November 2019 - tor-commits - lists.torproject.org

[tor/master] Remove spurious lib/stats doxygen file.
by nickm＠torproject.org 05 Nov '19

05 Nov '19

commit b6b125709998a81d9c9c23d77c6a770ca7a927a7 Author: Nick Mathewson <nickm(a)torproject.org> Date: Mon Nov 4 10:19:23 2019 -0500 Remove spurious lib/stats doxygen file. --- src/lib/stats/lib_stats.dox | 4 ---- 1 file changed, 4 deletions(-) diff --git a/src/lib/stats/lib_stats.dox b/src/lib/stats/lib_stats.dox deleted file mode 100644 index 897c41418..000000000 --- a/src/lib/stats/lib_stats.dox +++ /dev/null @@ -1,4 +0,0 @@ -/** -@dir lib/stats -@brief lib/stats -**/

1 0

[tor/master] Doxygen: Avoid ambiguity in @dir directives
by nickm＠torproject.org 05 Nov '19

05 Nov '19

commit 62a473debf98cf43a3645366ec5ab6171d735616 Author: Nick Mathewson <nickm(a)torproject.org> Date: Mon Nov 4 10:23:36 2019 -0500 Doxygen: Avoid ambiguity in @dir directives This commit was automatically generated with: find src -name '*.dox' |xargs perl -i -pe 's{\@dir ([^/])}{\@dir /$1};' --- src/app/app.dox | 2 +- src/app/config/app_config.dox | 2 +- src/app/main/app_main.dox | 2 +- src/core/core.dox | 2 +- src/core/crypto/core_crypto.dox | 2 +- src/core/mainloop/core_mainloop.dox | 2 +- src/core/or/core_or.dox | 2 +- src/core/proto/core_proto.dox | 2 +- src/feature/api/feature_api.dox | 2 +- src/feature/client/feature_client.dox | 2 +- src/feature/control/feature_control.dox | 2 +- src/feature/dirauth/feature_dirauth.dox | 2 +- src/feature/dircache/feature_dircache.dox | 2 +- src/feature/dirclient/feature_dirclient.dox | 2 +- src/feature/dircommon/feature_dircommon.dox | 2 +- src/feature/dirparse/feature_dirparse.dox | 2 +- src/feature/feature.dox | 2 +- src/feature/hibernate/feature_hibernate.dox | 2 +- src/feature/hs/feature_hs.dox | 2 +- src/feature/hs_common/feature_hs_common.dox | 2 +- src/feature/keymgt/feature_keymgt.dox | 2 +- src/feature/nodelist/feature_nodelist.dox | 2 +- src/feature/relay/feature_relay.dox | 2 +- src/feature/rend/feature_rend.dox | 2 +- src/feature/stats/feature_stats.dox | 2 +- src/lib/arch/lib_arch.dox | 2 +- src/lib/buf/lib_buf.dox | 2 +- src/lib/cc/lib_cc.dox | 2 +- src/lib/compress/lib_compress.dox | 2 +- src/lib/conf/lib_conf.dox | 2 +- src/lib/confmgt/lib_confmgt.dox | 2 +- src/lib/container/lib_container.dox | 2 +- src/lib/crypt_ops/lib_crypt_ops.dox | 2 +- src/lib/ctime/lib_ctime.dox | 2 +- src/lib/defs/lib_defs.dox | 2 +- src/lib/dispatch/lib_dispatch.dox | 2 +- src/lib/encoding/lib_encoding.dox | 2 +- src/lib/err/lib_err.dox | 2 +- src/lib/evloop/lib_evloop.dox | 2 +- src/lib/fdio/lib_fdio.dox | 2 +- src/lib/fs/lib_fs.dox | 2 +- src/lib/geoip/lib_geoip.dox | 2 +- src/lib/intmath/lib_intmath.dox | 2 +- src/lib/lock/lib_lock.dox | 2 +- src/lib/log/lib_log.dox | 2 +- src/lib/malloc/lib_malloc.dox | 2 +- src/lib/math/lib_math.dox | 2 +- src/lib/memarea/lib_memarea.dox | 2 +- src/lib/meminfo/lib_meminfo.dox | 2 +- src/lib/net/lib_net.dox | 2 +- src/lib/osinfo/lib_osinfo.dox | 2 +- src/lib/process/lib_process.dox | 2 +- src/lib/pubsub/lib_pubsub.dox | 2 +- src/lib/sandbox/lib_sandbox.dox | 2 +- src/lib/smartlist_core/lib_smartlist_core.dox | 2 +- src/lib/string/lib_string.dox | 2 +- src/lib/subsys/lib_subsys.dox | 2 +- src/lib/term/lib_term.dox | 2 +- src/lib/testsupport/lib_testsupport.dox | 2 +- src/lib/thread/lib_thread.dox | 2 +- src/lib/time/lib_time.dox | 2 +- src/lib/tls/lib_tls.dox | 2 +- src/lib/trace/lib_trace.dox | 2 +- src/lib/version/lib_version.dox | 2 +- src/lib/wallclock/lib_wallclock.dox | 2 +- src/tools/tools.dox | 2 +- 66 files changed, 66 insertions(+), 66 deletions(-) diff --git a/src/app/app.dox b/src/app/app.dox index 29e8651d5..21d5791cd 100644 --- a/src/app/app.dox +++ b/src/app/app.dox @@ -1,5 +1,5 @@ /** -@dir app +@dir /app @brief app: top-level entry point for Tor The "app" directory has Tor's main entry point and configuration logic, diff --git a/src/app/config/app_config.dox b/src/app/config/app_config.dox index 03762fd27..d0d2ee363 100644 --- a/src/app/config/app_config.dox +++ b/src/app/config/app_config.dox @@ -1,4 +1,4 @@ /** -@dir app/config +@dir /app/config @brief app/config **/ diff --git a/src/app/main/app_main.dox b/src/app/main/app_main.dox index 1d94f8981..3da20226d 100644 --- a/src/app/main/app_main.dox +++ b/src/app/main/app_main.dox @@ -1,4 +1,4 @@ /** -@dir app/main +@dir /app/main @brief app/main **/ diff --git a/src/core/core.dox b/src/core/core.dox index 1352daebd..b37c5e2d8 100644 --- a/src/core/core.dox +++ b/src/core/core.dox @@ -1,5 +1,5 @@ /** -@dir core +@dir /core @brief core: main loop and onion routing functionality The "core" directory has the central protocols for Tor, which every diff --git a/src/core/crypto/core_crypto.dox b/src/core/crypto/core_crypto.dox index e5acdd652..36c12371d 100644 --- a/src/core/crypto/core_crypto.dox +++ b/src/core/crypto/core_crypto.dox @@ -1,4 +1,4 @@ /** -@dir core/crypto +@dir /core/crypto @brief core/crypto **/ diff --git a/src/core/mainloop/core_mainloop.dox b/src/core/mainloop/core_mainloop.dox index 9b32cb7f6..e97edde94 100644 --- a/src/core/mainloop/core_mainloop.dox +++ b/src/core/mainloop/core_mainloop.dox @@ -1,4 +1,4 @@ /** -@dir core/mainloop +@dir /core/mainloop @brief core/mainloop **/ diff --git a/src/core/or/core_or.dox b/src/core/or/core_or.dox index 1289a85c8..754690e00 100644 --- a/src/core/or/core_or.dox +++ b/src/core/or/core_or.dox @@ -1,4 +1,4 @@ /** -@dir core/or +@dir /core/or @brief core/or **/ diff --git a/src/core/proto/core_proto.dox b/src/core/proto/core_proto.dox index 3e1e4ddb6..2e92a6513 100644 --- a/src/core/proto/core_proto.dox +++ b/src/core/proto/core_proto.dox @@ -1,4 +1,4 @@ /** -@dir core/proto +@dir /core/proto @brief core/proto **/ diff --git a/src/feature/api/feature_api.dox b/src/feature/api/feature_api.dox index cb723b060..524e3c68e 100644 --- a/src/feature/api/feature_api.dox +++ b/src/feature/api/feature_api.dox @@ -1,4 +1,4 @@ /** -@dir feature/api +@dir /feature/api @brief feature/api **/ diff --git a/src/feature/client/feature_client.dox b/src/feature/client/feature_client.dox index 1a4881c50..755777ec1 100644 --- a/src/feature/client/feature_client.dox +++ b/src/feature/client/feature_client.dox @@ -1,4 +1,4 @@ /** -@dir feature/client +@dir /feature/client @brief feature/client **/ diff --git a/src/feature/control/feature_control.dox b/src/feature/control/feature_control.dox index 1f6e83c1d..44fda7989 100644 --- a/src/feature/control/feature_control.dox +++ b/src/feature/control/feature_control.dox @@ -1,4 +1,4 @@ /** -@dir feature/control +@dir /feature/control @brief feature/control **/ diff --git a/src/feature/dirauth/feature_dirauth.dox b/src/feature/dirauth/feature_dirauth.dox index fa4bee5b3..fa209dfb0 100644 --- a/src/feature/dirauth/feature_dirauth.dox +++ b/src/feature/dirauth/feature_dirauth.dox @@ -1,4 +1,4 @@ /** -@dir feature/dirauth +@dir /feature/dirauth @brief feature/dirauth **/ diff --git a/src/feature/dircache/feature_dircache.dox b/src/feature/dircache/feature_dircache.dox index 5f1c5cc70..4447d0cd2 100644 --- a/src/feature/dircache/feature_dircache.dox +++ b/src/feature/dircache/feature_dircache.dox @@ -1,4 +1,4 @@ /** -@dir feature/dircache +@dir /feature/dircache @brief feature/dircache **/ diff --git a/src/feature/dirclient/feature_dirclient.dox b/src/feature/dirclient/feature_dirclient.dox index 984a17cf5..65d3d26d0 100644 --- a/src/feature/dirclient/feature_dirclient.dox +++ b/src/feature/dirclient/feature_dirclient.dox @@ -1,4 +1,4 @@ /** -@dir feature/dirclient +@dir /feature/dirclient @brief feature/dirclient **/ diff --git a/src/feature/dircommon/feature_dircommon.dox b/src/feature/dircommon/feature_dircommon.dox index 2eff21065..f647b2928 100644 --- a/src/feature/dircommon/feature_dircommon.dox +++ b/src/feature/dircommon/feature_dircommon.dox @@ -1,4 +1,4 @@ /** -@dir feature/dircommon +@dir /feature/dircommon @brief feature/dircommon **/ diff --git a/src/feature/dirparse/feature_dirparse.dox b/src/feature/dirparse/feature_dirparse.dox index a6b34c1f5..934d8e424 100644 --- a/src/feature/dirparse/feature_dirparse.dox +++ b/src/feature/dirparse/feature_dirparse.dox @@ -1,4 +1,4 @@ /** -@dir feature/dirparse +@dir /feature/dirparse @brief feature/dirparse **/ diff --git a/src/feature/feature.dox b/src/feature/feature.dox index 1d9c3a9df..03759f9a1 100644 --- a/src/feature/feature.dox +++ b/src/feature/feature.dox @@ -1,5 +1,5 @@ /** -@dir feature +@dir /feature @brief feature: domain-specific modules The "feature" directory has modules that Tor uses only for a particular diff --git a/src/feature/hibernate/feature_hibernate.dox b/src/feature/hibernate/feature_hibernate.dox index e24620a43..55d89d1c2 100644 --- a/src/feature/hibernate/feature_hibernate.dox +++ b/src/feature/hibernate/feature_hibernate.dox @@ -1,4 +1,4 @@ /** -@dir feature/hibernate +@dir /feature/hibernate @brief feature/hibernate **/ diff --git a/src/feature/hs/feature_hs.dox b/src/feature/hs/feature_hs.dox index 08801d002..d93a8c274 100644 --- a/src/feature/hs/feature_hs.dox +++ b/src/feature/hs/feature_hs.dox @@ -1,4 +1,4 @@ /** -@dir feature/hs +@dir /feature/hs @brief feature/hs **/ diff --git a/src/feature/hs_common/feature_hs_common.dox b/src/feature/hs_common/feature_hs_common.dox index 8fd4f1b07..10bc9492c 100644 --- a/src/feature/hs_common/feature_hs_common.dox +++ b/src/feature/hs_common/feature_hs_common.dox @@ -1,4 +1,4 @@ /** -@dir feature/hs_common +@dir /feature/hs_common @brief feature/hs_common **/ diff --git a/src/feature/keymgt/feature_keymgt.dox b/src/feature/keymgt/feature_keymgt.dox index 8f72c70bb..c59843c25 100644 --- a/src/feature/keymgt/feature_keymgt.dox +++ b/src/feature/keymgt/feature_keymgt.dox @@ -1,4 +1,4 @@ /** -@dir feature/keymgt +@dir /feature/keymgt @brief feature/keymgt **/ diff --git a/src/feature/nodelist/feature_nodelist.dox b/src/feature/nodelist/feature_nodelist.dox index faeb9970b..eecddcfb5 100644 --- a/src/feature/nodelist/feature_nodelist.dox +++ b/src/feature/nodelist/feature_nodelist.dox @@ -1,4 +1,4 @@ /** -@dir feature/nodelist +@dir /feature/nodelist @brief feature/nodelist **/ diff --git a/src/feature/relay/feature_relay.dox b/src/feature/relay/feature_relay.dox index 9aa7af48e..4652bacaf 100644 --- a/src/feature/relay/feature_relay.dox +++ b/src/feature/relay/feature_relay.dox @@ -1,4 +1,4 @@ /** -@dir feature/relay +@dir /feature/relay @brief feature/relay **/ diff --git a/src/feature/rend/feature_rend.dox b/src/feature/rend/feature_rend.dox index fcba0d460..759d2155d 100644 --- a/src/feature/rend/feature_rend.dox +++ b/src/feature/rend/feature_rend.dox @@ -1,4 +1,4 @@ /** -@dir feature/rend +@dir /feature/rend @brief feature/rend **/ diff --git a/src/feature/stats/feature_stats.dox b/src/feature/stats/feature_stats.dox index fc4ffd19d..9b9ed87d1 100644 --- a/src/feature/stats/feature_stats.dox +++ b/src/feature/stats/feature_stats.dox @@ -1,4 +1,4 @@ /** -@dir feature/stats +@dir /feature/stats @brief feature/stats **/ diff --git a/src/lib/arch/lib_arch.dox b/src/lib/arch/lib_arch.dox index f7cfdbf0e..edb0cbbf1 100644 --- a/src/lib/arch/lib_arch.dox +++ b/src/lib/arch/lib_arch.dox @@ -1,4 +1,4 @@ /** -@dir lib/arch +@dir /lib/arch @brief lib/arch: Compatibility code for handling different CPU architectures. **/ diff --git a/src/lib/buf/lib_buf.dox b/src/lib/buf/lib_buf.dox index f21c4b1b7..9caaba07f 100644 --- a/src/lib/buf/lib_buf.dox +++ b/src/lib/buf/lib_buf.dox @@ -1,4 +1,4 @@ /** -@dir lib/buf +@dir /lib/buf @brief lib/buf **/ diff --git a/src/lib/cc/lib_cc.dox b/src/lib/cc/lib_cc.dox index 880cfc44f..06f4e775b 100644 --- a/src/lib/cc/lib_cc.dox +++ b/src/lib/cc/lib_cc.dox @@ -1,4 +1,4 @@ /** -@dir lib/cc +@dir /lib/cc @brief lib/cc: Macros for managing the C compiler and language. **/ diff --git a/src/lib/compress/lib_compress.dox b/src/lib/compress/lib_compress.dox index ac6079456..b1b090235 100644 --- a/src/lib/compress/lib_compress.dox +++ b/src/lib/compress/lib_compress.dox @@ -1,4 +1,4 @@ /** -@dir lib/compress +@dir /lib/compress @brief lib/compress **/ diff --git a/src/lib/conf/lib_conf.dox b/src/lib/conf/lib_conf.dox index 2ad051dcf..be58fe5b5 100644 --- a/src/lib/conf/lib_conf.dox +++ b/src/lib/conf/lib_conf.dox @@ -1,5 +1,5 @@ /** -@dir lib/conf +@dir /lib/conf @brief lib/conf: Types and macros for declaring configuration options. **/ diff --git a/src/lib/confmgt/lib_confmgt.dox b/src/lib/confmgt/lib_confmgt.dox index 964fe1d07..86cb04e84 100644 --- a/src/lib/confmgt/lib_confmgt.dox +++ b/src/lib/confmgt/lib_confmgt.dox @@ -1,4 +1,4 @@ /** -@dir lib/confmgt +@dir /lib/confmgt @brief lib/confmgt **/ diff --git a/src/lib/container/lib_container.dox b/src/lib/container/lib_container.dox index 9599cce6e..fb360368d 100644 --- a/src/lib/container/lib_container.dox +++ b/src/lib/container/lib_container.dox @@ -1,5 +1,5 @@ /** -@dir lib/container +@dir /lib/container @brief lib/container: Hash tables, dynamic arrays, bit arrays, etc. **/ diff --git a/src/lib/crypt_ops/lib_crypt_ops.dox b/src/lib/crypt_ops/lib_crypt_ops.dox index 1ea0b67d5..0c3e4d7c3 100644 --- a/src/lib/crypt_ops/lib_crypt_ops.dox +++ b/src/lib/crypt_ops/lib_crypt_ops.dox @@ -1,4 +1,4 @@ /** -@dir lib/crypt_ops +@dir /lib/crypt_ops @brief lib/crypt_ops **/ diff --git a/src/lib/ctime/lib_ctime.dox b/src/lib/ctime/lib_ctime.dox index bf95b0316..2bcd0f036 100644 --- a/src/lib/ctime/lib_ctime.dox +++ b/src/lib/ctime/lib_ctime.dox @@ -1,5 +1,5 @@ /** -@dir lib/ctime +@dir /lib/ctime @brief lib/ctime: Constant-time code to avoid side-channels. This module contains constant-time implementations of various diff --git a/src/lib/defs/lib_defs.dox b/src/lib/defs/lib_defs.dox index cd39414bf..8ed4d7a0a 100644 --- a/src/lib/defs/lib_defs.dox +++ b/src/lib/defs/lib_defs.dox @@ -1,4 +1,4 @@ /** -@dir lib/defs +@dir /lib/defs @brief lib/defs: Lowest-level constants, used in many places. **/ diff --git a/src/lib/dispatch/lib_dispatch.dox b/src/lib/dispatch/lib_dispatch.dox index 9f3a1fc7d..24a4b79e3 100644 --- a/src/lib/dispatch/lib_dispatch.dox +++ b/src/lib/dispatch/lib_dispatch.dox @@ -1,5 +1,5 @@ /** -@dir lib/dispatch +@dir /lib/dispatch @brief lib/dispatch: In-process message delivery. This module provides a general in-process "message dispatch" system in which diff --git a/src/lib/encoding/lib_encoding.dox b/src/lib/encoding/lib_encoding.dox index 19aca645f..ca698cb18 100644 --- a/src/lib/encoding/lib_encoding.dox +++ b/src/lib/encoding/lib_encoding.dox @@ -1,5 +1,5 @@ /** -@dir lib/encoding +@dir /lib/encoding @brief lib/encoding: Encoding data in various forms, types, and transformations Here we have time formats (timefmt.c), quoted strings (qstring.c), C strings diff --git a/src/lib/err/lib_err.dox b/src/lib/err/lib_err.dox index 23f9d9d3a..d1479b114 100644 --- a/src/lib/err/lib_err.dox +++ b/src/lib/err/lib_err.dox @@ -1,5 +1,5 @@ /** -@dir lib/err +@dir /lib/err @brief lib/err: Lowest-level error handling code. This module is responsible for generating stack traces, handling raw diff --git a/src/lib/evloop/lib_evloop.dox b/src/lib/evloop/lib_evloop.dox index 86b60e3cd..f60f41968 100644 --- a/src/lib/evloop/lib_evloop.dox +++ b/src/lib/evloop/lib_evloop.dox @@ -1,4 +1,4 @@ /** -@dir lib/evloop +@dir /lib/evloop @brief lib/evloop **/ diff --git a/src/lib/fdio/lib_fdio.dox b/src/lib/fdio/lib_fdio.dox index c3ca3b9c8..2615b9791 100644 --- a/src/lib/fdio/lib_fdio.dox +++ b/src/lib/fdio/lib_fdio.dox @@ -1,5 +1,5 @@ /** -@dir lib/fdio +@dir /lib/fdio @brief lib/fdio Code to read/write on file descriptors. (This module also handles sockets, on platforms where a socket is not a kind diff --git a/src/lib/fs/lib_fs.dox b/src/lib/fs/lib_fs.dox index ad775ba55..33ff16928 100644 --- a/src/lib/fs/lib_fs.dox +++ b/src/lib/fs/lib_fs.dox @@ -1,4 +1,4 @@ /** -@dir lib/fs +@dir /lib/fs @brief lib/fs **/ diff --git a/src/lib/geoip/lib_geoip.dox b/src/lib/geoip/lib_geoip.dox index 7ad99e8f5..454dcb687 100644 --- a/src/lib/geoip/lib_geoip.dox +++ b/src/lib/geoip/lib_geoip.dox @@ -1,4 +1,4 @@ /** -@dir lib/geoip +@dir /lib/geoip @brief lib/geoip **/ diff --git a/src/lib/intmath/lib_intmath.dox b/src/lib/intmath/lib_intmath.dox index 0d5d711ee..33fa0f02b 100644 --- a/src/lib/intmath/lib_intmath.dox +++ b/src/lib/intmath/lib_intmath.dox @@ -1,4 +1,4 @@ /** -@dir lib/intmath +@dir /lib/intmath @brief lib/intmath Integer mathematics. **/ diff --git a/src/lib/lock/lib_lock.dox b/src/lib/lock/lib_lock.dox index f248e12c8..868b5ba7d 100644 --- a/src/lib/lock/lib_lock.dox +++ b/src/lib/lock/lib_lock.dox @@ -1,5 +1,5 @@ /** -@dir lib/lock +@dir /lib/lock @brief lib/lock: Simple locking support. This module is more low-level than the rest of the threading code, since it diff --git a/src/lib/log/lib_log.dox b/src/lib/log/lib_log.dox index 5059f3ef7..b6d242917 100644 --- a/src/lib/log/lib_log.dox +++ b/src/lib/log/lib_log.dox @@ -1,5 +1,5 @@ /** -@dir lib/log +@dir /lib/log @brief lib/log: Log messages to files, syslogs, etc. You can think of this as the logical "midpoint" of the diff --git a/src/lib/malloc/lib_malloc.dox b/src/lib/malloc/lib_malloc.dox index 6408d7ce3..2553c82f1 100644 --- a/src/lib/malloc/lib_malloc.dox +++ b/src/lib/malloc/lib_malloc.dox @@ -1,5 +1,5 @@ /** -@dir lib/malloc +@dir /lib/malloc @brief lib/malloc: Wrappers and utilities for memory management. **/ diff --git a/src/lib/math/lib_math.dox b/src/lib/math/lib_math.dox index c2e121dc8..0073731dc 100644 --- a/src/lib/math/lib_math.dox +++ b/src/lib/math/lib_math.dox @@ -1,4 +1,4 @@ /** -@dir lib/math +@dir /lib/math @brief lib/math **/ diff --git a/src/lib/memarea/lib_memarea.dox b/src/lib/memarea/lib_memarea.dox index f5b44f97c..eaca28604 100644 --- a/src/lib/memarea/lib_memarea.dox +++ b/src/lib/memarea/lib_memarea.dox @@ -1,5 +1,5 @@ /** -@dir lib/memarea +@dir /lib/memarea @brief lib/memarea A fast arena-style allocator. This module has a fast "arena" style allocator, where memory is freed all at diff --git a/src/lib/meminfo/lib_meminfo.dox b/src/lib/meminfo/lib_meminfo.dox index c8def7e2f..433d6859e 100644 --- a/src/lib/meminfo/lib_meminfo.dox +++ b/src/lib/meminfo/lib_meminfo.dox @@ -1,4 +1,4 @@ /** -@dir lib/meminfo +@dir /lib/meminfo @brief lib/meminfo **/ diff --git a/src/lib/net/lib_net.dox b/src/lib/net/lib_net.dox index 03783c12a..ca3c56a94 100644 --- a/src/lib/net/lib_net.dox +++ b/src/lib/net/lib_net.dox @@ -1,4 +1,4 @@ /** -@dir lib/net +@dir /lib/net @brief lib/net **/ diff --git a/src/lib/osinfo/lib_osinfo.dox b/src/lib/osinfo/lib_osinfo.dox index c78615937..4d9b1a6d7 100644 --- a/src/lib/osinfo/lib_osinfo.dox +++ b/src/lib/osinfo/lib_osinfo.dox @@ -1,5 +1,5 @@ /** -@dir lib/osinfo +@dir /lib/osinfo @brief lib/osinfo: For inspecting the OS version and capabilities. In general, we use this module when we're telling the user what operating diff --git a/src/lib/process/lib_process.dox b/src/lib/process/lib_process.dox index efb1adc09..9059d6666 100644 --- a/src/lib/process/lib_process.dox +++ b/src/lib/process/lib_process.dox @@ -1,4 +1,4 @@ /** -@dir lib/process +@dir /lib/process @brief lib/process **/ diff --git a/src/lib/pubsub/lib_pubsub.dox b/src/lib/pubsub/lib_pubsub.dox index 9a3fc6dfa..3fd026cc0 100644 --- a/src/lib/pubsub/lib_pubsub.dox +++ b/src/lib/pubsub/lib_pubsub.dox @@ -1,4 +1,4 @@ /** -@dir lib/pubsub +@dir /lib/pubsub @brief lib/pubsub **/ diff --git a/src/lib/sandbox/lib_sandbox.dox b/src/lib/sandbox/lib_sandbox.dox index 8b33fc255..91d056d46 100644 --- a/src/lib/sandbox/lib_sandbox.dox +++ b/src/lib/sandbox/lib_sandbox.dox @@ -1,5 +1,5 @@ /** -@dir lib/sandbox +@dir /lib/sandbox @brief lib/sandbox Linux seccomp2-based sandbox. This module uses Linux's seccomp2 facility via the diff --git a/src/lib/smartlist_core/lib_smartlist_core.dox b/src/lib/smartlist_core/lib_smartlist_core.dox index 68b824935..5e3ffd1f0 100644 --- a/src/lib/smartlist_core/lib_smartlist_core.dox +++ b/src/lib/smartlist_core/lib_smartlist_core.dox @@ -1,5 +1,5 @@ /** -@dir lib/smartlist_core +@dir /lib/smartlist_core @brief lib/smartlist_core: Minimal dynamic array implementation A `smartlist_t` is a dynamic array type for holding `void *`. We use it diff --git a/src/lib/string/lib_string.dox b/src/lib/string/lib_string.dox index 95645ab36..c8793ddf9 100644 --- a/src/lib/string/lib_string.dox +++ b/src/lib/string/lib_string.dox @@ -1,5 +1,5 @@ /** -@dir lib/string +@dir /lib/string @brief lib/string: Low-level string manipulation. We have a number of compatibility functions here: some are for handling diff --git a/src/lib/subsys/lib_subsys.dox b/src/lib/subsys/lib_subsys.dox index 4d98ff577..1a22a2d80 100644 --- a/src/lib/subsys/lib_subsys.dox +++ b/src/lib/subsys/lib_subsys.dox @@ -1,5 +1,5 @@ /** -@dir lib/subsys +@dir /lib/subsys @brief lib/subsys: Types for declaring a "subsystem". ## Subsystems in Tor diff --git a/src/lib/term/lib_term.dox b/src/lib/term/lib_term.dox index 2bc512583..d6010cb69 100644 --- a/src/lib/term/lib_term.dox +++ b/src/lib/term/lib_term.dox @@ -1,4 +1,4 @@ /** -@dir lib/term +@dir /lib/term @brief lib/term **/ diff --git a/src/lib/testsupport/lib_testsupport.dox b/src/lib/testsupport/lib_testsupport.dox index 665b10e1f..c09c32e47 100644 --- a/src/lib/testsupport/lib_testsupport.dox +++ b/src/lib/testsupport/lib_testsupport.dox @@ -1,4 +1,4 @@ /** -@dir lib/testsupport +@dir /lib/testsupport @brief lib/testsupport: Helpers for test-only code and for function mocking. **/ diff --git a/src/lib/thread/lib_thread.dox b/src/lib/thread/lib_thread.dox index 68937ef79..b1e24d824 100644 --- a/src/lib/thread/lib_thread.dox +++ b/src/lib/thread/lib_thread.dox @@ -1,4 +1,4 @@ /** -@dir lib/thread +@dir /lib/thread @brief lib/thread **/ diff --git a/src/lib/time/lib_time.dox b/src/lib/time/lib_time.dox index 50abf072f..8e1e30859 100644 --- a/src/lib/time/lib_time.dox +++ b/src/lib/time/lib_time.dox @@ -1,4 +1,4 @@ /** -@dir lib/time +@dir /lib/time @brief lib/time **/ diff --git a/src/lib/tls/lib_tls.dox b/src/lib/tls/lib_tls.dox index 40b7b2c27..9558687f6 100644 --- a/src/lib/tls/lib_tls.dox +++ b/src/lib/tls/lib_tls.dox @@ -1,4 +1,4 @@ /** -@dir lib/tls +@dir /lib/tls @brief lib/tls **/ diff --git a/src/lib/trace/lib_trace.dox b/src/lib/trace/lib_trace.dox index a8ac09d87..64f762bc3 100644 --- a/src/lib/trace/lib_trace.dox +++ b/src/lib/trace/lib_trace.dox @@ -1,5 +1,5 @@ /** -@dir lib/trace +@dir /lib/trace @brief lib/trace: Function-tracing functionality API. This module is used for adding "trace" support (low-granularity function diff --git a/src/lib/version/lib_version.dox b/src/lib/version/lib_version.dox index d3d2481ba..93d2fb6b9 100644 --- a/src/lib/version/lib_version.dox +++ b/src/lib/version/lib_version.dox @@ -1,4 +1,4 @@ /** -@dir lib/version +@dir /lib/version @brief lib/version: holds the current version of Tor. **/ diff --git a/src/lib/wallclock/lib_wallclock.dox b/src/lib/wallclock/lib_wallclock.dox index a024425ea..03966aecc 100644 --- a/src/lib/wallclock/lib_wallclock.dox +++ b/src/lib/wallclock/lib_wallclock.dox @@ -1,5 +1,5 @@ /** -@dir lib/wallclock +@dir /lib/wallclock @brief lib/wallclock: Inspect and manipulate the current time. This module handles our concept of "what time is it" or "what time does the diff --git a/src/tools/tools.dox b/src/tools/tools.dox index 54aa4df48..1168ed5ba 100644 --- a/src/tools/tools.dox +++ b/src/tools/tools.dox @@ -1,5 +1,5 @@ /** -@dir tools +@dir /tools @brief tools: other command-line tools for use with Tor. The "tools" directory has a few other programs that use Tor, but are not part

1 0

[tor/master] Doxygen: define an alias for linking to a directory.
by nickm＠torproject.org 05 Nov '19

05 Nov '19

commit b95bc4d839323650bbdf2269b9551c7595ff3b2a Author: Nick Mathewson <nickm(a)torproject.org> Date: Mon Nov 4 11:08:04 2019 -0500 Doxygen: define an alias for linking to a directory. We need to use this kind of trickery to make directory links work in out-of-tree builds. --- Doxyfile.in | 1 + 1 file changed, 1 insertion(+) diff --git a/Doxyfile.in b/Doxyfile.in index 0128f1281..bb0d75cc9 100644 --- a/Doxyfile.in +++ b/Doxyfile.in @@ -255,6 +255,7 @@ TAB_SIZE = 8 # a double escape (\\{ and \\}) ALIASES = +ALIASES += refdir{1}="\ref @top_srcdir@/src/\1 \"\1\"" # This tag can be used to specify a number of word-keyword mappings (TCL only). # A mapping has the form "name=value". For example adding "class=itcl::class"

1 0

[tor/master] doxygen: Take "lib" descriptions from doc/HACKING/design.
by nickm＠torproject.org 05 Nov '19

05 Nov '19

commit 51a98929148e9ca08b33735fb0542759380c57a9 Author: Nick Mathewson <nickm(a)torproject.org> Date: Mon Nov 4 10:19:41 2019 -0500 doxygen: Take "lib" descriptions from doc/HACKING/design. This commit takes descriptions for src/lib and moves them into our doxygen hierarchy. I've covered everything from lib/cc through lib/sandbox here. --- src/lib/arch/lib_arch.dox | 2 +- src/lib/cc/lib_cc.dox | 2 +- src/lib/conf/lib_conf.dox | 3 +- src/lib/container/lib_container.dox | 3 +- src/lib/ctime/lib_ctime.dox | 14 ++- src/lib/defs/lib_defs.dox | 2 +- src/lib/dispatch/lib_dispatch.dox | 14 ++- src/lib/encoding/lib_encoding.dox | 6 +- src/lib/err/lib_err.dox | 13 ++- src/lib/fdio/lib_fdio.dox | 5 +- src/lib/intmath/lib_intmath.dox | 2 +- src/lib/lib.dox | 149 +++++++++++++++++++++++++- src/lib/lock/lib_lock.dox | 6 +- src/lib/log/lib_log.dox | 10 +- src/lib/malloc/lib_malloc.dox | 3 +- src/lib/memarea/lib_memarea.dox | 8 +- src/lib/osinfo/lib_osinfo.dox | 8 +- src/lib/sandbox/lib_sandbox.dox | 15 ++- src/lib/smartlist_core/lib_smartlist_core.dox | 10 +- src/lib/string/lib_string.dox | 13 ++- src/lib/subsys/lib_subsys.dox | 32 +++++- src/lib/testsupport/lib_testsupport.dox | 2 +- src/lib/trace/lib_trace.dox | 6 +- src/lib/version/lib_version.dox | 2 +- src/lib/wallclock/lib_wallclock.dox | 10 +- 25 files changed, 313 insertions(+), 27 deletions(-) diff --git a/src/lib/arch/lib_arch.dox b/src/lib/arch/lib_arch.dox index 60b5fafeb..f7cfdbf0e 100644 --- a/src/lib/arch/lib_arch.dox +++ b/src/lib/arch/lib_arch.dox @@ -1,4 +1,4 @@ /** @dir lib/arch -@brief lib/arch +@brief lib/arch: Compatibility code for handling different CPU architectures. **/ diff --git a/src/lib/cc/lib_cc.dox b/src/lib/cc/lib_cc.dox index 804260cb2..880cfc44f 100644 --- a/src/lib/cc/lib_cc.dox +++ b/src/lib/cc/lib_cc.dox @@ -1,4 +1,4 @@ /** @dir lib/cc -@brief lib/cc +@brief lib/cc: Macros for managing the C compiler and language. **/ diff --git a/src/lib/conf/lib_conf.dox b/src/lib/conf/lib_conf.dox index 40a1d9f90..2ad051dcf 100644 --- a/src/lib/conf/lib_conf.dox +++ b/src/lib/conf/lib_conf.dox @@ -1,4 +1,5 @@ /** @dir lib/conf -@brief lib/conf +@brief lib/conf: Types and macros for declaring configuration options. + **/ diff --git a/src/lib/container/lib_container.dox b/src/lib/container/lib_container.dox index 6ee719f47..9599cce6e 100644 --- a/src/lib/container/lib_container.dox +++ b/src/lib/container/lib_container.dox @@ -1,4 +1,5 @@ /** @dir lib/container -@brief lib/container +@brief lib/container: Hash tables, dynamic arrays, bit arrays, etc. + **/ diff --git a/src/lib/ctime/lib_ctime.dox b/src/lib/ctime/lib_ctime.dox index 476c95991..bf95b0316 100644 --- a/src/lib/ctime/lib_ctime.dox +++ b/src/lib/ctime/lib_ctime.dox @@ -1,4 +1,16 @@ /** @dir lib/ctime -@brief lib/ctime +@brief lib/ctime: Constant-time code to avoid side-channels. + +This module contains constant-time implementations of various +data comparison and table lookup functions. We use these in preference to +memcmp() and so forth, since memcmp() can leak information about its inputs +based on how fast it returns. In general, your code should call tor_memeq() +and tor_memneq(), not memcmp(). + +We also define some _non_-constant-time wrappers for memcmp() here: Since we +consider calls to memcmp() to be in error, we require that code that actually +doesn't need to be constant-time to use the fast_memeq() / fast_memneq() / +fast_memcmp() aliases instead. + **/ diff --git a/src/lib/defs/lib_defs.dox b/src/lib/defs/lib_defs.dox index 5adb527fc..cd39414bf 100644 --- a/src/lib/defs/lib_defs.dox +++ b/src/lib/defs/lib_defs.dox @@ -1,4 +1,4 @@ /** @dir lib/defs -@brief lib/defs +@brief lib/defs: Lowest-level constants, used in many places. **/ diff --git a/src/lib/dispatch/lib_dispatch.dox b/src/lib/dispatch/lib_dispatch.dox index f194eff48..9f3a1fc7d 100644 --- a/src/lib/dispatch/lib_dispatch.dox +++ b/src/lib/dispatch/lib_dispatch.dox @@ -1,4 +1,16 @@ /** @dir lib/dispatch -@brief lib/dispatch +@brief lib/dispatch: In-process message delivery. + +This module provides a general in-process "message dispatch" system in which +typed messages are sent on channels. The dispatch.h header has far more +information. + +It is used by by \ref src/lib/pubsub "lib/pubsub" to implement our general +inter-module publish/subscribe system. + +This is not a fancy multi-threaded many-to-many dispatcher as you may be used +to from more sophisticated architectures: this dispatcher is intended only +for use in improving Tor's architecture. + **/ diff --git a/src/lib/encoding/lib_encoding.dox b/src/lib/encoding/lib_encoding.dox index 4a5fad927..19aca645f 100644 --- a/src/lib/encoding/lib_encoding.dox +++ b/src/lib/encoding/lib_encoding.dox @@ -1,4 +1,8 @@ /** @dir lib/encoding -@brief lib/encoding +@brief lib/encoding: Encoding data in various forms, types, and transformations + +Here we have time formats (timefmt.c), quoted strings (qstring.c), C strings +(string.c) base-16/32/64 (binascii.c), and more. + **/ diff --git a/src/lib/err/lib_err.dox b/src/lib/err/lib_err.dox index 8994fa5fd..23f9d9d3a 100644 --- a/src/lib/err/lib_err.dox +++ b/src/lib/err/lib_err.dox @@ -1,4 +1,15 @@ /** @dir lib/err -@brief lib/err +@brief lib/err: Lowest-level error handling code. + +This module is 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. + +There are three kinds of users for the functions in this module: + * Code that needs a way to assert(), but which cannot use the regular + `tor_assert()` macros in logging module. + * Code that needs signal-safe error reporting. + * Higher-level error handling code. + **/ diff --git a/src/lib/fdio/lib_fdio.dox b/src/lib/fdio/lib_fdio.dox index b868d28aa..c3ca3b9c8 100644 --- a/src/lib/fdio/lib_fdio.dox +++ b/src/lib/fdio/lib_fdio.dox @@ -1,4 +1,7 @@ /** @dir lib/fdio -@brief lib/fdio +@brief lib/fdio Code to read/write on file descriptors. + +(This module also handles sockets, on platforms where a socket is not a kind +of fd.) **/ diff --git a/src/lib/intmath/lib_intmath.dox b/src/lib/intmath/lib_intmath.dox index ce71e455d..0d5d711ee 100644 --- a/src/lib/intmath/lib_intmath.dox +++ b/src/lib/intmath/lib_intmath.dox @@ -1,4 +1,4 @@ /** @dir lib/intmath -@brief lib/intmath +@brief lib/intmath Integer mathematics. **/ diff --git a/src/lib/lib.dox b/src/lib/lib.dox index f1b2291c7..1d3bc3a3f 100644 --- a/src/lib/lib.dox +++ b/src/lib/lib.dox @@ -1,8 +1,151 @@ /** -@dir lib +@dir /lib @brief lib: low-level functionality. -The "lib" directory contains low-level functionality, most of it not -necessarily Tor-specific. +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): + + - \ref src/lib/cc "lib/cc" -- Macros for managing the C compiler and + language. + + - \ref src/lib/version "lib/version" -- Holds the current version of Tor. + + - \ref src/lib/testsupport "lib/testsupport" -- Helpers for making + test-only code, and test mocking support. + + - \ref src/lib/defs "lib/defs" -- Lowest-level constants. + + - \ref src/lib/subsys "lib/subsys" -- Types used for declaring a + "subsystem". (_A subsystem is a module with support for initialization, + shutdown, configuration, and so on._) + + - \ref src/lib/conf "lib/conf" -- For declaring configuration options. + + - \ref src/lib/arch "lib/arch" -- For handling differences in CPU + architecture. + + - \ref src/lib/err "lib/err" -- Lowest-level error handling code. + + - \ref src/lib/malloc "lib/malloc" -- Memory management. + management. + + - \ref src/lib/intmath "lib/intmath" -- Integer mathematics. + + - \ref src/lib/fdio "lib/fdio" -- For + reading and writing n file descriptors. + + - \ref src/lib/lock "lib/lock" -- Simple locking support. + (_Lower-level than the rest of the threading code._) + + - \ref src/lib/ctime "lib/ctime" -- Constant-time code to avoid + side-channels. + + - \ref src/lib/string "lib/string" -- Low-level string manipulation. + + - \ref src/lib/wallclock "lib/wallclock" -- + For inspecting and manipulating the current (UTC) time. + + - \ref src/lib/osinfo "lib/osinfo" -- For inspecting the OS version + and capabilities. + + - \ref src/lib/smartlist_core "lib/smartlist_core" -- The bare-bones + pieces of our dynamic array ("smartlist") implementation. + + - \ref src/lib/log "lib/log" -- Log messages to files, syslogs, etc. + + - \ref src/lib/container "lib/container" -- General purpose containers, + including dynamic arrays ("smartlists"), hashtables, bit arrays, + etc. + + - \ref src/lib/trace "lib/trace" -- A general-purpose API + function-tracing functionality Tor. (_Currently not much used._) + + - \ref src/lib/thread "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 \ref src/lib/evloop "lib/evloop"). + + - \ref src/lib/term "lib/term" -- Terminal manipulation + (like reading a password from the user). + + - \ref src/lib/memarea "lib/memarea" -- A fast + "arena" style allocator, where the data is freed all at once. + + - \ref src/lib/encoding "lib/encoding" -- Encoding + data in various formats, datatypes, and transformations. + + - \ref src/lib/dispatch "lib/dispatch" -- A general-purpose in-process + message delivery system. + + - \ref src/lib/sandbox "lib/sandbox" -- Our Linux seccomp2 sandbox + implementation. + + - \ref src/lib/pubsub "lib/pubsub" -- Code and macros to implement our + publish/subscribe message passing system. + + - \ref src/lib/fs "lib/fs" -- Utility and compatibility code for + manipulating files, filenames, directories, and so on. + + - \ref src/lib/confmgt "lib/confmgt" -- Code to parse, encode, and + manipulate our configuration files, state files, and so forth. + + - \ref src/lib/crypt_ops "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. + + - \ref src/lib/meminfo "lib/meminfo" -- Functions for inspecting our + memory usage, if the malloc implementation exposes that to us. + + - \ref src/lib/time "lib/time" -- Higher level time functions, including + fine-gained and monotonic timers. + + - \ref src/lib/math "lib/math" -- Floating-point mathematical utilities, + including compatibility code, and probability distributions. + + - \ref src/lib/buf "lib/buf" -- A general purpose queued buffer + implementation, similar to the BSD kernel's "mbuf" structure. + + - \ref src/lib/net "lib/net" -- Networking code, including address + manipulation, compatibility wrappers, + + - \ref src/lib/compress "lib/compress" -- A compatibility wrapper around + several compression libraries, currently including zlib, zstd, and lzma. + + - \ref src/lib/geoip "lib/geoip" -- Utilities to manage geoip (IP to + country) lookups and formats. + + - \ref src/lib/tls "lib/tls" -- Compatibility wrappers around the library + (NSS or OpenSSL, depending on configuration) that Tor uses to implement + the TLS link security protocol. + + - \ref src/lib/evloop "lib/evloop" -- Tools to manage the event loop and + related functionality, in order to implement asynchronous networking, + timers, periodic events, and other scheduling tasks. + + - \ref src/lib/process "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. **/ diff --git a/src/lib/lock/lib_lock.dox b/src/lib/lock/lib_lock.dox index 44693e7a6..f248e12c8 100644 --- a/src/lib/lock/lib_lock.dox +++ b/src/lib/lock/lib_lock.dox @@ -1,4 +1,8 @@ /** @dir lib/lock -@brief lib/lock +@brief lib/lock: Simple locking support. + +This module is more low-level than the rest of the threading code, since it +is needed by more intermediate-level modules. + **/ diff --git a/src/lib/log/lib_log.dox b/src/lib/log/lib_log.dox index 915d65240..5059f3ef7 100644 --- a/src/lib/log/lib_log.dox +++ b/src/lib/log/lib_log.dox @@ -1,4 +1,12 @@ /** @dir lib/log -@brief lib/log +@brief lib/log: Log messages to files, syslogs, etc. + +You can think of this as the logical "midpoint" of the +\ref src/lib "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. + + **/ diff --git a/src/lib/malloc/lib_malloc.dox b/src/lib/malloc/lib_malloc.dox index 4923f1446..6408d7ce3 100644 --- a/src/lib/malloc/lib_malloc.dox +++ b/src/lib/malloc/lib_malloc.dox @@ -1,4 +1,5 @@ /** @dir lib/malloc -@brief lib/malloc +@brief lib/malloc: Wrappers and utilities for memory management. + **/ diff --git a/src/lib/memarea/lib_memarea.dox b/src/lib/memarea/lib_memarea.dox index dbd98de5e..f5b44f97c 100644 --- a/src/lib/memarea/lib_memarea.dox +++ b/src/lib/memarea/lib_memarea.dox @@ -1,4 +1,10 @@ /** @dir lib/memarea -@brief lib/memarea +@brief lib/memarea A fast arena-style allocator. + +This module has a fast "arena" style allocator, where memory is freed all at +once. This kind of allocation is very fast and avoids fragmentation, at the +expense of requiring all the data to be freed at the same time. We use this +for parsing and diff calculations. + **/ diff --git a/src/lib/osinfo/lib_osinfo.dox b/src/lib/osinfo/lib_osinfo.dox index 7733755f2..c78615937 100644 --- a/src/lib/osinfo/lib_osinfo.dox +++ b/src/lib/osinfo/lib_osinfo.dox @@ -1,4 +1,10 @@ /** @dir lib/osinfo -@brief lib/osinfo +@brief lib/osinfo: For inspecting the OS version and capabilities. + +In general, we use this module when we're telling the user what operating +system they are running. We shouldn't make decisions based on the output of +these checks: instead, we should have more specific checks, either at compile +time or run time, based on the observed system behavior. + **/ diff --git a/src/lib/sandbox/lib_sandbox.dox b/src/lib/sandbox/lib_sandbox.dox index eb42d9758..8b33fc255 100644 --- a/src/lib/sandbox/lib_sandbox.dox +++ b/src/lib/sandbox/lib_sandbox.dox @@ -1,4 +1,17 @@ /** @dir lib/sandbox -@brief lib/sandbox +@brief lib/sandbox Linux seccomp2-based sandbox. + +This module uses Linux's seccomp2 facility via the +[`libseccomp` library](https://github.com/seccomp/libseccomp), to restrict +the set of system calls that Tor is allowed to invoke while it is running. + +Because there are many libc versions that invoke different system calls, and +because handling strings is quite complex, this module is more complex and +less portable than it needs to be. + +A better architecture would put the responsibility for invoking tricky system +calls (like open()) in another, less restricted process, and give that +process responsibility for enforcing our sandbox rules. + **/ diff --git a/src/lib/smartlist_core/lib_smartlist_core.dox b/src/lib/smartlist_core/lib_smartlist_core.dox index 507d0fe92..68b824935 100644 --- a/src/lib/smartlist_core/lib_smartlist_core.dox +++ b/src/lib/smartlist_core/lib_smartlist_core.dox @@ -1,4 +1,12 @@ /** @dir lib/smartlist_core -@brief lib/smartlist_core +@brief lib/smartlist_core: Minimal dynamic array implementation + +A `smartlist_t` is a dynamic array type for holding `void *`. We use it +throughout the rest of the codebase. + +There are higher-level pieces in \ref src/lib/container "lib/container", but +the ones in lib/smartlist_core are used by the logging code, and therefore +cannot use the logging code. + **/ diff --git a/src/lib/string/lib_string.dox b/src/lib/string/lib_string.dox index 3e038ea07..95645ab36 100644 --- a/src/lib/string/lib_string.dox +++ b/src/lib/string/lib_string.dox @@ -1,4 +1,15 @@ /** @dir lib/string -@brief lib/string +@brief lib/string: Low-level string manipulation. + +We have a number of compatibility functions here: some are for handling +functionality that is not implemented (or not implemented the same) on every +platform; some are for providing locale-independent versions of libc +functions that would otherwise be defined differently for different users. + +Other functions here are for common string-manipulation operations that we do +in the rest of the codebase. + +Any string function high-level enough to need logging belongs in a +higher-level module. **/ diff --git a/src/lib/subsys/lib_subsys.dox b/src/lib/subsys/lib_subsys.dox index f9cd5eeb8..4d98ff577 100644 --- a/src/lib/subsys/lib_subsys.dox +++ b/src/lib/subsys/lib_subsys.dox @@ -1,4 +1,34 @@ /** @dir lib/subsys -@brief lib/subsys +@brief lib/subsys: Types for declaring a "subsystem". + +## Subsystems in Tor + +A subsystem is a module with support for initialization, shutdown, +configuration, and so on. + +Many parts of Tor can be initialized, cleaned up, and configured somewhat +independently through a table-driven mechanism. Each such part is called a +"subsystem". + +To declare a subsystem, make a global `const` instance of the `subsys_fns_t` +type, filling in the function pointer fields that you require with ones +corresponding to your subsystem. Any function pointers left as "NULL" will +be a no-op. Each system must have a name and a "level", which corresponds to +the order in which it is initialized. (See `app/main/subsystem_list.c` for a +list of current subsystems and their levels.) + +Then, insert your subsystem in the list in `app/main/subsystem_list.c`. It +will need to occupy a position corresponding to its level. + +At this point, your subsystem will be handled like the others: it will get +initialized at startup, torn down at exit, and so on. + +Historical note: Not all of Tor's code is currently handled as +subsystems. As you work with older code, you may see some parts of the code +that are initialized from `tor_init()` or `run_tor_main_loop()` or +`tor_run_main()`; and torn down from `tor_cleanup()`. We aim to migrate +these to subsystems over time; please don't add any new code that follows +this pattern. + **/ diff --git a/src/lib/testsupport/lib_testsupport.dox b/src/lib/testsupport/lib_testsupport.dox index 63ccc47d3..665b10e1f 100644 --- a/src/lib/testsupport/lib_testsupport.dox +++ b/src/lib/testsupport/lib_testsupport.dox @@ -1,4 +1,4 @@ /** @dir lib/testsupport -@brief lib/testsupport +@brief lib/testsupport: Helpers for test-only code and for function mocking. **/ diff --git a/src/lib/trace/lib_trace.dox b/src/lib/trace/lib_trace.dox index a1ae25650..a8ac09d87 100644 --- a/src/lib/trace/lib_trace.dox +++ b/src/lib/trace/lib_trace.dox @@ -1,4 +1,8 @@ /** @dir lib/trace -@brief lib/trace +@brief lib/trace: Function-tracing functionality API. + +This module is used for adding "trace" support (low-granularity function +logging) to Tor. Right now it doesn't have many users. + **/ diff --git a/src/lib/version/lib_version.dox b/src/lib/version/lib_version.dox index 213e1a1ae..d3d2481ba 100644 --- a/src/lib/version/lib_version.dox +++ b/src/lib/version/lib_version.dox @@ -1,4 +1,4 @@ /** @dir lib/version -@brief lib/version +@brief lib/version: holds the current version of Tor. **/ diff --git a/src/lib/wallclock/lib_wallclock.dox b/src/lib/wallclock/lib_wallclock.dox index 7bb2b075d..a024425ea 100644 --- a/src/lib/wallclock/lib_wallclock.dox +++ b/src/lib/wallclock/lib_wallclock.dox @@ -1,4 +1,12 @@ /** @dir lib/wallclock -@brief lib/wallclock +@brief lib/wallclock: Inspect and manipulate the current time. + +This module handles our concept of "what time is it" or "what time does the +world agree it is?" Generally, if you want something derived from UTC, this +is the module for you. + +For versions of the time that are more local, more monotonic, or more +accurate, see \ref src/lib/time "lib/time". + **/

