4 http://tor-buildbot.freehaven.net:8010/
6 - Down for unknown reasons, ioerror will look into this.
8 0.1. Useful command-lines that are non-trivial to reproduce but can
9 help with tracking bugs or leaks.
11 dmalloc -l ~/dmalloc.log
12 (run the commands it tells you)
13 ./configure --with-dmalloc
15 valgrind --leak-check=yes --error-limit=no --show-reachable=yes src/or/tor
19 1.0. Whitespace and C conformance
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
34 - A space between anything and an open brace.
35 - No space between a function name and an opening paren. "puts(x)", not
37 - Function declarations at the start of the line.
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.
44 1.0.1. Getting emacs to edit Tor source properly.
46 Hi, folks! Nick here. I like to put the following snippet in my .emacs
48 (add-hook 'c-mode-hook
51 (set-variable 'show-trailing-whitespace t)
53 (let ((fname (expand-file-name (buffer-file-name))))
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))
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.
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.
76 If you *only* use emacs to edit Tor, you could always just say:
78 (add-hook 'c-mode-hook
81 (set-variable 'show-trailing-whitespace t)
82 (set-variable 'indent-tabs-mode nil)
83 (set-variable 'c-basic-offset 2)))
85 There is probably a better way to do this. No, we are probably not going
86 to clutter the files with emacs stuff.
90 Use tor_malloc, tor_free, tor_strdup, and tor_gettimeofday instead of their
91 generic equivalents. (They always succeed or exit.)
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.
96 Use 'INLINE' instead of 'inline', so that we work properly on Windows.
98 1.2. Calling and naming conventions
100 Whenever possible, functions should return -1 on error and 0 on success.
102 For multi-word identifiers, use lowercase words combined with
103 underscores. (e.g., "multi_word_identifier"). Use ALL_CAPS for macros and
106 Typenames should end with "_t".
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.)
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).
116 1.3. What To Optimize
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.
124 http://wiki.noreply.org/noreply/TheOnionRouter/TorFAQ#LogLevels
126 No error or warning messages should be expected during normal OR or OP
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
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]
141 We use the 'doxygen' utility to generate documentation from our
142 source code. Here's how to use it:
144 1. Begin every file that should be documented with
147 * \brief Short description of the file.
150 (Doxygen will recognize any comment beginning with /** as special.)
152 2. Before any function, structure, #define, or variable you want to
153 document, add a comment of the form:
155 /** Describe the function's actions in imperative sentences.
157 * Use blank lines for paragraph breaks
163 * Write <b>argument_names</b> in boldface.
166 * place_example_code();
167 * between_code_and_endcode_commands();
171 3. Make sure to escape the characters "<", ">", "\", "%" and "#" as "\<",
172 "\>", "\\", "\%", and "\#".
174 4. To document structure members, you can use two forms:
177 /** You can put the comment before an element; */
179 int b; /**< Or use the less-than symbol to put the comment
180 * after the element. */
183 5. To generate documentation from the Tor source code, type:
187 To generate a file called 'Doxyfile'. Edit that file and run
188 'doxygen' to generate the API documentation.
190 6. See the Doxygen manual for more information; this summary just
191 scratches the surface.
197 2.1.1. How Incoming data is handled
199 There are two paths for data arriving at Tor over the network: regular
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
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
216 - Increments the read and written counts for the connection as
218 - Adjusts bandwidth buckets as appropriate.
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().
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.
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().