doc/HACKING

   1
   2 0. The buildbot.
   3
   4   http://tor-buildbot.freehaven.net:8010/
   5
   6   - Down for unknown reasons, ioerror will look into this.
   7
   8 0.1. Useful command-lines that are non-trivial to reproduce but can
   9 help with tracking bugs or leaks.
  10
  11 dmalloc -l ~/dmalloc.log
  12 (run the commands it tells you)
  13 ./configure --with-dmalloc
  14
  15 valgrind --leak-check=yes --error-limit=no --show-reachable=yes src/or/tor
  16
  17 1. Coding conventions
  18
  19 1.0. Whitespace and C conformance
  20
  21   Invoke "make check-spaces" from time to time, so it can tell you about
  22   deviations from our C whitespace style.  Generally, we use:
  23     - Unix-style line endings
  24     - K&R-style indentation
  25     - No space before newlines
  26     - A blank line at the end of each file
  27     - Never more than one blank line in a row
  28     - Always spaces, never tabs
  29     - No more than 79-columns per line.
  30     - Two spaces per indent.
  31     - A space between control keywords and their corresponding paren
  32       "if (x)", "while (x)", and "switch (x)", never "if(x)", "while(x)", or
  33       "switch(x)".
  34     - A space between anything and an open brace.
  35     - No space between a function name and an opening paren. "puts(x)", not
  36       "puts (x)".
  37     - Function declarations at the start of the line.
  38
  39   We try hard to build without warnings everywhere.  In particular, if you're
  40   using gcc, you should invoke the configure script with the option
  41   "--enable-gcc-warnings".  This will give a bunch of extra warning flags to
  42   the compiler, and help us find divergences from our preferred C style.
  43
  44 1.0.1. Getting emacs to edit Tor source properly.
  45
  46   Hi, folks!  Nick here.  I like to put the following snippet in my .emacs
  47   file:
  48     (add-hook 'c-mode-hook
  49           (lambda ()
  50             (font-lock-mode 1)
  51             (set-variable 'show-trailing-whitespace t)
  52
  53             (let ((fname (expand-file-name (buffer-file-name))))
  54               (cond
  55                ((string-match "^/home/nickm/src/libevent" fname)
  56                 (set-variable 'indent-tabs-mode t)
  57                 (set-variable 'c-basic-offset 4)
  58                 (set-variable 'tab-width 4))
  59                ((string-match "^/home/nickm/src/tor" fname)
  60                 (set-variable 'indent-tabs-mode nil)
  61                 (set-variable 'c-basic-offset 2))
  62                ((string-match "^/home/nickm/src/openssl" fname)
  63                 (set-variable 'indent-tabs-mode t)
  64                 (set-variable 'c-basic-offset 8)
  65                 (set-variable 'tab-width 8))
  66             ))))
  67
  68   You'll note that it defaults to showing all trailing whitespace.  The
  69   "cond" test detects whether the file is one of a few C free software
  70   projects that I often edit, and sets up the indentation level and tab
  71   preferences to match what they want.
  72
  73   If you want to try this out, you'll need to change the filename regex
  74   patterns to match where you keep your Tor files.
  75
  76   If you *only* use emacs to edit Tor, you could always just say:
  77
  78     (add-hook 'c-mode-hook
  79           (lambda ()
  80             (font-lock-mode 1)
  81             (set-variable 'show-trailing-whitespace t)
  82             (set-variable 'indent-tabs-mode nil)
  83             (set-variable 'c-basic-offset 2)))
  84
  85   There is probably a better way to do this.  No, we are probably not going
  86   to clutter the files with emacs stuff.
  87
  88 1.1. Details
  89
  90   Use tor_malloc, tor_free, tor_strdup, and tor_gettimeofday instead of their
  91   generic equivalents.  (They always succeed or exit.)
  92
  93   You can get a full list of the compatibility functions that Tor provides
  94   by looking through src/common/util.h and src/common/compat.h.
  95
  96   Use 'INLINE' instead of 'inline', so that we work properly on Windows.
  97
  98 1.2. Calling and naming conventions
  99
 100   Whenever possible, functions should return -1 on error and 0 on success.
 101
 102   For multi-word identifiers, use lowercase words combined with
 103   underscores. (e.g., "multi_word_identifier").  Use ALL_CAPS for macros and
 104   constants.
 105
 106   Typenames should end with "_t".
 107
 108   Function names should be prefixed with a module name or object name.  (In
 109   general, code to manipulate an object should be a module with the same
 110   name as the object, so it's hard to tell which convention is used.)
 111
 112   Functions that do things should have imperative-verb names
 113   (e.g. buffer_clear, buffer_resize); functions that return booleans should
 114   have predicate names (e.g. buffer_is_empty, buffer_needs_resizing).
 115
 116 1.3. What To Optimize
 117
 118   Don't optimize anything if it's not in the critical path.  Right now,
 119   the critical path seems to be AES, logging, and the network itself.
 120   Feel free to do your own profiling to determine otherwise.
 121
 122 1.4. Log conventions
 123
 124   http://wiki.noreply.org/noreply/TheOnionRouter/TorFAQ#LogLevels
 125
 126   No error or warning messages should be expected during normal OR or OP
 127   operation.
 128
 129   If a library function is currently called such that failure always
 130   means ERR, then the library function should log WARN and let the caller
 131   log ERR.
 132
 133   [XXX Proposed convention: every message of severity INFO or higher should
 134   either (A) be intelligible to end-users who don't know the Tor source; or
 135   (B) somehow inform the end-users that they aren't expected to understand
 136   the message (perhaps with a string like "internal error").  Option (A) is
 137   to be preferred to option (B). -NM]
 138
 139 1.5. Doxygen
 140
 141   We use the 'doxygen' utility to generate documentation from our
 142   source code. Here's how to use it:
 143
 144   1. Begin every file that should be documented with
 145          /**
 146           * \file filename.c
 147           * \brief Short description of the file.
 148           **/
 149
 150      (Doxygen will recognize any comment beginning with /** as special.)
 151
 152   2. Before any function, structure, #define, or variable you want to
 153      document, add a comment of the form:
 154
 155         /** Describe the function's actions in imperative sentences.
 156          *
 157          * Use blank lines for paragraph breaks
 158          *   - and
 159          *   - hyphens
 160          *   - for
 161          *   - lists.
 162          *
 163          * Write <b>argument_names</b> in boldface.
 164          *
 165          * \code
 166          *     place_example_code();
 167          *     between_code_and_endcode_commands();
 168          * \endcode
 169          */
 170
 171   3. Make sure to escape the characters "<", ">", "\", "%" and "#" as "\<",
 172      "\>", "\\", "\%", and "\#".
 173
 174   4. To document structure members, you can use two forms:
 175
 176        struct foo {
 177          /** You can put the comment before an element; */
 178          int a;
 179          int b; /**< Or use the less-than symbol to put the comment
 180                  * after the element. */
 181        };
 182
 183   5. To generate documentation from the Tor source code, type:
 184
 185      $ doxygen -g
 186
 187      To generate a file called 'Doxyfile'.  Edit that file and run
 188      'doxygen' to generate the API documentation.
 189
 190   6. See the Doxygen manual for more information; this summary just
 191      scratches the surface.
 192
 193 2. Code notes
 194
 195 2.1. Dataflows
 196
 197 2.1.1. How Incoming data is handled
 198
 199 There are two paths for data arriving at Tor over the network: regular
 200 TCP data, and DNS.
 201
 202 2.1.1.1. TCP.
 203
 204 When Tor takes information over the network, it uses the functions
 205 read_to_buf() and read_to_buf_tls() in buffers.c.  These read from a
 206 socket or an SSL* into a buffer_t, which is an mbuf-style linkedlist
 207 of memory chunks.
 208
 209 read_to_buf() and read_to_buf_tls() are called only from
 210 connection_read_to_buf() in connection.c.  It takes a connection_t
 211 pointer, and reads data into it over the network, up to the
 212 connection's current bandwidth limits.  It places that data into the
 213 "inbuf" field of the connection, and then:
 214   - Adjusts the connection's want-to-read/want-to-write status as
 215     appropriate.
 216   - Increments the read and written counts for the connection as
 217     appropriate.
 218   - Adjusts bandwidth buckets as appropriate.
 219
 220 connection_read_to_buf() is called only from connection_handle_read().
 221 The connection_handle_read() function is called whenever libevent
 222 decides (based on select, poll, epoll, kqueue, etc) that there is data
 223 to read from a connection.  If any data is read,
 224 connection_handle_read() calls connection_process_inbuf() to see if
 225 any of the data can be processed.  If the connection was closed,
 226 connection_handle_read() calls connection_reached_eof().
 227
 228 Connection_process_inbuf() and connection_reached_eof() both dispatch
 229 based on the connection type to determine what to do with the data
 230 that's just arrived on the connection's inbuf field.  Each type of
 231 connection has its own version of these functions.  For example,
 232 directory connections process incoming data in
 233 connection_dir_process_inbuf(), while OR connections process incoming
 234 data in connection_or_process_inbuf().  These
 235 connection_*_process_inbuf() functions extract data from the
 236 connection's inbuf field (a buffer_t), using functions from buffers.c.
 237 Some of these accessor functions are straightforward data extractors
 238 (like fetch_from_buf()); others do protocol-specific parsing.
 239
 240
 241 2.1.1.2. DNS
 242
 243 Tor launches (and optionally accepts) DNS requests using the code in
 244 eventdns.c, which is a copy of libevent's evdns.c.  (We don't use
 245 libevent's version because it is not yet in the versions of libevent
 246 all our users have.)  DNS replies are read in nameserver_read();
 247 DNS queries are read in server_port_read().