1 0

[tor/master] Doxygen: use \refdir everywhere.
by nickm＠torproject.org 05 Nov '19

05 Nov '19

commit 9b13191192eefd79a1bfa5fbbd2e45c06ff1e005 Author: Nick Mathewson <nickm(a)torproject.org> Date: Mon Nov 4 11:12:27 2019 -0500 Doxygen: use \refdir everywhere. This commit was generated with: find src -name '*.dox' |xargs perl -i -pe 's{\\ref src/(\S+) \"\S+}{\\refdir{$1}};' --- Doxyfile.in | 1 + src/lib/dispatch/lib_dispatch.dox | 2 +- src/lib/lib.dox | 82 +++++++++++++-------------- src/lib/log/lib_log.dox | 2 +- src/lib/smartlist_core/lib_smartlist_core.dox | 2 +- src/lib/wallclock/lib_wallclock.dox | 2 +- 6 files changed, 46 insertions(+), 45 deletions(-) diff --git a/Doxyfile.in b/Doxyfile.in index bb0d75cc9..547a7db19 100644 --- a/Doxyfile.in +++ b/Doxyfile.in @@ -255,6 +255,7 @@ TAB_SIZE = 8 # a double escape (\\{ and \\}) ALIASES = + ALIASES += refdir{1}="\ref @top_srcdir@/src/\1 \"\1\"" # This tag can be used to specify a number of word-keyword mappings (TCL only). diff --git a/src/lib/dispatch/lib_dispatch.dox b/src/lib/dispatch/lib_dispatch.dox index 24a4b79e3..955b7df64 100644 --- a/src/lib/dispatch/lib_dispatch.dox +++ b/src/lib/dispatch/lib_dispatch.dox @@ -6,7 +6,7 @@ This module provides a general in-process "message dispatch" system in which typed messages are sent on channels. The dispatch.h header has far more information. -It is used by by \ref src/lib/pubsub "lib/pubsub" to implement our general +It is used by by \refdir{lib/pubsub} to implement our general inter-module publish/subscribe system. This is not a fancy multi-threaded many-to-many dispatcher as you may be used diff --git a/src/lib/lib.dox b/src/lib/lib.dox index 1d3bc3a3f..b4babf798 100644 --- a/src/lib/lib.dox +++ b/src/lib/lib.dox @@ -14,125 +14,125 @@ modules, sorted from lowest to highest level, by running As of this writing, the library modules are (from lowest to highest level): - - \ref src/lib/cc "lib/cc" -- Macros for managing the C compiler and + - \refdir{lib/cc} -- Macros for managing the C compiler and language. - - \ref src/lib/version "lib/version" -- Holds the current version of Tor. + - \refdir{lib/version} -- Holds the current version of Tor. - - \ref src/lib/testsupport "lib/testsupport" -- Helpers for making + - \refdir{lib/testsupport} -- Helpers for making test-only code, and test mocking support. - - \ref src/lib/defs "lib/defs" -- Lowest-level constants. + - \refdir{lib/defs} -- Lowest-level constants. - - \ref src/lib/subsys "lib/subsys" -- Types used for declaring a + - \refdir{lib/subsys} -- Types used for declaring a "subsystem". (_A subsystem is a module with support for initialization, shutdown, configuration, and so on._) - - \ref src/lib/conf "lib/conf" -- For declaring configuration options. + - \refdir{lib/conf} -- For declaring configuration options. - - \ref src/lib/arch "lib/arch" -- For handling differences in CPU + - \refdir{lib/arch} -- For handling differences in CPU architecture. - - \ref src/lib/err "lib/err" -- Lowest-level error handling code. + - \refdir{lib/err} -- Lowest-level error handling code. - - \ref src/lib/malloc "lib/malloc" -- Memory management. + - \refdir{lib/malloc} -- Memory management. management. - - \ref src/lib/intmath "lib/intmath" -- Integer mathematics. + - \refdir{lib/intmath} -- Integer mathematics. - - \ref src/lib/fdio "lib/fdio" -- For + - \refdir{lib/fdio} -- For reading and writing n file descriptors. - - \ref src/lib/lock "lib/lock" -- Simple locking support. + - \refdir{lib/lock} -- Simple locking support. (_Lower-level than the rest of the threading code._) - - \ref src/lib/ctime "lib/ctime" -- Constant-time code to avoid + - \refdir{lib/ctime} -- Constant-time code to avoid side-channels. - - \ref src/lib/string "lib/string" -- Low-level string manipulation. + - \refdir{lib/string} -- Low-level string manipulation. - - \ref src/lib/wallclock "lib/wallclock" -- + - \refdir{lib/wallclock} -- For inspecting and manipulating the current (UTC) time. - - \ref src/lib/osinfo "lib/osinfo" -- For inspecting the OS version + - \refdir{lib/osinfo} -- For inspecting the OS version and capabilities. - - \ref src/lib/smartlist_core "lib/smartlist_core" -- The bare-bones + - \refdir{lib/smartlist_core} -- The bare-bones pieces of our dynamic array ("smartlist") implementation. - - \ref src/lib/log "lib/log" -- Log messages to files, syslogs, etc. + - \refdir{lib/log} -- Log messages to files, syslogs, etc. - - \ref src/lib/container "lib/container" -- General purpose containers, + - \refdir{lib/container} -- General purpose containers, including dynamic arrays ("smartlists"), hashtables, bit arrays, etc. - - \ref src/lib/trace "lib/trace" -- A general-purpose API + - \refdir{lib/trace} -- A general-purpose API function-tracing functionality Tor. (_Currently not much used._) - - \ref src/lib/thread "lib/thread" -- Threading compatibility and utility + - \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 \ref src/lib/evloop "lib/evloop"). + in \refdir{lib/evloop} - - \ref src/lib/term "lib/term" -- Terminal manipulation + - \refdir{lib/term} -- Terminal manipulation (like reading a password from the user). - - \ref src/lib/memarea "lib/memarea" -- A fast + - \refdir{lib/memarea} -- A fast "arena" style allocator, where the data is freed all at once. - - \ref src/lib/encoding "lib/encoding" -- Encoding + - \refdir{lib/encoding} -- Encoding data in various formats, datatypes, and transformations. - - \ref src/lib/dispatch "lib/dispatch" -- A general-purpose in-process + - \refdir{lib/dispatch} -- A general-purpose in-process message delivery system. - - \ref src/lib/sandbox "lib/sandbox" -- Our Linux seccomp2 sandbox + - \refdir{lib/sandbox} -- Our Linux seccomp2 sandbox implementation. - - \ref src/lib/pubsub "lib/pubsub" -- Code and macros to implement our + - \refdir{lib/pubsub} -- Code and macros to implement our publish/subscribe message passing system. - - \ref src/lib/fs "lib/fs" -- Utility and compatibility code for + - \refdir{lib/fs} -- Utility and compatibility code for manipulating files, filenames, directories, and so on. - - \ref src/lib/confmgt "lib/confmgt" -- Code to parse, encode, and + - \refdir{lib/confmgt} -- Code to parse, encode, and manipulate our configuration files, state files, and so forth. - - \ref src/lib/crypt_ops "lib/crypt_ops" -- Cryptographic operations. This + - \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. - - \ref src/lib/meminfo "lib/meminfo" -- Functions for inspecting our + - \refdir{lib/meminfo} -- Functions for inspecting our memory usage, if the malloc implementation exposes that to us. - - \ref src/lib/time "lib/time" -- Higher level time functions, including + - \refdir{lib/time} -- Higher level time functions, including fine-gained and monotonic timers. - - \ref src/lib/math "lib/math" -- Floating-point mathematical utilities, + - \refdir{lib/math} -- Floating-point mathematical utilities, including compatibility code, and probability distributions. - - \ref src/lib/buf "lib/buf" -- A general purpose queued buffer + - \refdir{lib/buf} -- A general purpose queued buffer implementation, similar to the BSD kernel's "mbuf" structure. - - \ref src/lib/net "lib/net" -- Networking code, including address + - \refdir{lib/net} -- Networking code, including address manipulation, compatibility wrappers, - - \ref src/lib/compress "lib/compress" -- A compatibility wrapper around + - \refdir{lib/compress} -- A compatibility wrapper around several compression libraries, currently including zlib, zstd, and lzma. - - \ref src/lib/geoip "lib/geoip" -- Utilities to manage geoip (IP to + - \refdir{lib/geoip} -- Utilities to manage geoip (IP to country) lookups and formats. - - \ref src/lib/tls "lib/tls" -- Compatibility wrappers around the library + - \refdir{lib/tls} -- Compatibility wrappers around the library (NSS or OpenSSL, depending on configuration) that Tor uses to implement the TLS link security protocol. - - \ref src/lib/evloop "lib/evloop" -- Tools to manage the event loop and + - \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. - - \ref src/lib/process "lib/process" -- Utilities and compatibility code + - \refdir{lib/process} -- Utilities and compatibility code to launch and manage subprocesses. ### What belongs in lib? diff --git a/src/lib/log/lib_log.dox b/src/lib/log/lib_log.dox index b6d242917..a772dc320 100644 --- a/src/lib/log/lib_log.dox +++ b/src/lib/log/lib_log.dox @@ -3,7 +3,7 @@ @brief lib/log: Log messages to files, syslogs, etc. You can think of this as the logical "midpoint" of the -\ref src/lib "library code": much of the higher-level code is higher-level +\refdir{lib} 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. diff --git a/src/lib/smartlist_core/lib_smartlist_core.dox b/src/lib/smartlist_core/lib_smartlist_core.dox index 5e3ffd1f0..73c3b6905 100644 --- a/src/lib/smartlist_core/lib_smartlist_core.dox +++ b/src/lib/smartlist_core/lib_smartlist_core.dox @@ -5,7 +5,7 @@ A `smartlist_t` is a dynamic array type for holding `void *`. We use it throughout the rest of the codebase. -There are higher-level pieces in \ref src/lib/container "lib/container", but +There are higher-level pieces in \refdir{lib/container} but the ones in lib/smartlist_core are used by the logging code, and therefore cannot use the logging code. diff --git a/src/lib/wallclock/lib_wallclock.dox b/src/lib/wallclock/lib_wallclock.dox index 03966aecc..69dff85b5 100644 --- a/src/lib/wallclock/lib_wallclock.dox +++ b/src/lib/wallclock/lib_wallclock.dox @@ -7,6 +7,6 @@ world agree it is?" Generally, if you want something derived from UTC, this is the module for you. For versions of the time that are more local, more monotonic, or more -accurate, see \ref src/lib/time "lib/time". +accurate, see \refdir{lib/time} **/

