lib Directory Reference

lib: low-level functionality.

More...

Directories
directory	arch
	lib/arch: Compatibility code for handling different CPU architectures.
directory	buf
	lib/buf: An efficient byte queue.
directory	cc
	lib/cc: Macros for managing the C compiler and language.
directory	compress
	lib/compress: Wraps several compression libraries
directory	conf
	lib/conf: Types and macros for declaring configuration options.
directory	confmgt
	lib/confmgt: Parse, encode, manipulate configuration files.
directory	container
	lib/container: Hash tables, dynamic arrays, bit arrays, etc.
directory	crypt_ops
	lib/crypt_ops: Cryptographic operations.
directory	ctime
	lib/ctime: Constant-time code to avoid side-channels.
directory	defs
	lib/defs: Lowest-level constants, used in many places.
directory	dispatch
	lib/dispatch: In-process message delivery.
directory	encoding
	lib/encoding: Encoding data in various forms, types, and transformations
directory	err
	lib/err: Lowest-level error handling code.
directory	evloop
	lib/evloop: Low-level event loop.
directory	fdio
	lib/fdio: Code to read/write on file descriptors.
directory	fs
	lib/fs: Files, filenames, directories, etc.
directory	geoip
	lib/geoip: IP-to-country mapping
directory	intmath
	lib/intmath: Integer mathematics.
directory	llharden
	lib/llharden: low-level unconditional process hardening
directory	lock
	lib/lock: Simple locking support.
directory	log
	lib/log: Log messages to files, syslogs, etc.
directory	malloc
	lib/malloc: Wrappers and utilities for memory management.
directory	math
	lib/math: Floating-point math utilities.
directory	memarea
	lib/memarea: A fast arena-style allocator.
directory	meminfo
	lib/meminfo: Inspecting system memory availability.
directory	metrics
	lib/metrics: Metrics collection API
directory	net
	lib/net: Low-level network-related code.
directory	osinfo
	lib/osinfo: For inspecting the OS version and capabilities.
directory	process
	lib/process: Launch and manage subprocesses.
directory	pubsub
	lib/pubsub: Publish-subscribe message passing.
directory	sandbox
	lib/sandbox: Linux seccomp2-based sandbox.
directory	smartlist_core
	lib/smartlist_core: Minimal dynamic array implementation
directory	string
	lib/string: Low-level string manipulation.
directory	subsys
	lib/subsys: Types for declaring a "subsystem".
directory	term
	lib/term: Terminal operations (password input).
directory	testsupport
	lib/testsupport: Helpers for test-only code and for function mocking.
directory	thread
	lib/thread: Mid-level threading.
directory	time
	lib/time: Higher-level time functions
directory	tls
	lib/tls: TLS library wrappers
directory	trace
	lib/trace: Function-tracing functionality API.
directory	version
	lib/version: holds the current version of Tor.
directory	wallclock
	lib/wallclock: Inspect and manipulate the current time.

Detailed Description

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):

• lib/cc – Macros for managing the C compiler and language.
• 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.
• lib/subsys – Types used for declaring a "subsystem". (A subsystem is a module with support for initialization, shutdown, configuration, and so on.)
• lib/conf – For declaring configuration options.
• lib/arch – For handling differences in CPU architecture.
• lib/err – Lowest-level error handling code.
• lib/malloc – Memory management. management.
• lib/intmath – Integer mathematics.
• lib/fdio – For reading and writing n file descriptors.
• lib/lock – Simple locking support. (Lower-level than the rest of the threading code.)
• lib/ctime – Constant-time code to avoid side-channels.
• lib/string – Low-level string manipulation.
• lib/wallclock – For inspecting and manipulating the current (UTC) time.
• lib/osinfo – For inspecting the OS version and capabilities.
• lib/smartlist_core – The bare-bones pieces of our dynamic array ("smartlist") implementation.
• lib/log – Log messages to files, syslogs, etc.
• lib/container – General purpose containers, including dynamic arrays ("smartlists"), hashtables, bit arrays, etc.
• lib/trace – A general-purpose API function-tracing functionality Tor. (Currently not much used.)
• lib/thread – Mid-level Threading.
• lib/term – Terminal manipulation (like reading a password from the user).
• lib/memarea – A fast "arena" style allocator, where the data is freed all at once.
• lib/encoding – Encoding data in various formats, datatypes, and transformations.
• lib/dispatch – A general-purpose in-process message delivery system.
• lib/sandbox – Our Linux seccomp2 sandbox implementation.
• lib/pubsub – A publish/subscribe message passing system.
• lib/fs – Files, filenames, directories, etc.
• lib/confmgt – Parse, encode, and manipulate onfiguration files.
• lib/crypt_ops – Cryptographic operations.
• 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.
• lib/buf – An efficient byte queue.
• lib/net – Networking code, including address manipulation, compatibility wrappers, etc.
• lib/compress – Wraps several compression libraries.
• lib/geoip – IP-to-country mapping.
• lib/tls – TLS library wrappers.
• lib/evloop – Low-level event-loop.
• lib/process – 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 ifdefs to manage compatibility issues among platforms, you should probably consider whether you can put your code into lib.