2 @brief lib: low-level functionality.
4 The "lib" directory contains low-level functionality. In general, this
5 code is not necessarily Tor-specific, but is instead possibly useful for
8 The modules in `lib` are currently well-factored: each one depends
9 only on lower-level modules. You can see an up-to-date list of the
10 modules, sorted from lowest to highest level, by running
11 `./scripts/maint/practracker/includes.py --toposort`.
13 As of this writing, the library modules are (from lowest to highest
16 - \refdir{lib/cc} -- Macros for managing the C compiler and
19 - \refdir{lib/version} -- Holds the current version of Tor.
21 - \refdir{lib/testsupport} -- Helpers for making
22 test-only code, and test mocking support.
24 - \refdir{lib/defs} -- Lowest-level constants.
26 - \refdir{lib/subsys} -- Types used for declaring a
27 "subsystem". (_A subsystem is a module with support for initialization,
28 shutdown, configuration, and so on._)
30 - \refdir{lib/conf} -- For declaring configuration options.
32 - \refdir{lib/arch} -- For handling differences in CPU
35 - \refdir{lib/err} -- Lowest-level error handling code.
37 - \refdir{lib/malloc} -- Memory management.
40 - \refdir{lib/intmath} -- Integer mathematics.
42 - \refdir{lib/fdio} -- For
43 reading and writing n file descriptors.
45 - \refdir{lib/lock} -- Simple locking support.
46 (_Lower-level than the rest of the threading code._)
48 - \refdir{lib/ctime} -- Constant-time code to avoid
51 - \refdir{lib/string} -- Low-level string manipulation.
53 - \refdir{lib/wallclock} --
54 For inspecting and manipulating the current (UTC) time.
56 - \refdir{lib/osinfo} -- For inspecting the OS version
59 - \refdir{lib/smartlist_core} -- The bare-bones
60 pieces of our dynamic array ("smartlist") implementation.
62 - \refdir{lib/log} -- Log messages to files, syslogs, etc.
64 - \refdir{lib/container} -- General purpose containers,
65 including dynamic arrays ("smartlists"), hashtables, bit arrays,
68 - \refdir{lib/trace} -- A general-purpose API
69 function-tracing functionality Tor. (_Currently not much used._)
71 - \refdir{lib/thread} -- Mid-level Threading.
73 - \refdir{lib/term} -- Terminal manipulation
74 (like reading a password from the user).
76 - \refdir{lib/memarea} -- A fast
77 "arena" style allocator, where the data is freed all at once.
79 - \refdir{lib/encoding} -- Encoding
80 data in various formats, datatypes, and transformations.
82 - \refdir{lib/dispatch} -- A general-purpose in-process
83 message delivery system.
85 - \refdir{lib/sandbox} -- Our Linux seccomp2 sandbox
88 - \refdir{lib/pubsub} -- A publish/subscribe message passing system.
90 - \refdir{lib/fs} -- Files, filenames, directories, etc.
92 - \refdir{lib/confmgt} -- Parse, encode, and manipulate onfiguration files.
94 - \refdir{lib/crypt_ops} -- Cryptographic operations.
96 - \refdir{lib/meminfo} -- Functions for inspecting our
97 memory usage, if the malloc implementation exposes that to us.
99 - \refdir{lib/time} -- Higher level time functions, including
100 fine-gained and monotonic timers.
102 - \refdir{lib/math} -- Floating-point mathematical utilities.
104 - \refdir{lib/buf} -- An efficient byte queue.
106 - \refdir{lib/net} -- Networking code, including address
107 manipulation, compatibility wrappers, etc.
109 - \refdir{lib/compress} -- Wraps several compression libraries.
111 - \refdir{lib/geoip} -- IP-to-country mapping.
113 - \refdir{lib/tls} -- TLS library wrappers.
115 - \refdir{lib/evloop} -- Low-level event-loop.
117 - \refdir{lib/process} -- Launch and manage subprocesses.
119 ### What belongs in lib?
121 In general, if you can imagine some program wanting the functionality
122 you're writing, even if that program had nothing to do with Tor, your
123 functionality belongs in lib.
125 If it falls into one of the existing "lib" categories, your
126 functionality belongs in lib.
128 If you are using platform-specific `ifdef`s to manage compatibility
129 issues among platforms, you should probably consider whether you can
130 put your code into lib.