1 0

[tor/master] Doxygen: fix a remaining \ref-to-directory
by nickm＠torproject.org 05 Nov '19

05 Nov '19

commit fd271363296b89cb3a11e97e507546b3600fde59 Author: Nick Mathewson <nickm(a)torproject.org> Date: Mon Nov 4 11:13:30 2019 -0500 Doxygen: fix a remaining \ref-to-directory This one was missed by the perl script in the last commit because it spanned a newline. --- src/lib/lib.dox | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/lib/lib.dox b/src/lib/lib.dox index b4babf798..da6f7b2d2 100644 --- a/src/lib/lib.dox +++ b/src/lib/lib.dox @@ -70,9 +70,9 @@ level): 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} + functionality, other than low-level locks (which are in + \refdir{lib/lock} and workqueue/threadpool code (which belongs + in \refdir{lib/evloop}.) - \refdir{lib/term} -- Terminal manipulation (like reading a password from the user).

1 0

[tor/master] Doxygen: document the rest of the directories in lib.
by nickm＠torproject.org 05 Nov '19

05 Nov '19

commit 76e8effc7b8e747cd34188a5a27e6d792a66ba7e Author: Nick Mathewson <nickm(a)torproject.org> Date: Mon Nov 4 11:51:38 2019 -0500 Doxygen: document the rest of the directories in lib. (This copies documentation from doc/HACKING/design, and edits for concisensess and clarity.) --- src/lib/buf/lib_buf.dox | 13 ++++++++++- src/lib/compress/lib_compress.dox | 6 ++++- src/lib/confmgt/lib_confmgt.dox | 7 +++++- src/lib/crypt_ops/lib_crypt_ops.dox | 10 ++++++++- src/lib/evloop/lib_evloop.dox | 7 +++++- src/lib/fdio/lib_fdio.dox | 2 +- src/lib/fs/lib_fs.dox | 9 +++++++- src/lib/geoip/lib_geoip.dox | 3 ++- src/lib/intmath/lib_intmath.dox | 2 +- src/lib/lib.dox | 44 +++++++++++-------------------------- src/lib/math/lib_math.dox | 6 ++++- src/lib/memarea/lib_memarea.dox | 2 +- src/lib/meminfo/lib_meminfo.dox | 5 ++++- src/lib/net/lib_net.dox | 6 ++++- src/lib/process/lib_process.dox | 2 +- src/lib/pubsub/lib_pubsub.dox | 14 +++++++++++- src/lib/sandbox/lib_sandbox.dox | 2 +- src/lib/term/lib_term.dox | 2 +- src/lib/thread/lib_thread.dox | 7 +++++- src/lib/time/lib_time.dox | 9 +++++++- src/lib/tls/lib_tls.dox | 11 +++++++++- src/lib/wallclock/lib_wallclock.dox | 3 ++- 22 files changed, 120 insertions(+), 52 deletions(-) diff --git a/src/lib/buf/lib_buf.dox b/src/lib/buf/lib_buf.dox index 9caaba07f..a2ac23ee4 100644 --- a/src/lib/buf/lib_buf.dox +++ b/src/lib/buf/lib_buf.dox @@ -1,4 +1,15 @@ /** @dir /lib/buf -@brief lib/buf +@brief lib/buf: An efficient byte queue. + +This module defines the buf_t type, which is used throughout our networking +code. The implementation is a singly-linked queue of buffer chunks, similar +to the BSD kernel's +["mbuf"](https://www.freebsd.org/cgi/man.cgi?query=mbuf&sektion=9) structure. + +The buf_t type is also reasonable for use in constructing long strings. + +See \refdir{lib/net} for networking code that uses buf_t, and +\refdir{lib/tls} for cryptographic code that uses buf_t. + **/ diff --git a/src/lib/compress/lib_compress.dox b/src/lib/compress/lib_compress.dox index b1b090235..599126901 100644 --- a/src/lib/compress/lib_compress.dox +++ b/src/lib/compress/lib_compress.dox @@ -1,4 +1,8 @@ /** @dir /lib/compress -@brief lib/compress +@brief lib/compress: Wraps several compression libraries + +Currently supported are zlib (mandatory), zstd (optional), and lzma +(optional). + **/ diff --git a/src/lib/confmgt/lib_confmgt.dox b/src/lib/confmgt/lib_confmgt.dox index 86cb04e84..d18fa304c 100644 --- a/src/lib/confmgt/lib_confmgt.dox +++ b/src/lib/confmgt/lib_confmgt.dox @@ -1,4 +1,9 @@ /** @dir /lib/confmgt -@brief lib/confmgt +@brief lib/confmgt: Parse, encode, manipulate configuration files. + +This logic is used in common by our state files (statefile.c) and +configuration files (config.c) to manage a set of named, typed fields, +reading and writing them to disk and to the controller. + **/ diff --git a/src/lib/crypt_ops/lib_crypt_ops.dox b/src/lib/crypt_ops/lib_crypt_ops.dox index 0c3e4d7c3..d856d93be 100644 --- a/src/lib/crypt_ops/lib_crypt_ops.dox +++ b/src/lib/crypt_ops/lib_crypt_ops.dox @@ -1,4 +1,12 @@ /** @dir /lib/crypt_ops -@brief lib/crypt_ops +@brief 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. + +It wraps our two major cryptographic backends (OpenSSL or NSS, as configured +by the user), and also wraps other cryptographic code in src/ext. + **/ diff --git a/src/lib/evloop/lib_evloop.dox b/src/lib/evloop/lib_evloop.dox index f60f41968..52fcf6775 100644 --- a/src/lib/evloop/lib_evloop.dox +++ b/src/lib/evloop/lib_evloop.dox @@ -1,4 +1,9 @@ /** @dir /lib/evloop -@brief lib/evloop +@brief lib/evloop: Low-level event loop. + +This modules has tools to manage the [libevent](https://libevent.org/) event +loop and related functionality, in order to implement asynchronous +networking, timers, periodic events, and other scheduling tasks. + **/ diff --git a/src/lib/fdio/lib_fdio.dox b/src/lib/fdio/lib_fdio.dox index 2615b9791..9e2fda617 100644 --- a/src/lib/fdio/lib_fdio.dox +++ b/src/lib/fdio/lib_fdio.dox @@ -1,6 +1,6 @@ /** @dir /lib/fdio -@brief lib/fdio Code to read/write on file descriptors. +@brief lib/fdio: Code to read/write on file descriptors. (This module also handles sockets, on platforms where a socket is not a kind of fd.) diff --git a/src/lib/fs/lib_fs.dox b/src/lib/fs/lib_fs.dox index 33ff16928..4466250bb 100644 --- a/src/lib/fs/lib_fs.dox +++ b/src/lib/fs/lib_fs.dox @@ -1,4 +1,11 @@ /** @dir /lib/fs -@brief lib/fs +@brief lib/fs: Files, filenames, directories, etc. + +This module is mostly a set of compatibility wrappers around +operating-system-specific filesystem access. + +It also contains a set of convenience functions for safely writing to files, +creating directories, and so on. + **/ diff --git a/src/lib/geoip/lib_geoip.dox b/src/lib/geoip/lib_geoip.dox index 454dcb687..da1123640 100644 --- a/src/lib/geoip/lib_geoip.dox +++ b/src/lib/geoip/lib_geoip.dox @@ -1,4 +1,5 @@ /** @dir /lib/geoip -@brief lib/geoip +@brief lib/geoip: IP-to-country mapping + **/ diff --git a/src/lib/intmath/lib_intmath.dox b/src/lib/intmath/lib_intmath.dox index 33fa0f02b..e9b704470 100644 --- a/src/lib/intmath/lib_intmath.dox +++ b/src/lib/intmath/lib_intmath.dox @@ -1,4 +1,4 @@ /** @dir /lib/intmath -@brief lib/intmath Integer mathematics. +@brief lib/intmath: Integer mathematics. **/ diff --git a/src/lib/lib.dox b/src/lib/lib.dox index da6f7b2d2..fdf2c4768 100644 --- a/src/lib/lib.dox +++ b/src/lib/lib.dox @@ -69,10 +69,7 @@ level): - \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 - \refdir{lib/lock} and workqueue/threadpool code (which belongs - in \refdir{lib/evloop}.) + - \refdir{lib/thread} -- Mid-level Threading. - \refdir{lib/term} -- Terminal manipulation (like reading a password from the user). @@ -89,19 +86,13 @@ level): - \refdir{lib/sandbox} -- Our Linux seccomp2 sandbox implementation. - - \refdir{lib/pubsub} -- Code and macros to implement our - publish/subscribe message passing system. + - \refdir{lib/pubsub} -- A publish/subscribe message passing system. - - \refdir{lib/fs} -- Utility and compatibility code for - manipulating files, filenames, directories, and so on. + - \refdir{lib/fs} -- Files, filenames, directories, etc. - - \refdir{lib/confmgt} -- Code to parse, encode, and - manipulate our configuration files, state files, and so forth. + - \refdir{lib/confmgt} -- Parse, encode, and manipulate onfiguration files. - - \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/crypt_ops} -- Cryptographic operations. - \refdir{lib/meminfo} -- Functions for inspecting our memory usage, if the malloc implementation exposes that to us. @@ -109,31 +100,22 @@ level): - \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/math} -- Floating-point mathematical utilities. - - \refdir{lib/buf} -- A general purpose queued buffer - implementation, similar to the BSD kernel's "mbuf" structure. + - \refdir{lib/buf} -- An efficient byte queue. - \refdir{lib/net} -- Networking code, including address - manipulation, compatibility wrappers, + manipulation, compatibility wrappers, etc. - - \refdir{lib/compress} -- A compatibility wrapper around - several compression libraries, currently including zlib, zstd, and lzma. + - \refdir{lib/compress} -- Wraps several compression libraries. - - \refdir{lib/geoip} -- Utilities to manage geoip (IP to - country) lookups and formats. + - \refdir{lib/geoip} -- IP-to-country mapping. - - \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/tls} -- TLS library wrappers. - - \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/evloop} -- Low-level event-loop. - - \refdir{lib/process} -- Utilities and compatibility code - to launch and manage subprocesses. + - \refdir{lib/process} -- Launch and manage subprocesses. ### What belongs in lib? diff --git a/src/lib/math/lib_math.dox b/src/lib/math/lib_math.dox index 0073731dc..f20d7092b 100644 --- a/src/lib/math/lib_math.dox +++ b/src/lib/math/lib_math.dox @@ -1,4 +1,8 @@ /** @dir /lib/math -@brief lib/math +@brief lib/math: Floating-point math utilities. + +This module includes a bunch of floating-point compatibility code, and +implementations for several probability distributions. + **/ diff --git a/src/lib/memarea/lib_memarea.dox b/src/lib/memarea/lib_memarea.dox index eaca28604..9a7c8c4b2 100644 --- a/src/lib/memarea/lib_memarea.dox +++ b/src/lib/memarea/lib_memarea.dox @@ -1,6 +1,6 @@ /** @dir /lib/memarea -@brief lib/memarea A fast arena-style allocator. +@brief lib/memarea: A fast arena-style allocator. This module has a fast "arena" style allocator, where memory is freed all at once. This kind of allocation is very fast and avoids fragmentation, at the diff --git a/src/lib/meminfo/lib_meminfo.dox b/src/lib/meminfo/lib_meminfo.dox index 433d6859e..b57e60525 100644 --- a/src/lib/meminfo/lib_meminfo.dox +++ b/src/lib/meminfo/lib_meminfo.dox @@ -1,4 +1,7 @@ /** @dir /lib/meminfo -@brief lib/meminfo +@brief lib/meminfo: Inspecting malloc() usage. + +Only available when malloc() provides mallinfo() or something similar. + **/ diff --git a/src/lib/net/lib_net.dox b/src/lib/net/lib_net.dox index ca3c56a94..b4c00405d 100644 --- a/src/lib/net/lib_net.dox +++ b/src/lib/net/lib_net.dox @@ -1,4 +1,8 @@ /** @dir /lib/net -@brief lib/net +@brief lib/net: Low-level network-related code. + +This module includes address manipulation, compatibility wrappers, +convenience functions, and so on. + **/ diff --git a/src/lib/process/lib_process.dox b/src/lib/process/lib_process.dox index 9059d6666..723c9f193 100644 --- a/src/lib/process/lib_process.dox +++ b/src/lib/process/lib_process.dox @@ -1,4 +1,4 @@ /** @dir /lib/process -@brief lib/process +@brief lib/process: Launch and manage subprocesses. **/ diff --git a/src/lib/pubsub/lib_pubsub.dox b/src/lib/pubsub/lib_pubsub.dox index 3fd026cc0..c03366012 100644 --- a/src/lib/pubsub/lib_pubsub.dox +++ b/src/lib/pubsub/lib_pubsub.dox @@ -1,4 +1,16 @@ /** @dir /lib/pubsub -@brief lib/pubsub +@brief lib/pubsub: Publish-subscribe message passing. + +This module wraps the \refdir{lib/dispatch} module, to provide a more +ergonomic and type-safe approach to message passing. + +In general, we favor this mechanism for cases where higher-level modules +need to be notified when something happens in lower-level modules. (The +alternative would be calling up from the lower-level modules, which +would be error-prone; or maintaining lists of function-pointers, which +would be clumsy and tend to complicate the call graph.) + +See pubsub.c for more information. + **/ diff --git a/src/lib/sandbox/lib_sandbox.dox b/src/lib/sandbox/lib_sandbox.dox index 91d056d46..48eddac68 100644 --- a/src/lib/sandbox/lib_sandbox.dox +++ b/src/lib/sandbox/lib_sandbox.dox @@ -1,6 +1,6 @@ /** @dir /lib/sandbox -@brief lib/sandbox Linux seccomp2-based sandbox. +@brief lib/sandbox: Linux seccomp2-based sandbox. This module uses Linux's seccomp2 facility via the [`libseccomp` library](https://github.com/seccomp/libseccomp), to restrict diff --git a/src/lib/term/lib_term.dox b/src/lib/term/lib_term.dox index d6010cb69..3bf2f960a 100644 --- a/src/lib/term/lib_term.dox +++ b/src/lib/term/lib_term.dox @@ -1,4 +1,4 @@ /** @dir /lib/term -@brief lib/term +@brief lib/term: Terminal operations (password input). **/ diff --git a/src/lib/thread/lib_thread.dox b/src/lib/thread/lib_thread.dox index b1e24d824..2773aa009 100644 --- a/src/lib/thread/lib_thread.dox +++ b/src/lib/thread/lib_thread.dox @@ -1,4 +1,9 @@ /** @dir /lib/thread -@brief lib/thread +@brief lib/thread: Mid-level threading. + +This module contains compatibility and convenience code for multithreading, +except for low-level locks (which are in \refdir{lib/lock} and +workqueue/threadpool code (which belongs in \refdir{lib/evloop}.) + **/ diff --git a/src/lib/time/lib_time.dox b/src/lib/time/lib_time.dox index 8e1e30859..b76a31fb9 100644 --- a/src/lib/time/lib_time.dox +++ b/src/lib/time/lib_time.dox @@ -1,4 +1,11 @@ /** @dir /lib/time -@brief lib/time +@brief lib/time: Higher-level time functions + +This includes both fine-grained timers and monotonic timers, along with +wrappers for them to try to improve efficiency. + +For "what time is it" in UTC, see \refdir{lib/wallclock}. For parsing and +encoding times and dates, see \refdir{lib/encoding}. + **/ diff --git a/src/lib/tls/lib_tls.dox b/src/lib/tls/lib_tls.dox index 9558687f6..f0dba269e 100644 --- a/src/lib/tls/lib_tls.dox +++ b/src/lib/tls/lib_tls.dox @@ -1,4 +1,13 @@ /** @dir /lib/tls -@brief lib/tls +@brief lib/tls: TLS library wrappers + +This module has compatibility wrappers around the library (NSS or OpenSSL, +depending on configuration) that Tor uses to implement the TLS link security +protocol. + +It also implements the logic for some legacy TLS protocol usage we used to +support in old versions of Tor, involving conditional delivery of certificate +chains (v1 link protocol) and conditional renegotiation (v2 link protocol). + **/ diff --git a/src/lib/wallclock/lib_wallclock.dox b/src/lib/wallclock/lib_wallclock.dox index 69dff85b5..7d43fa612 100644 --- a/src/lib/wallclock/lib_wallclock.dox +++ b/src/lib/wallclock/lib_wallclock.dox @@ -7,6 +7,7 @@ world agree it is?" Generally, if you want something derived from UTC, this is the module for you. For versions of the time that are more local, more monotonic, or more -accurate, see \refdir{lib/time} +accurate, see \refdir{lib/time}. For parsing and encoding times and dates, +see \refdir{lib/encoding}. **/

1 0

[tor/master] directory-level documentation for feature/*
by nickm＠torproject.org 05 Nov '19

05 Nov '19

commit a33d1dce8affdaef7d84a6cc2c23c3821192cb87 Author: Nick Mathewson <nickm(a)torproject.org> Date: Mon Nov 4 17:07:38 2019 -0500 directory-level documentation for feature/* --- src/feature/api/feature_api.dox | 2 +- src/feature/client/feature_client.dox | 5 ++++- src/feature/control/feature_control.dox | 8 +++++++- src/feature/dirauth/feature_dirauth.dox | 4 +++- src/feature/dircache/feature_dircache.dox | 6 +++++- src/feature/dirclient/feature_dirclient.dox | 7 ++++++- src/feature/dircommon/feature_dircommon.dox | 7 ++++++- src/feature/dirparse/feature_dirparse.dox | 8 +++++++- src/feature/hibernate/feature_hibernate.dox | 14 +++++++++++++- src/feature/hs/feature_hs.dox | 3 ++- src/feature/hs_common/feature_hs_common.dox | 3 ++- src/feature/keymgt/feature_keymgt.dox | 3 ++- src/feature/nodelist/feature_nodelist.dox | 2 +- src/feature/relay/feature_relay.dox | 4 +++- src/feature/rend/feature_rend.dox | 3 ++- src/feature/stats/feature_stats.dox | 10 +++++++++- 16 files changed, 73 insertions(+), 16 deletions(-) diff --git a/src/feature/api/feature_api.dox b/src/feature/api/feature_api.dox index 524e3c68e..06112120c 100644 --- a/src/feature/api/feature_api.dox +++ b/src/feature/api/feature_api.dox @@ -1,4 +1,4 @@ /** @dir /feature/api -@brief feature/api +@brief feature/api: In-process interface to starting/stopping Tor. **/ diff --git a/src/feature/client/feature_client.dox b/src/feature/client/feature_client.dox index 755777ec1..a8263b494 100644 --- a/src/feature/client/feature_client.dox +++ b/src/feature/client/feature_client.dox @@ -1,4 +1,7 @@ /** @dir /feature/client -@brief feature/client +@brief feature/client: Client-specific code + +(There is also a bunch of client-specific code in other modules.) + **/ diff --git a/src/feature/control/feature_control.dox b/src/feature/control/feature_control.dox index 44fda7989..a0bf9413a 100644 --- a/src/feature/control/feature_control.dox +++ b/src/feature/control/feature_control.dox @@ -1,4 +1,10 @@ /** @dir /feature/control -@brief feature/control +@brief feature/control: Controller API. + +The Controller API is a text-based protocol that another program (or another +thread, if you're running Tor in-process) can use to configure and control +Tor while it is running. The current protocol is documented in +[control-spec.txt](https://gitweb.torproject.org/torspec.git/tree/control-spec.txt). + **/ diff --git a/src/feature/dirauth/feature_dirauth.dox b/src/feature/dirauth/feature_dirauth.dox index fa209dfb0..93c680e47 100644 --- a/src/feature/dirauth/feature_dirauth.dox +++ b/src/feature/dirauth/feature_dirauth.dox @@ -1,4 +1,6 @@ /** @dir /feature/dirauth -@brief feature/dirauth +@brief feature/dirauth: Directory authority implementation. + +This module handles running Tor as a directory authority. **/ diff --git a/src/feature/dircache/feature_dircache.dox b/src/feature/dircache/feature_dircache.dox index 4447d0cd2..ef8a51aa9 100644 --- a/src/feature/dircache/feature_dircache.dox +++ b/src/feature/dircache/feature_dircache.dox @@ -1,4 +1,8 @@ /** @dir /feature/dircache -@brief feature/dircache +@brief feature/dircache: Run as a directory cache server + +This module handles the directory caching functionality that all relays may +provide, for serving cached directory objects to objects. + **/ diff --git a/src/feature/dirclient/feature_dirclient.dox b/src/feature/dirclient/feature_dirclient.dox index 65d3d26d0..0cbae6911 100644 --- a/src/feature/dirclient/feature_dirclient.dox +++ b/src/feature/dirclient/feature_dirclient.dox @@ -1,4 +1,9 @@ /** @dir /feature/dirclient -@brief feature/dirclient +@brief feature/dirclient: Directory client implementation. + +The code here is used by all Tor instances that need to download directory +information. Currently, that is all of them, since even authorities need to +launch downloads to learn about relays that other authorities have listed. + **/ diff --git a/src/feature/dircommon/feature_dircommon.dox b/src/feature/dircommon/feature_dircommon.dox index f647b2928..2d9866da0 100644 --- a/src/feature/dircommon/feature_dircommon.dox +++ b/src/feature/dircommon/feature_dircommon.dox @@ -1,4 +1,9 @@ /** @dir /feature/dircommon -@brief feature/dircommon +@brief feature/dircommon: Directory client and server shared code + +This module has the code that directory clients (anybody who download +information about relays) and directory servers (anybody who serves such +information) share in common. + **/ diff --git a/src/feature/dirparse/feature_dirparse.dox b/src/feature/dirparse/feature_dirparse.dox index 934d8e424..4f2136b02 100644 --- a/src/feature/dirparse/feature_dirparse.dox +++ b/src/feature/dirparse/feature_dirparse.dox @@ -1,4 +1,10 @@ /** @dir /feature/dirparse -@brief feature/dirparse +@brief feature/dirparse: Parsing Tor directory objects + +We define a number of "directory objects" in +[dir-spec.txt](https://gitweb.torproject.org/torspec.git/tree/dir-spec.txt), +all of them using a common line-oriented meta-format. This module is used by +other parts of Tor to parse them. + **/ diff --git a/src/feature/hibernate/feature_hibernate.dox b/src/feature/hibernate/feature_hibernate.dox index 55d89d1c2..eebb2d51a 100644 --- a/src/feature/hibernate/feature_hibernate.dox +++ b/src/feature/hibernate/feature_hibernate.dox @@ -1,4 +1,16 @@ /** @dir /feature/hibernate -@brief feature/hibernate +@brief feature/hibernate: Bandwidth accounting and hibernation (!) + +This module implements two features that are only somewhat related, and +should probably be separated in the future. One feature is bandwidth +accounting (making sure we use no more than so many gigabytes in a day) and +hibernation (avoiding network activity while we have used up all/most of our +configured gigabytes). The other feature is clean shutdown, where we stop +accepting new connections for a while and give the old ones time to close. + +The two features are related only in the sense that "soft hibernation" (being +almost out of ) is very close to the "shutting down" state. But it would be +better in the long run to make the two completely separate. + **/ diff --git a/src/feature/hs/feature_hs.dox b/src/feature/hs/feature_hs.dox index d93a8c274..35a574d01 100644 --- a/src/feature/hs/feature_hs.dox +++ b/src/feature/hs/feature_hs.dox @@ -1,4 +1,5 @@ /** @dir /feature/hs -@brief feature/hs +@brief feature/hs: v3 (current) onion service protocol + **/ diff --git a/src/feature/hs_common/feature_hs_common.dox b/src/feature/hs_common/feature_hs_common.dox index 10bc9492c..85d758587 100644 --- a/src/feature/hs_common/feature_hs_common.dox +++ b/src/feature/hs_common/feature_hs_common.dox @@ -1,4 +1,5 @@ /** @dir /feature/hs_common -@brief feature/hs_common +@brief feature/hs_common: Common to v2 (old) and v3 (current) onion services + **/ diff --git a/src/feature/keymgt/feature_keymgt.dox b/src/feature/keymgt/feature_keymgt.dox index c59843c25..acc840eb2 100644 --- a/src/feature/keymgt/feature_keymgt.dox +++ b/src/feature/keymgt/feature_keymgt.dox @@ -1,4 +1,5 @@ /** @dir /feature/keymgt -@brief feature/keymgt +@brief feature/keymgt: Store keys for relays, authorities, etc. + **/ diff --git a/src/feature/nodelist/feature_nodelist.dox b/src/feature/nodelist/feature_nodelist.dox index eecddcfb5..0b25dd246 100644 --- a/src/feature/nodelist/feature_nodelist.dox +++ b/src/feature/nodelist/feature_nodelist.dox @@ -1,4 +1,4 @@ /** @dir /feature/nodelist -@brief feature/nodelist +@brief feature/nodelist: Download and manage a list of relays **/ diff --git a/src/feature/relay/feature_relay.dox b/src/feature/relay/feature_relay.dox index 4652bacaf..686781825 100644 --- a/src/feature/relay/feature_relay.dox +++ b/src/feature/relay/feature_relay.dox @@ -1,4 +1,6 @@ /** @dir /feature/relay -@brief feature/relay +@brief feature/relay: Relay-specific code + +(There is also a bunch of relay-specific code in other modules.) **/ diff --git a/src/feature/rend/feature_rend.dox b/src/feature/rend/feature_rend.dox index 759d2155d..e92406804 100644 --- a/src/feature/rend/feature_rend.dox +++ b/src/feature/rend/feature_rend.dox @@ -1,4 +1,5 @@ /** @dir /feature/rend -@brief feature/rend +@brief feature/rend: version 2 (old) hidden services + **/ diff --git a/src/feature/stats/feature_stats.dox b/src/feature/stats/feature_stats.dox index 9b9ed87d1..0ced00ce5 100644 --- a/src/feature/stats/feature_stats.dox +++ b/src/feature/stats/feature_stats.dox @@ -1,4 +1,12 @@ /** @dir /feature/stats -@brief feature/stats +@brief feature/stats: Relay statistics. Also, port prediction. + +This module collects anonymized relay statistics in order to publish them in +relays' routerinfo and extrainfo documents. + +Additionally, it contains predict_ports.c, which remembers which ports we've +visited recently as a client, so we can make sure we have open circuits that +support them. + **/

1 0

[tor/master] Move doc/HACKING/design/01b-collections.md into doxygen.
by nickm＠torproject.org 05 Nov '19

05 Nov '19

commit 211a2e0a8f06c65a2b8458b53d7a61a5fa21aac1 Author: Nick Mathewson <nickm(a)torproject.org> Date: Mon Nov 4 12:07:38 2019 -0500 Move doc/HACKING/design/01b-collections.md into doxygen. --- doc/HACKING/design/01b-collections.md | 45 ---------------------------------- src/lib/container/lib_container.dox | 46 +++++++++++++++++++++++++++++++++++ 2 files changed, 46 insertions(+), 45 deletions(-) diff --git a/doc/HACKING/design/01b-collections.md b/doc/HACKING/design/01b-collections.md deleted file mode 100644 index ed6fdc907..000000000 --- a/doc/HACKING/design/01b-collections.md +++ /dev/null @@ -1,45 +0,0 @@ - -## Collections in tor - -### Smartlists: Neither lists, nor especially smart. - -For historical reasons, we call our dynamic-allocated array type -`smartlist_t`. It can grow or shrink as elements are added and removed. - -All smartlists hold an array of `void *`. Whenever you expose a smartlist -in an API you *must* document which types its pointers actually hold. - - - -Smartlists are created empty with `smartlist_new()` and freed with -`smartlist_free()`. See the `containers.h` module documentation for more -information; there are many convenience functions for commonly needed -operations. - - - -### Digest maps, string maps, and more. - -Tor makes frequent use of maps from 160-bit digests, 256-bit digests, -or nul-terminated strings to `void *`. These types are `digestmap_t`, -`digest256map_t`, and `strmap_t` respectively. See the containers.h -module documentation for more information. - -### Intrusive lists and hashtables - -For performance-sensitive cases, we sometimes want to use "intrusive" -collections: ones where the bookkeeping pointers are stuck inside the -structures that belong to the collection. If you've used the -BSD-style sys/queue.h macros, you'll be familiar with these. - -Unfortunately, the `sys/queue.h` macros vary significantly between the -platforms that have them, so we provide our own variants in -`src/ext/tor_queue.h`. - -We also provide an intrusive hashtable implementation in `src/ext/ht.h`. -When you're using it, you'll need to define your own hash -functions. If attacker-induced collisions are a worry here, use the -cryptographic siphash24g function to extract hashes. - - diff --git a/src/lib/container/lib_container.dox b/src/lib/container/lib_container.dox index fb360368d..675aaeef3 100644 --- a/src/lib/container/lib_container.dox +++ b/src/lib/container/lib_container.dox @@ -2,4 +2,50 @@ @dir /lib/container @brief lib/container: Hash tables, dynamic arrays, bit arrays, etc. +### Smartlists: Neither lists, nor especially smart. + +For historical reasons, we call our dynamic-allocated array type +`smartlist_t`. It can grow or shrink as elements are added and removed. + +All smartlists hold an array of `void *`. Whenever you expose a smartlist +in an API you *must* document which types its pointers actually hold. + + + +Smartlists are created empty with `smartlist_new()` and freed with +`smartlist_free()`. See the `containers.h` header documentation for more +information; there are many convenience functions for commonly needed +operations. + +For low-level operations on smartlists, see also +\refdir{lib/smartlist_core}. + + + +### Digest maps, string maps, and more. + +Tor makes frequent use of maps from 160-bit digests, 256-bit digests, +or nul-terminated strings to `void *`. These types are `digestmap_t`, +`digest256map_t`, and `strmap_t` respectively. See the containers.h +module documentation for more information. + +### Intrusive lists and hashtables + +For performance-sensitive cases, we sometimes want to use "intrusive" +collections: ones where the bookkeeping pointers are stuck inside the +structures that belong to the collection. If you've used the +BSD-style sys/queue.h macros, you'll be familiar with these. + +Unfortunately, the `sys/queue.h` macros vary significantly between the +platforms that have them, so we provide our own variants in +`ext/tor_queue.h`. + +We also provide an intrusive hashtable implementation in `ext/ht.h`. +When you're using it, you'll need to define your own hash +functions. If attacker-induced collisions are a worry here, use the +cryptographic siphash24g function to extract hashes. + + + **/

1 0

[tor/master] Move much of 00-overview.md into doxygen.
by nickm＠torproject.org 05 Nov '19

05 Nov '19

commit 607b1ff776b5a5e5c9ba0197b5768751e5b9c68c Author: Nick Mathewson <nickm(a)torproject.org> Date: Mon Nov 4 12:22:58 2019 -0500 Move much of 00-overview.md into doxygen. --- doc/HACKING/design/00-overview.md | 118 ------------------------------------- src/mainpage.dox | 119 ++++++++++++++++++++++++++++++++++++-- 2 files changed, 115 insertions(+), 122 deletions(-) diff --git a/doc/HACKING/design/00-overview.md b/doc/HACKING/design/00-overview.md index ff40a566b..1c14dc8c1 100644 --- a/doc/HACKING/design/00-overview.md +++ b/doc/HACKING/design/00-overview.md @@ -1,124 +1,6 @@ ## Overview ## -This document describes the general structure of the Tor codebase, how -it fits together, what functionality is available for extending Tor, -and gives some notes on how Tor got that way. - -Tor remains a work in progress: We've been working on it for nearly two -decades, and we've learned a lot about good coding since we first -started. This means, however, that some of the older pieces of Tor will -have some "code smell" in them that could stand a brisk -refactoring. So when I describe a piece of code, I'll sometimes give a -note on how it got that way, and whether I still think that's a good -idea. - -The first drafts of this document were written in the Summer and Fall of -2015, when Tor 0.2.6 was the most recent stable version, and Tor 0.2.7 -was under development. There is a revision in progress (as of late -2019), to bring it up to pace with Tor as of version 0.4.2. If you're -reading this far in the future, some things may have changed. Caveat -haxxor! - -This document is not an overview of the Tor protocol. For that, see the -design paper and the specifications at https://spec.torproject.org/ . - -For more information about Tor's coding standards and some helpful -development tools, see doc/HACKING in the Tor repository. - - -### The very high level ### - -Ultimately, Tor runs as an event-driven network daemon: it responds to -network events, signals, and timers by sending and receiving things over -the network. Clients, relays, and directory authorities all use the -same codebase: the Tor process will run as a client, relay, or authority -depending on its configuration. - -Tor has a few major dependencies, including Libevent (used to tell which -sockets are readable and writable), OpenSSL or NSS (used for many encryption -functions, and to implement the TLS protocol), and zlib (used to -compress and uncompress directory information). - -Most of Tor's work today is done in a single event-driven main thread. -Tor also spawns one or more worker threads to handle CPU-intensive -tasks. (Right now, this only includes circuit encryption and the more -expensive compression algorithms.) - -On startup, Tor initializes its libraries, reads and responds to its -configuration files, and launches a main event loop. At first, the only -events that Tor listens for are a few signals (like TERM and HUP), and -one or more listener sockets (for different kinds of incoming -connections). Tor also configures several timers to handle periodic -events. As Tor runs over time, other events will open, and new events -will be scheduled. - -The codebase is divided into a few top-level subdirectories, each of -which contains several sub-modules. - - * `src/ext` -- Code maintained elsewhere that we include in the Tor - source distribution. - - * src/lib` -- Lower-level utility code, not necessarily tor-specific. - - * `src/trunnel` -- Automatically generated code (from the Trunnel - tool): used to parse and encode binary formats. - - * `src/core` -- Networking code that is implements the central parts of - the Tor protocol and main loop. - - * `src/feature` -- Aspects of Tor (like directory management, running a - relay, running a directory authorities, managing a list of nodes, - running and using onion services) that are built on top of the - mainloop code. - - * `src/app` -- Highest-level functionality; responsible for setting up - and configuring the Tor daemon, making sure all the lower-level - modules start up when required, and so on. - - * `src/tools` -- Binaries other than Tor that we produce. Currently this - is tor-resolve, tor-gencert, and the tor_runner.o helper module. - - * `src/test` -- unit tests, regression tests, and a few integration - tests. - -In theory, the above parts of the codebase are sorted from highest-level to -lowest-level, where high-level code is only allowed to invoke lower-level -code, and lower-level code never includes or depends on code of a higher -level. In practice, this refactoring is incomplete: The modules in `src/lib` -are well-factored, but there are many layer violations ("upward -dependencies") in `src/core` and `src/feature`. We aim to eliminate those -over time. - -### Some key high-level abstractions ### - -The most important abstractions at Tor's high-level are Connections, -Channels, Circuits, and Nodes. - -A 'Connection' represents a stream-based information flow. Most -connections are TCP connections to remote Tor servers and clients. (But -as a shortcut, a relay will sometimes make a connection to itself -without actually using a TCP connection. More details later on.) -Connections exist in different varieties, depending on what -functionality they provide. The principle types of connection are -"edge" (eg a socks connection or a connection from an exit relay to a -destination), "OR" (a TLS stream connecting to a relay), "Directory" (an -HTTP connection to learn about the network), and "Control" (a connection -from a controller). - -A 'Circuit' is persistent tunnel through the Tor network, established -with public-key cryptography, and used to send cells one or more hops. -Clients keep track of multi-hop circuits, and the cryptography -associated with each hop. Relays, on the other hand, keep track only of -their hop of each circuit. - -A 'Channel' is an abstract view of sending cells to and from a Tor -relay. Currently, all channels are implemented using OR connections. -If we switch to other strategies in the future, we'll have more -connection types. - -A 'Node' is a view of a Tor instance's current knowledge and opinions -about a Tor relay or bridge. ### The rest of this document. ### diff --git a/src/mainpage.dox b/src/mainpage.dox index 84eea3c52..7c64e0dff 100644 --- a/src/mainpage.dox +++ b/src/mainpage.dox @@ -3,9 +3,120 @@ @section intro Getting to know Tor -Welcome to the Tor source code documentation! Here we have documentation for -nearly every function, type, and module in the Tor source code. The high-level -documentation is a work in progress. For now, have a look at the source code -overview in doc/HACKING/design. +Welcome! + +This documentation describes the general structure of the Tor codebase, how +it fits together, what functionality is available for extending Tor, and +gives some notes on how Tor got that way. It also includes a reference for +nearly every function, type, file, and module in the Tor source code. The +high-level documentation is a work in progress. + +Tor itself remains a work in progress too: We've been working on it for +nearly two decades, and we've learned a lot about good coding since we first +started. This means, however, that some of the older pieces of Tor will have +some "code smell" in them that could stand a brisk refactoring. So when we +describe a piece of code, we'll sometimes give a note on how it got that way, +and whether we still think that's a good idea. + +This document is not an overview of the Tor protocol. For that, see the +design paper and the specifications at https://spec.torproject.org/ . + +For more information about Tor's coding standards and some helpful +development tools, see doc/HACKING in the Tor repository. + +@section highlevel The very high level + +Ultimately, Tor runs as an event-driven network daemon: it responds to +network events, signals, and timers by sending and receiving things over +the network. Clients, relays, and directory authorities all use the +same codebase: the Tor process will run as a client, relay, or authority +depending on its configuration. + +Tor has a few major dependencies, including Libevent (used to tell which +sockets are readable and writable), OpenSSL or NSS (used for many encryption +functions, and to implement the TLS protocol), and zlib (used to +compress and uncompress directory information). + +Most of Tor's work today is done in a single event-driven main thread. +Tor also spawns one or more worker threads to handle CPU-intensive +tasks. (Right now, this only includes circuit encryption and the more +expensive compression algorithms.) + +On startup, Tor initializes its libraries, reads and responds to its +configuration files, and launches a main event loop. At first, the only +events that Tor listens for are a few signals (like TERM and HUP), and +one or more listener sockets (for different kinds of incoming +connections). Tor also configures several timers to handle periodic +events. As Tor runs over time, other events will open, and new events +will be scheduled. + +The codebase is divided into a few top-level subdirectories, each of +which contains several sub-modules. + + - `ext` -- Code maintained elsewhere that we include in the Tor + source distribution. + + - \refdir{lib} -- Lower-level utility code, not necessarily + tor-specific. + + - `trunnel` -- Automatically generated code (from the Trunnel + tool): used to parse and encode binary formats. + + - \refdir{core} -- Networking code that is implements the central + parts of the Tor protocol and main loop. + + - \refdir{feature} -- Aspects of Tor (like directory management, + running a relay, running a directory authorities, managing a list of + nodes, running and using onion services) that are built on top of the + mainloop code. + + - \refdir{app} -- Highest-level functionality; responsible for setting + up and configuring the Tor daemon, making sure all the lower-level + modules start up when required, and so on. + + - \refdir{tools} -- Binaries other than Tor that we produce. + Currently this is tor-resolve, tor-gencert, and the tor_runner.o helper + module. + + - `test` -- unit tests, regression tests, and a few integration + tests. + +In theory, the above parts of the codebase are sorted from highest-level to +lowest-level, where high-level code is only allowed to invoke lower-level +code, and lower-level code never includes or depends on code of a higher +level. In practice, this refactoring is incomplete: The modules in +\refdir{lib} are well-factored, but there are many layer violations ("upward +dependencies") in \refdir{core} and \refdir{feature}. +We aim to eliminate those over time. + +@section keyabstractions Some key high-level abstractions + +The most important abstractions at Tor's high-level are Connections, +Channels, Circuits, and Nodes. + +A 'Connection' (connection_t) represents a stream-based information flow. +Most connections are TCP connections to remote Tor servers and clients. (But +as a shortcut, a relay will sometimes make a connection to itself without +actually using a TCP connection. More details later on.) Connections exist +in different varieties, depending on what functionality they provide. The +principle types of connection are edge_connection_t (eg a socks connection or +a connection from an exit relay to a destination), or_connection_t (a TLS +stream connecting to a relay), dir_connection_t (an HTTP connection to learn +about the network), and control_connection_t (a connection from a +controller). + +A 'Circuit' (circuit_t) is persistent tunnel through the Tor network, +established with public-key cryptography, and used to send cells one or more +hops. Clients keep track of multi-hop circuits (origin_circuit_t), and the +cryptography associated with each hop. Relays, on the other hand, keep track +only of their hop of each circuit (or_circuit_t). + +A 'Channel' (channel_t) is an abstract view of sending cells to and from a +Tor relay. Currently, all channels are implemented using OR connections +(channel_tls_t). If we switch to other strategies in the future, we'll have +more connection types. + +A 'Node' (node_t) is a view of a Tor instance's current knowledge and opinions +about a Tor relay or bridge. **/

1 0