[tor-commits] [torspec/master] Improve documentation for ADDRMAP controller events

[nickm at torproject.org]

commit 12ce6bf77d5ab104598c032749f61188573b006d
Author: Nick Mathewson <nickm at torproject.org>
Date:   Fri Nov 23 11:38:44 2012 -0500

    Improve documentation for ADDRMAP controller events
    
    based on a patch from atagar and comments by rransom.
    
    Fixes 7515.
---
 control-spec.txt |   19 ++++++++++++-------
 1 files changed, 12 insertions(+), 7 deletions(-)

diff --git a/control-spec.txt b/control-spec.txt
index cc82dca..b6ae495 100644
--- a/control-spec.txt
+++ b/control-spec.txt
@@ -1546,26 +1546,31 @@
 
 4.1.7. New Address mapping
 
+  These events are generated when a new address mapping is entered in
+  Tor's address map cache, or when the answer for a RESOLVE command is
+  found.  Entries can be created by a successful or failed DNS lookup,
+  a successful or failed connection attempt, a RESOLVE command,
+  a MAPADDRESS command, or the AutomapHostsOnResolve feature.
+
   Syntax:
      "650" SP "ADDRMAP" SP Address SP NewAddress SP Expiry
-       [SP Error] [SP UTCExpiry] CRLF
+       [SP "error=" ErrorCode] [SP "EXPIRES=" UTCExpiry] CRLF
 
      NewAddress = Address / "<error>"
      Expiry = DQUOTE ISOTime DQUOTE / "NEVER"
 
-     Error = "error=" ErrorCode
-     ErrorCode = XXXX
-     UTCExpiry = "EXPIRES=" DQUOTE IsoTime DQUOTE
+     ErrorCode = "yes" / "internal" / "Unable to launch resolve request"
+     UTCExpiry = DQUOTE IsoTime DQUOTE
 
   Error and UTCExpiry are only provided if extended events are enabled.
+  The values for Error are mostly useless.  Future values will be
+  chosen to match 1*(ALNUM / "_"); the "Unable to launch resolve request"
+  value is a bug in Tor before 0.2.4.7-alpha.
 
   Expiry is expressed as the local time (rather than UTC).  This is a bug,
   left in for backward compatibility; new code should look at UTCExpiry
   instead.  (If Expiry is "NEVER", UTCExpiry is omitted.)
 
-  These events are generated when a new address mapping is entered in the
-  cache, or when the answer for a RESOLVE command is found.
-
 4.1.8. Descriptors uploaded to us in our role as authoritative dirserver
 
   Syntax: