1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
|
/**
@dir /lib
@brief lib: low-level functionality.
The "lib" directory contains low-level functionality. In general, this
code is not necessarily Tor-specific, but is instead possibly useful for
other applications.
The modules in `lib` are currently well-factored: each one depends
only on lower-level modules. You can see an up-to-date list of the
modules, sorted from lowest to highest level, by running
`./scripts/maint/practracker/includes.py --toposort`.
As of this writing, the library modules are (from lowest to highest
level):
- \refdir{lib/cc} -- Macros for managing the C compiler and
language.
- \refdir{lib/version} -- Holds the current version of Tor.
- \refdir{lib/testsupport} -- Helpers for making
test-only code, and test mocking support.
- \refdir{lib/defs} -- Lowest-level constants.
- \refdir{lib/subsys} -- Types used for declaring a
"subsystem". (_A subsystem is a module with support for initialization,
shutdown, configuration, and so on._)
- \refdir{lib/conf} -- For declaring configuration options.
- \refdir{lib/arch} -- For handling differences in CPU
architecture.
- \refdir{lib/err} -- Lowest-level error handling code.
- \refdir{lib/malloc} -- Memory management.
management.
- \refdir{lib/intmath} -- Integer mathematics.
- \refdir{lib/fdio} -- For
reading and writing n file descriptors.
- \refdir{lib/lock} -- Simple locking support.
(_Lower-level than the rest of the threading code._)
- \refdir{lib/ctime} -- Constant-time code to avoid
side-channels.
- \refdir{lib/string} -- Low-level string manipulation.
- \refdir{lib/wallclock} --
For inspecting and manipulating the current (UTC) time.
- \refdir{lib/osinfo} -- For inspecting the OS version
and capabilities.
- \refdir{lib/smartlist_core} -- The bare-bones
pieces of our dynamic array ("smartlist") implementation.
- \refdir{lib/log} -- Log messages to files, syslogs, etc.
- \refdir{lib/container} -- General purpose containers,
including dynamic arrays ("smartlists"), hashtables, bit arrays,
etc.
- \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 \ref
src/lib/lock "lib/lock") and workqueue/threadpool code (which belongs
in \refdir{lib/evloop}
- \refdir{lib/term} -- Terminal manipulation
(like reading a password from the user).
- \refdir{lib/memarea} -- A fast
"arena" style allocator, where the data is freed all at once.
- \refdir{lib/encoding} -- Encoding
data in various formats, datatypes, and transformations.
- \refdir{lib/dispatch} -- A general-purpose in-process
message delivery system.
- \refdir{lib/sandbox} -- Our Linux seccomp2 sandbox
implementation.
- \refdir{lib/pubsub} -- Code and macros to implement our
publish/subscribe message passing system.
- \refdir{lib/fs} -- Utility and compatibility code for
manipulating files, filenames, directories, and so on.
- \refdir{lib/confmgt} -- Code to parse, encode, and
manipulate our configuration files, state files, and so forth.
- \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/meminfo} -- Functions for inspecting our
memory usage, if the malloc implementation exposes that to us.
- \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/buf} -- A general purpose queued buffer
implementation, similar to the BSD kernel's "mbuf" structure.
- \refdir{lib/net} -- Networking code, including address
manipulation, compatibility wrappers,
- \refdir{lib/compress} -- A compatibility wrapper around
several compression libraries, currently including zlib, zstd, and lzma.
- \refdir{lib/geoip} -- Utilities to manage geoip (IP to
country) lookups and formats.
- \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/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/process} -- Utilities and compatibility code
to launch and manage subprocesses.
### What belongs in lib?
In general, if you can imagine some program wanting the functionality
you're writing, even if that program had nothing to do with Tor, your
functionality belongs in lib.
If it falls into one of the existing "lib" categories, your
functionality belongs in lib.
If you are using platform-specific `ifdef`s to manage compatibility
issues among platforms, you should probably consider whether you can
put your code into lib.
**/
|
