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
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
|
## Library code in Tor.
Most of Tor's utility code is in modules in the `src/lib` subdirectory. In
general, this code is not necessarily Tor-specific, but is instead possibly
useful for other applications.
This code includes:
* Compatibility wrappers, to provide a uniform API across different
platforms.
* Library wrappers, to provide a tor-like API over different libraries
that Tor uses for things like compression and cryptography.
* Containers, to implement some general-purpose data container types.
The modules in `src/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):
* `lib/cc` -- Macros for managing the C compiler and
language. Includes macros for improving compatibility and clarity
across different C compilers.
* `lib/version` -- Holds the current version of Tor.
* `lib/testsupport` -- Helpers for making test-only code and test
mocking support.
* `lib/defs` -- Lowest-level constants used in many places across the
code.
* `lib/subsys` -- Types used for declaring a "subsystem". A subsystem
is a module with support for initialization, shutdown,
configuration, and so on.
* `lib/conf` -- Types and macros used for declaring configuration
options.
* `lib/arch` -- Compatibility functions and macros for handling
differences in CPU architecture.
* `lib/err` -- Lowest-level error handling code: responsible for
generating stack traces, handling raw assertion failures, and
otherwise reporting problems that might not be safe to report
via the regular logging module.
* `lib/malloc` -- Wrappers and utilities for memory management.
* `lib/intmath` -- Utilities for integer mathematics.
* `lib/fdio` -- Utilities and compatibility code for reading and
writing data on file descriptors (and on sockets, for platforms
where a socket is not a kind of fd).
* `lib/lock` -- Compatibility code for declaring and using locks.
Lower-level than the rest of the threading code.
* `lib/ctime` -- Constant-time implementations for data comparison
and table lookup, used to avoid timing side-channels from standard
implementations of memcmp() and so on.
* `lib/string` -- Low-level compatibility wrappers and utility
functions for string manipulation.
* `lib/wallclock` -- Compatibility and utility functions for
inspecting and manipulating the current (UTC) time.
* `lib/osinfo` -- Functions for inspecting the version and
capabilities of the operating system.
* `lib/smartlist_core` -- The bare-bones pieces of our dynamic array
("smartlist") implementation. There are higher-level pieces, but
these ones are used by (and therefore cannot use) the logging code.
* `lib/log` -- Implements the logging system used by all higher-level
Tor code. You can think of this as the logical "midpoint" of the
library code: much of the higher-level code is higher-level
_because_ it uses the logging module, and much of the lower-level
code is specifically written to avoid having to log, because the
logging module depends on it.
* `lib/container` -- General purpose containers, including dynamic arrays
("smartlists"), hashtables, bit arrays, weak-reference-like "handles",
bloom filters, and a bit more.
* `lib/trace` -- A general-purpose API for introducing
function-tracing functionality into Tor. Currently not much used.
* `lib/thread` -- Threading compatibility and utility functionality,
other than low-level locks (which are in `lib/lock`) and
workqueue/threadpool code (which belongs in `lib/evloop`).
* `lib/term` -- Code for terminal manipulation functions (like
reading a password from the user).
* `lib/memarea` -- A data structure for a fast "arena" style allocator,
where the data is freed all at once. Used for parsing.
* `lib/encoding` -- Implementations for encoding data in various
formats, datatypes, and transformations.
* `lib/dispatch` -- A general-purpose in-process message delivery
system. Used by `lib/pubsub` to implement our inter-module
publish/subscribe system.
* `lib/sandbox` -- Our Linux seccomp2 sandbox implementation.
* `lib/pubsub` -- Code and macros to implement our publish/subscribe
message passing system.
* `lib/fs` -- Utility and compatibility code for manipulating files,
filenames, directories, and so on.
* `lib/confmgt` -- Code to parse, encode, and manipulate our
configuration files, state files, and so forth.
* `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.
* `lib/meminfo` -- Functions for inspecting our memory usage, if the
malloc implementation exposes that to us.
* `lib/time` -- Higher level time functions, including fine-gained and
monotonic timers.
* `lib/math` -- Floating-point mathematical utilities, including
compatibility code, and probability distributions.
* `lib/buf` -- A general purpose queued buffer implementation,
similar to the BSD kernel's "mbuf" structure.
* `lib/net` -- Networking code, including address manipulation,
compatibility wrappers,
* `lib/compress` -- A compatibility wrapper around several
compression libraries, currently including zlib, zstd, and lzma.
* `lib/geoip` -- Utilities to manage geoip (IP to country) lookups
and formats.
* `lib/tls` -- Compatibility wrappers around the library (NSS or
OpenSSL, depending on configuration) that Tor uses to implement the
TLS link security protocol.
* `lib/evloop` -- Tools to manage the event loop and related
functionality, in order to implement asynchronous networking,
timers, periodic events, and other scheduling tasks.
* `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.
|
