mirror of
https://gitlab.torproject.org/tpo/core/tor.git
synced 2024-12-06 19:41:15 +01:00
Nick Mathewson
9b13191192
This commit was generated with:
find src -name '*.dox' |xargs perl -i -pe 's{\\ref src/(\S+) \"\S+}{\\refdir{$1}};'
152 lines
5.2 KiB
Plaintext
152 lines
5.2 KiB
Plaintext
/**
|
|
@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.
|
|
|
|
**/
|