commit 76e8effc7b8e747cd34188a5a27e6d792a66ba7e Author: Nick Mathewson <nickm@torproject.org> Date: Mon Nov 4 11:51:38 2019 -0500 Doxygen: document the rest of the directories in lib. (This copies documentation from doc/HACKING/design, and edits for concisensess and clarity.) --- src/lib/buf/lib_buf.dox | 13 ++++++++++- src/lib/compress/lib_compress.dox | 6 ++++- src/lib/confmgt/lib_confmgt.dox | 7 +++++- src/lib/crypt_ops/lib_crypt_ops.dox | 10 ++++++++- src/lib/evloop/lib_evloop.dox | 7 +++++- src/lib/fdio/lib_fdio.dox | 2 +- src/lib/fs/lib_fs.dox | 9 +++++++- src/lib/geoip/lib_geoip.dox | 3 ++- src/lib/intmath/lib_intmath.dox | 2 +- src/lib/lib.dox | 44 +++++++++++-------------------------- src/lib/math/lib_math.dox | 6 ++++- src/lib/memarea/lib_memarea.dox | 2 +- src/lib/meminfo/lib_meminfo.dox | 5 ++++- src/lib/net/lib_net.dox | 6 ++++- src/lib/process/lib_process.dox | 2 +- src/lib/pubsub/lib_pubsub.dox | 14 +++++++++++- src/lib/sandbox/lib_sandbox.dox | 2 +- src/lib/term/lib_term.dox | 2 +- src/lib/thread/lib_thread.dox | 7 +++++- src/lib/time/lib_time.dox | 9 +++++++- src/lib/tls/lib_tls.dox | 11 +++++++++- src/lib/wallclock/lib_wallclock.dox | 3 ++- 22 files changed, 120 insertions(+), 52 deletions(-) diff --git a/src/lib/buf/lib_buf.dox b/src/lib/buf/lib_buf.dox index 9caaba07f..a2ac23ee4 100644 --- a/src/lib/buf/lib_buf.dox +++ b/src/lib/buf/lib_buf.dox @@ -1,4 +1,15 @@ /** @dir /lib/buf -@brief lib/buf +@brief lib/buf: An efficient byte queue. + +This module defines the buf_t type, which is used throughout our networking +code. The implementation is a singly-linked queue of buffer chunks, similar +to the BSD kernel's +["mbuf"](https://www.freebsd.org/cgi/man.cgi?query=mbuf&sektion=9) structure. + +The buf_t type is also reasonable for use in constructing long strings. + +See \refdir{lib/net} for networking code that uses buf_t, and +\refdir{lib/tls} for cryptographic code that uses buf_t. + **/ diff --git a/src/lib/compress/lib_compress.dox b/src/lib/compress/lib_compress.dox index b1b090235..599126901 100644 --- a/src/lib/compress/lib_compress.dox +++ b/src/lib/compress/lib_compress.dox @@ -1,4 +1,8 @@ /** @dir /lib/compress -@brief lib/compress +@brief lib/compress: Wraps several compression libraries + +Currently supported are zlib (mandatory), zstd (optional), and lzma +(optional). + **/ diff --git a/src/lib/confmgt/lib_confmgt.dox b/src/lib/confmgt/lib_confmgt.dox index 86cb04e84..d18fa304c 100644 --- a/src/lib/confmgt/lib_confmgt.dox +++ b/src/lib/confmgt/lib_confmgt.dox @@ -1,4 +1,9 @@ /** @dir /lib/confmgt -@brief lib/confmgt +@brief lib/confmgt: Parse, encode, manipulate configuration files. + +This logic is used in common by our state files (statefile.c) and +configuration files (config.c) to manage a set of named, typed fields, +reading and writing them to disk and to the controller. + **/ diff --git a/src/lib/crypt_ops/lib_crypt_ops.dox b/src/lib/crypt_ops/lib_crypt_ops.dox index 0c3e4d7c3..d856d93be 100644 --- a/src/lib/crypt_ops/lib_crypt_ops.dox +++ b/src/lib/crypt_ops/lib_crypt_ops.dox @@ -1,4 +1,12 @@ /** @dir /lib/crypt_ops -@brief lib/crypt_ops +@brief lib/crypt_ops: Cryptographic operations. + +This module contains wrappers around the cryptographic libraries that we +support, and implementations for some higher-level cryptographic +constructions that we use. + +It wraps our two major cryptographic backends (OpenSSL or NSS, as configured +by the user), and also wraps other cryptographic code in src/ext. + **/ diff --git a/src/lib/evloop/lib_evloop.dox b/src/lib/evloop/lib_evloop.dox index f60f41968..52fcf6775 100644 --- a/src/lib/evloop/lib_evloop.dox +++ b/src/lib/evloop/lib_evloop.dox @@ -1,4 +1,9 @@ /** @dir /lib/evloop -@brief lib/evloop +@brief lib/evloop: Low-level event loop. + +This modules has tools to manage the [libevent](https://libevent.org/) event +loop and related functionality, in order to implement asynchronous +networking, timers, periodic events, and other scheduling tasks. + **/ diff --git a/src/lib/fdio/lib_fdio.dox b/src/lib/fdio/lib_fdio.dox index 2615b9791..9e2fda617 100644 --- a/src/lib/fdio/lib_fdio.dox +++ b/src/lib/fdio/lib_fdio.dox @@ -1,6 +1,6 @@ /** @dir /lib/fdio -@brief lib/fdio Code to read/write on file descriptors. +@brief lib/fdio: Code to read/write on file descriptors. (This module also handles sockets, on platforms where a socket is not a kind of fd.) diff --git a/src/lib/fs/lib_fs.dox b/src/lib/fs/lib_fs.dox index 33ff16928..4466250bb 100644 --- a/src/lib/fs/lib_fs.dox +++ b/src/lib/fs/lib_fs.dox @@ -1,4 +1,11 @@ /** @dir /lib/fs -@brief lib/fs +@brief lib/fs: Files, filenames, directories, etc. + +This module is mostly a set of compatibility wrappers around +operating-system-specific filesystem access. + +It also contains a set of convenience functions for safely writing to files, +creating directories, and so on. + **/ diff --git a/src/lib/geoip/lib_geoip.dox b/src/lib/geoip/lib_geoip.dox index 454dcb687..da1123640 100644 --- a/src/lib/geoip/lib_geoip.dox +++ b/src/lib/geoip/lib_geoip.dox @@ -1,4 +1,5 @@ /** @dir /lib/geoip -@brief lib/geoip +@brief lib/geoip: IP-to-country mapping + **/ diff --git a/src/lib/intmath/lib_intmath.dox b/src/lib/intmath/lib_intmath.dox index 33fa0f02b..e9b704470 100644 --- a/src/lib/intmath/lib_intmath.dox +++ b/src/lib/intmath/lib_intmath.dox @@ -1,4 +1,4 @@ /** @dir /lib/intmath -@brief lib/intmath Integer mathematics. +@brief lib/intmath: Integer mathematics. **/ diff --git a/src/lib/lib.dox b/src/lib/lib.dox index da6f7b2d2..fdf2c4768 100644 --- a/src/lib/lib.dox +++ b/src/lib/lib.dox @@ -69,10 +69,7 @@ level): - \refdir{lib/trace} -- A general-purpose API function-tracing functionality Tor. (_Currently not much used._) - - \refdir{lib/thread} -- Threading compatibility and utility - functionality, other than low-level locks (which are in - \refdir{lib/lock} and workqueue/threadpool code (which belongs - in \refdir{lib/evloop}.) + - \refdir{lib/thread} -- Mid-level Threading. - \refdir{lib/term} -- Terminal manipulation (like reading a password from the user). @@ -89,19 +86,13 @@ level): - \refdir{lib/sandbox} -- Our Linux seccomp2 sandbox implementation. - - \refdir{lib/pubsub} -- Code and macros to implement our - publish/subscribe message passing system. + - \refdir{lib/pubsub} -- A publish/subscribe message passing system. - - \refdir{lib/fs} -- Utility and compatibility code for - manipulating files, filenames, directories, and so on. + - \refdir{lib/fs} -- Files, filenames, directories, etc. - - \refdir{lib/confmgt} -- Code to parse, encode, and - manipulate our configuration files, state files, and so forth. + - \refdir{lib/confmgt} -- Parse, encode, and manipulate onfiguration files. - - \refdir{lib/crypt_ops} -- Cryptographic operations. This - module contains wrappers around the cryptographic libraries that we - support, and implementations for some higher-level cryptographic - constructions that we use. + - \refdir{lib/crypt_ops} -- Cryptographic operations. - \refdir{lib/meminfo} -- Functions for inspecting our memory usage, if the malloc implementation exposes that to us. @@ -109,31 +100,22 @@ level): - \refdir{lib/time} -- Higher level time functions, including fine-gained and monotonic timers. - - \refdir{lib/math} -- Floating-point mathematical utilities, - including compatibility code, and probability distributions. + - \refdir{lib/math} -- Floating-point mathematical utilities. - - \refdir{lib/buf} -- A general purpose queued buffer - implementation, similar to the BSD kernel's "mbuf" structure. + - \refdir{lib/buf} -- An efficient byte queue. - \refdir{lib/net} -- Networking code, including address - manipulation, compatibility wrappers, + manipulation, compatibility wrappers, etc. - - \refdir{lib/compress} -- A compatibility wrapper around - several compression libraries, currently including zlib, zstd, and lzma. + - \refdir{lib/compress} -- Wraps several compression libraries. - - \refdir{lib/geoip} -- Utilities to manage geoip (IP to - country) lookups and formats. + - \refdir{lib/geoip} -- IP-to-country mapping. - - \refdir{lib/tls} -- Compatibility wrappers around the library - (NSS or OpenSSL, depending on configuration) that Tor uses to implement - the TLS link security protocol. + - \refdir{lib/tls} -- TLS library wrappers. - - \refdir{lib/evloop} -- Tools to manage the event loop and - related functionality, in order to implement asynchronous networking, - timers, periodic events, and other scheduling tasks. + - \refdir{lib/evloop} -- Low-level event-loop. - - \refdir{lib/process} -- Utilities and compatibility code - to launch and manage subprocesses. + - \refdir{lib/process} -- Launch and manage subprocesses. ### What belongs in lib? diff --git a/src/lib/math/lib_math.dox b/src/lib/math/lib_math.dox index 0073731dc..f20d7092b 100644 --- a/src/lib/math/lib_math.dox +++ b/src/lib/math/lib_math.dox @@ -1,4 +1,8 @@ /** @dir /lib/math -@brief lib/math +@brief lib/math: Floating-point math utilities. + +This module includes a bunch of floating-point compatibility code, and +implementations for several probability distributions. + **/ diff --git a/src/lib/memarea/lib_memarea.dox b/src/lib/memarea/lib_memarea.dox index eaca28604..9a7c8c4b2 100644 --- a/src/lib/memarea/lib_memarea.dox +++ b/src/lib/memarea/lib_memarea.dox @@ -1,6 +1,6 @@ /** @dir /lib/memarea -@brief lib/memarea A fast arena-style allocator. +@brief lib/memarea: A fast arena-style allocator. This module has a fast "arena" style allocator, where memory is freed all at once. This kind of allocation is very fast and avoids fragmentation, at the diff --git a/src/lib/meminfo/lib_meminfo.dox b/src/lib/meminfo/lib_meminfo.dox index 433d6859e..b57e60525 100644 --- a/src/lib/meminfo/lib_meminfo.dox +++ b/src/lib/meminfo/lib_meminfo.dox @@ -1,4 +1,7 @@ /** @dir /lib/meminfo -@brief lib/meminfo +@brief lib/meminfo: Inspecting malloc() usage. + +Only available when malloc() provides mallinfo() or something similar. + **/ diff --git a/src/lib/net/lib_net.dox b/src/lib/net/lib_net.dox index ca3c56a94..b4c00405d 100644 --- a/src/lib/net/lib_net.dox +++ b/src/lib/net/lib_net.dox @@ -1,4 +1,8 @@ /** @dir /lib/net -@brief lib/net +@brief lib/net: Low-level network-related code. + +This module includes address manipulation, compatibility wrappers, +convenience functions, and so on. + **/ diff --git a/src/lib/process/lib_process.dox b/src/lib/process/lib_process.dox index 9059d6666..723c9f193 100644 --- a/src/lib/process/lib_process.dox +++ b/src/lib/process/lib_process.dox @@ -1,4 +1,4 @@ /** @dir /lib/process -@brief lib/process +@brief lib/process: Launch and manage subprocesses. **/ diff --git a/src/lib/pubsub/lib_pubsub.dox b/src/lib/pubsub/lib_pubsub.dox index 3fd026cc0..c03366012 100644 --- a/src/lib/pubsub/lib_pubsub.dox +++ b/src/lib/pubsub/lib_pubsub.dox @@ -1,4 +1,16 @@ /** @dir /lib/pubsub -@brief lib/pubsub +@brief lib/pubsub: Publish-subscribe message passing. + +This module wraps the \refdir{lib/dispatch} module, to provide a more +ergonomic and type-safe approach to message passing. + +In general, we favor this mechanism for cases where higher-level modules +need to be notified when something happens in lower-level modules. (The +alternative would be calling up from the lower-level modules, which +would be error-prone; or maintaining lists of function-pointers, which +would be clumsy and tend to complicate the call graph.) + +See pubsub.c for more information. + **/ diff --git a/src/lib/sandbox/lib_sandbox.dox b/src/lib/sandbox/lib_sandbox.dox index 91d056d46..48eddac68 100644 --- a/src/lib/sandbox/lib_sandbox.dox +++ b/src/lib/sandbox/lib_sandbox.dox @@ -1,6 +1,6 @@ /** @dir /lib/sandbox -@brief lib/sandbox Linux seccomp2-based sandbox. +@brief lib/sandbox: Linux seccomp2-based sandbox. This module uses Linux's seccomp2 facility via the [`libseccomp` library](https://github.com/seccomp/libseccomp), to restrict diff --git a/src/lib/term/lib_term.dox b/src/lib/term/lib_term.dox index d6010cb69..3bf2f960a 100644 --- a/src/lib/term/lib_term.dox +++ b/src/lib/term/lib_term.dox @@ -1,4 +1,4 @@ /** @dir /lib/term -@brief lib/term +@brief lib/term: Terminal operations (password input). **/ diff --git a/src/lib/thread/lib_thread.dox b/src/lib/thread/lib_thread.dox index b1e24d824..2773aa009 100644 --- a/src/lib/thread/lib_thread.dox +++ b/src/lib/thread/lib_thread.dox @@ -1,4 +1,9 @@ /** @dir /lib/thread -@brief lib/thread +@brief lib/thread: Mid-level threading. + +This module contains compatibility and convenience code for multithreading, +except for low-level locks (which are in \refdir{lib/lock} and +workqueue/threadpool code (which belongs in \refdir{lib/evloop}.) + **/ diff --git a/src/lib/time/lib_time.dox b/src/lib/time/lib_time.dox index 8e1e30859..b76a31fb9 100644 --- a/src/lib/time/lib_time.dox +++ b/src/lib/time/lib_time.dox @@ -1,4 +1,11 @@ /** @dir /lib/time -@brief lib/time +@brief lib/time: Higher-level time functions + +This includes both fine-grained timers and monotonic timers, along with +wrappers for them to try to improve efficiency. + +For "what time is it" in UTC, see \refdir{lib/wallclock}. For parsing and +encoding times and dates, see \refdir{lib/encoding}. + **/ diff --git a/src/lib/tls/lib_tls.dox b/src/lib/tls/lib_tls.dox index 9558687f6..f0dba269e 100644 --- a/src/lib/tls/lib_tls.dox +++ b/src/lib/tls/lib_tls.dox @@ -1,4 +1,13 @@ /** @dir /lib/tls -@brief lib/tls +@brief lib/tls: TLS library wrappers + +This module has compatibility wrappers around the library (NSS or OpenSSL, +depending on configuration) that Tor uses to implement the TLS link security +protocol. + +It also implements the logic for some legacy TLS protocol usage we used to +support in old versions of Tor, involving conditional delivery of certificate +chains (v1 link protocol) and conditional renegotiation (v2 link protocol). + **/ diff --git a/src/lib/wallclock/lib_wallclock.dox b/src/lib/wallclock/lib_wallclock.dox index 69dff85b5..7d43fa612 100644 --- a/src/lib/wallclock/lib_wallclock.dox +++ b/src/lib/wallclock/lib_wallclock.dox @@ -7,6 +7,7 @@ world agree it is?" Generally, if you want something derived from UTC, this is the module for you. For versions of the time that are more local, more monotonic, or more -accurate, see \refdir{lib/time} +accurate, see \refdir{lib/time}. For parsing and encoding times and dates, +see \refdir{lib/encoding}. **/