src/lib/lib.md

   1 @dir /lib
   2 @brief lib: low-level functionality.
   3
   4 The "lib" directory contains low-level functionality.  In general, this
   5 code is not necessarily Tor-specific, but is instead possibly useful for
   6 other applications.
   7
   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`.
  12
  13 As of this writing, the library modules are (from lowest to highest
  14 level):
  15
  16    - \refdir{lib/cc} -- Macros for managing the C compiler and
  17      language.
  18
  19    - \refdir{lib/version} -- Holds the current version of Tor.
  20
  21    - \refdir{lib/testsupport} -- Helpers for making
  22      test-only code, and test mocking support.
  23
  24    - \refdir{lib/defs} -- Lowest-level constants.
  25
  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._)
  29
  30    - \refdir{lib/conf} -- For declaring configuration options.
  31
  32    - \refdir{lib/arch} -- For handling differences in CPU
  33      architecture.
  34
  35    - \refdir{lib/err} -- Lowest-level error handling code.
  36
  37    - \refdir{lib/malloc} -- Memory management.
  38      management.
  39
  40    - \refdir{lib/intmath} -- Integer mathematics.
  41
  42    - \refdir{lib/fdio} -- For
  43       reading and writing n file descriptors.
  44
  45    - \refdir{lib/lock} -- Simple locking support.
  46       (_Lower-level than the rest of the threading code._)
  47
  48    - \refdir{lib/ctime} -- Constant-time code to avoid
  49      side-channels.
  50
  51    - \refdir{lib/string} -- Low-level string manipulation.
  52
  53    - \refdir{lib/wallclock} --
  54      For inspecting and manipulating the current (UTC) time.
  55
  56    - \refdir{lib/osinfo} -- For inspecting the OS version
  57      and capabilities.
  58
  59    - \refdir{lib/smartlist_core} -- The bare-bones
  60      pieces of our dynamic array ("smartlist") implementation.
  61
  62    - \refdir{lib/log} -- Log messages to files, syslogs, etc.
  63
  64    - \refdir{lib/container} -- General purpose containers,
  65      including dynamic arrays ("smartlists"), hashtables, bit arrays,
  66      etc.
  67
  68    - \refdir{lib/trace} -- A general-purpose API
  69      function-tracing functionality Tor.  (_Currently not much used._)
  70
  71    - \refdir{lib/thread} -- Mid-level Threading.
  72
  73    - \refdir{lib/term} -- Terminal manipulation
  74      (like reading a password from the user).
  75
  76    - \refdir{lib/memarea} -- A fast
  77      "arena" style allocator, where the data is freed all at once.
  78
  79    - \refdir{lib/encoding} -- Encoding
  80      data in various formats, datatypes, and transformations.
  81
  82    - \refdir{lib/dispatch} -- A general-purpose in-process
  83      message delivery system.
  84
  85    - \refdir{lib/sandbox} -- Our Linux seccomp2 sandbox
  86      implementation.
  87
  88    - \refdir{lib/pubsub} -- A publish/subscribe message passing system.
  89
  90    - \refdir{lib/fs} -- Files, filenames, directories, etc.
  91
  92    - \refdir{lib/confmgt} -- Parse, encode, and manipulate onfiguration files.
  93
  94    - \refdir{lib/crypt_ops} -- Cryptographic operations.
  95
  96    - \refdir{lib/meminfo} -- Functions for inspecting our
  97      memory usage, if the malloc implementation exposes that to us.
  98
  99    - \refdir{lib/time} -- Higher level time functions, including
 100      fine-gained and monotonic timers.
 101
 102    - \refdir{lib/math} -- Floating-point mathematical utilities.
 103
 104    - \refdir{lib/buf} -- An efficient byte queue.
 105
 106    - \refdir{lib/net} -- Networking code, including address
 107      manipulation, compatibility wrappers, etc.
 108
 109    - \refdir{lib/compress} -- Wraps several compression libraries.
 110
 111    - \refdir{lib/geoip} -- IP-to-country mapping.
 112
 113    - \refdir{lib/tls} -- TLS library wrappers.
 114
 115    - \refdir{lib/evloop} -- Low-level event-loop.
 116
 117    - \refdir{lib/process} -- Launch and manage subprocesses.
 118
 119 ### What belongs in lib?
 120
 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.
 124
 125 If it falls into one of the existing "lib" categories, your
 126 functionality belongs in lib.
 127
 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.
 131