diff options
Diffstat (limited to 'src/common')
| -rw-r--r-- | src/common/address.h | 30 | ||||
| -rw-r--r-- | src/common/compat.c | 11 | ||||
| -rw-r--r-- | src/common/container.c | 53 | ||||
| -rw-r--r-- | src/common/crypto.c | 11 | ||||
| -rw-r--r-- | src/common/crypto.h | 4 | ||||
| -rw-r--r-- | src/common/log.c | 3 | ||||
| -rw-r--r-- | src/common/memarea.c | 3 | ||||
| -rw-r--r-- | src/common/util.c | 14 |
8 files changed, 80 insertions, 49 deletions
diff --git a/src/common/address.h b/src/common/address.h index 4a6e9859ef..603ffae2ae 100644 --- a/src/common/address.h +++ b/src/common/address.h @@ -17,8 +17,10 @@ #include "torint.h" #include "compat.h" -/* DOCDOC maskbits_t */ +/** The number of bits from an address to consider while doing a masked + * comparison. */ typedef uint8_t maskbits_t; + struct in_addr; /** Holds an IPv4 or IPv6 address. (Uses less memory than struct * sockaddr_storage.) */ @@ -31,20 +33,30 @@ typedef struct tor_addr_t } addr; } tor_addr_t; -/* DOCDOC*/ +/** Return an IPv4 address in network order for <b>a</b>, or 0 if + * <b>a</b> is not an IPv4 address. */ static INLINE uint32_t tor_addr_to_ipv4n(const tor_addr_t *a); -/* DOCDOC tor_addr_to_ipv4h */ +/** Return an IPv4 address in host order for <b>a</b>, or 0 if + * <b>a</b> is not an IPv4 address. */ static INLINE uint32_t tor_addr_to_ipv4h(const tor_addr_t *a); -/* DOCDOC tor_addr_to_mapped_ipv4h */ +/* Given an IPv6 address, return its mapped IPv4 address in host order, or + * 0 if <b>a</b> is not an IPv6 address. + * + * (Does not check whether the address is really a mapped address */ static INLINE uint32_t tor_addr_to_mapped_ipv4h(const tor_addr_t *a); -/* DOCDOC tor_addr_family */ +/** Return the address family of <b>a</b>. Possible values are: + * AF_INET6, AF_INET, AF_UNSPEC. */ static INLINE sa_family_t tor_addr_family(const tor_addr_t *a); -/* DOCDOC tor_addr_to_in */ +/** Return an in_addr* equivalent to <b>a</b>, or NULL if <b>a</b> is not + * an IPv4 address. */ static INLINE const struct in_addr *tor_addr_to_in(const tor_addr_t *a); -/* DOCDOC tor_addr_to_in6 */ +/** Return an in6_addr* equivalent to <b>a</b>, or NULL if <b>a</b> is not + * an IPv6 address. */ static INLINE const struct in6_addr *tor_addr_to_in6(const tor_addr_t *a); -/* DOCDOC tor_addr_eq_ipv4h */ +/** Return true iff <b>a</b> is an IPv4 address equal to the host-ordered + * address in <b>u</b>. */ static INLINE int tor_addr_eq_ipv4h(const tor_addr_t *a, uint32_t u); + socklen_t tor_addr_to_sockaddr(const tor_addr_t *a, uint16_t port, struct sockaddr *sa_out, socklen_t len); int tor_addr_from_sockaddr(tor_addr_t *a, const struct sockaddr *sa, @@ -74,7 +86,7 @@ tor_addr_to_ipv4h(const tor_addr_t *a) static INLINE uint32_t tor_addr_to_mapped_ipv4h(const tor_addr_t *a) { - return ntohl(tor_addr_to_in6_addr32(a)[3]); + return a->family == AF_INET6 ? ntohl(tor_addr_to_in6_addr32(a)[3]) : 0; } static INLINE sa_family_t tor_addr_family(const tor_addr_t *a) diff --git a/src/common/compat.c b/src/common/compat.c index d75cab5571..f1e3a1d4c8 100644 --- a/src/common/compat.c +++ b/src/common/compat.c @@ -1831,7 +1831,8 @@ tor_get_thread_id(void) #elif defined(USE_PTHREADS) static pthread_mutexattr_t attr_reentrant; static int threads_initialized = 0; -/* DOCDOC tor_mutex_init */ +/** Initialize <b>mutex</b> so it can be locked. Every mutex must be set + * up eith tor_mutex_init() or tor_mutex_new(); not both. */ void tor_mutex_init(tor_mutex_t *mutex) { @@ -1868,7 +1869,9 @@ tor_mutex_release(tor_mutex_t *m) tor_fragile_assert(); } } -/* DOCDOC tor_mutex_uninit */ +/** Clean up the mutex <b>m</b> so that it no longer uses any system + * resources. Does not free <b>m</b>. This function must only be called on + * mutexes from tor_mutex_init(). */ void tor_mutex_uninit(tor_mutex_t *m) { @@ -1894,7 +1897,7 @@ tor_get_thread_id(void) #endif #ifdef TOR_IS_MULTITHREADED -/* DOCDOC tor_mutex_new */ +/** Return a newly allocated, ready-for-use mutex. */ tor_mutex_t * tor_mutex_new(void) { @@ -1902,7 +1905,7 @@ tor_mutex_new(void) tor_mutex_init(m); return m; } -/* DOCDOC tor_mutex_free */ +/** Release all storage and system resources held by <b>m</b>. */ void tor_mutex_free(tor_mutex_t *m) { diff --git a/src/common/container.c b/src/common/container.c index 2cf45f1467..4fed9184d6 100644 --- a/src/common/container.c +++ b/src/common/container.c @@ -687,7 +687,10 @@ smartlist_uniq_digests(smartlist_t *sl) smartlist_uniq(sl, _compare_digests, _tor_free); } -/* DOCDOC DEFINE_MAP_STRUCTS */ +/** Helper: Declare an entry type and a map type to implement a mapping using + * ht.h. The map type will be called <b>maptype</b>. The key part of each + * entry is declared using the C declaration <b>keydecl</b>. All functions + * and types associated with the map get prefixed with <b>prefix</b> */ #define DEFINE_MAP_STRUCTS(maptype, keydecl, prefix) \ typedef struct prefix ## entry_t { \ HT_ENTRY(prefix ## entry_t) node; \ @@ -698,9 +701,7 @@ smartlist_uniq_digests(smartlist_t *sl) HT_HEAD(prefix ## impl, prefix ## entry_t) head; \ } -/* DOCDOC DEFINE_MAP_STRUCTS */ DEFINE_MAP_STRUCTS(strmap_t, char *key, strmap_); -/* DOCDOC DEFINE_MAP_STRUCTS */ DEFINE_MAP_STRUCTS(digestmap_t, char key[DIGEST_LEN], digestmap_); /** Helper: compare strmap_entry_t objects by key value. */ @@ -1007,7 +1008,7 @@ strmap_iter_init(strmap_t *map) return HT_START(strmap_impl, &map->head); } -/* DOCDOC digestmap_iter_init */ +/** Start iterating through <b>map</b>. See strmap_iter_init() for example. */ digestmap_iter_t * digestmap_iter_init(digestmap_t *map) { @@ -1015,8 +1016,8 @@ digestmap_iter_init(digestmap_t *map) return HT_START(digestmap_impl, &map->head); } -/** Advance the iterator <b>iter</b> for map a single step to the next entry. - */ +/** Advance the iterator <b>iter</b> for <b>map</b> a single step to the next + * entry, and return its new value. */ strmap_iter_t * strmap_iter_next(strmap_t *map, strmap_iter_t *iter) { @@ -1025,7 +1026,8 @@ strmap_iter_next(strmap_t *map, strmap_iter_t *iter) return HT_NEXT(strmap_impl, &map->head, iter); } -/* DOCDOC digestmap_iter_next */ +/** Advance the iterator <b>iter</b> for map a single step to the next entry, + * and return its new value. */ digestmap_iter_t * digestmap_iter_next(digestmap_t *map, digestmap_iter_t *iter) { @@ -1035,7 +1037,7 @@ digestmap_iter_next(digestmap_t *map, digestmap_iter_t *iter) } /** Advance the iterator <b>iter</b> a single step to the next entry, removing - * the current entry. + * the current entry, and return its new value. */ strmap_iter_t * strmap_iter_next_rmv(strmap_t *map, strmap_iter_t *iter) @@ -1051,7 +1053,9 @@ strmap_iter_next_rmv(strmap_t *map, strmap_iter_t *iter) return iter; } -/* DOCDOC digestmap_iter_next_rmv */ +/** Advance the iterator <b>iter</b> a single step to the next entry, removing + * the current entry, and return its new value. + */ digestmap_iter_t * digestmap_iter_next_rmv(digestmap_t *map, digestmap_iter_t *iter) { @@ -1065,8 +1069,8 @@ digestmap_iter_next_rmv(digestmap_t *map, digestmap_iter_t *iter) return iter; } -/** Set *keyp and *valp to the current entry pointed to by iter. - */ +/** Set *<b>keyp</b> and *<b>valp</b> to the current entry pointed to by + * iter. */ void strmap_iter_get(strmap_iter_t *iter, const char **keyp, void **valp) { @@ -1078,7 +1082,8 @@ strmap_iter_get(strmap_iter_t *iter, const char **keyp, void **valp) *valp = (*iter)->val; } -/* DOCDOC digestmap_iter_get */ +/** Set *<b>keyp</b> and *<b>valp</b> to the current entry pointed to by + * iter. */ void digestmap_iter_get(digestmap_iter_t *iter, const char **keyp, void **valp) { @@ -1090,14 +1095,16 @@ digestmap_iter_get(digestmap_iter_t *iter, const char **keyp, void **valp) *valp = (*iter)->val; } -/** Return true iff iter has advanced past the last entry of map. - */ +/** Return true iff <b>iter</b> has advanced past the last entry of + * <b>map</b>. */ int strmap_iter_done(strmap_iter_t *iter) { return iter == NULL; } -/* DOCDOC digestmap_iter_done */ + +/** Return true iff <b>iter</b> has advanced past the last entry of + * <b>map</b>. */ int digestmap_iter_done(digestmap_iter_t *iter) { @@ -1124,7 +1131,11 @@ strmap_free(strmap_t *map, void (*free_val)(void*)) HT_CLEAR(strmap_impl, &map->head); tor_free(map); } -/* DOCDOC digestmap_free */ + +/** Remove all entries from <b>map</b>, and deallocate storage for those + * entries. If free_val is provided, it is invoked on every value in + * <b>map</b>. + */ void digestmap_free(digestmap_t *map, void (*free_val)(void*)) { @@ -1141,13 +1152,15 @@ digestmap_free(digestmap_t *map, void (*free_val)(void*)) tor_free(map); } -/* DOCDOC strmap_assert_ok */ +/** Fail with an assertion error if anything has gone wrong with the internal + * representation of <b>map</b>. */ void strmap_assert_ok(const strmap_t *map) { tor_assert(!_strmap_impl_HT_REP_IS_BAD(&map->head)); } -/* DOCDOC digestmap_assert_ok */ +/** Fail with an assertion error if anything has gone wrong with the internal + * representation of <b>map</b>. */ void digestmap_assert_ok(const digestmap_t *map) { @@ -1161,7 +1174,7 @@ strmap_isempty(const strmap_t *map) return HT_EMPTY(&map->head); } -/* DOCDOC digestmap_isempty */ +/** Return true iff <b>map</b> has no entries. */ int digestmap_isempty(const digestmap_t *map) { @@ -1175,7 +1188,7 @@ strmap_size(const strmap_t *map) return HT_SIZE(&map->head); } -/* DOCDOC digestmap_size */ +/** Return the number of items in <b>map</b>. */ int digestmap_size(const digestmap_t *map) { diff --git a/src/common/crypto.c b/src/common/crypto.c index 228656cf46..ae9edd16f8 100644 --- a/src/common/crypto.c +++ b/src/common/crypto.c @@ -2274,12 +2274,13 @@ _openssl_locking_cb(int mode, int n, const char *file, int line) tor_mutex_release(_openssl_mutexes[n]); } -/* DOCDOC CRYPTO_dynlock_value */ +/** OpenSSL helper type: wraps a Tor mutex so that openssl can */ struct CRYPTO_dynlock_value { tor_mutex_t *lock; }; -/* DOCDOC _openssl_dynlock_create_cb */ +/** Openssl callback function to allocate a lock: see CRYPTO_set_dynlock_* + * documentation in OpenSSL's docs for more info. */ static struct CRYPTO_dynlock_value * _openssl_dynlock_create_cb(const char *file, int line) { @@ -2291,7 +2292,8 @@ _openssl_dynlock_create_cb(const char *file, int line) return v; } -/* DOCDOC _openssl_dynlock_lock_cb */ +/** Openssl callback function to acquire or release a lock: see + * CRYPTO_set_dynlock_* documentation in OpenSSL's docs for more info. */ static void _openssl_dynlock_lock_cb(int mode, struct CRYPTO_dynlock_value *v, const char *file, int line) @@ -2304,7 +2306,8 @@ _openssl_dynlock_lock_cb(int mode, struct CRYPTO_dynlock_value *v, tor_mutex_release(v->lock); } -/* DOCDOC _openssl_dynlock_destroy_cb */ +/** Openssl callback function to free a lock: see CRYPTO_set_dynlock_* + * documentation in OpenSSL's docs for more info. */ static void _openssl_dynlock_destroy_cb(struct CRYPTO_dynlock_value *v, const char *file, int line) diff --git a/src/common/crypto.h b/src/common/crypto.h index 6e6163c8cb..86dfa88076 100644 --- a/src/common/crypto.h +++ b/src/common/crypto.h @@ -51,13 +51,9 @@ /** Length of hex encoding of SHA1 digest, not including final NUL. */ #define HEX_DIGEST_LEN 40 -/* DOCDOC crypto_pk_env_t */ typedef struct crypto_pk_env_t crypto_pk_env_t; -/* DOCDOC crypto_cipher_env_t */ typedef struct crypto_cipher_env_t crypto_cipher_env_t; -/* DOCDOC crypto_digest_env_t */ typedef struct crypto_digest_env_t crypto_digest_env_t; -/* DOCDOC crypto_dh_env_t */ typedef struct crypto_dh_env_t crypto_dh_env_t; /* global state */ diff --git a/src/common/log.c b/src/common/log.c index d4894baef4..7406734e28 100644 --- a/src/common/log.c +++ b/src/common/log.c @@ -766,7 +766,8 @@ parse_log_domain(const char *domain) return 0; } #if 0 -/** DOCDOC */ +/** Translate a bitmask of log domains to a string, or NULL if the bitmask + * is undecodable. */ static const char * domain_to_string(log_domain_mask_t domain) { diff --git a/src/common/memarea.c b/src/common/memarea.c index 5c565cebe7..ff348770c3 100644 --- a/src/common/memarea.c +++ b/src/common/memarea.c @@ -85,7 +85,8 @@ alloc_chunk(size_t sz, int freelist_ok) } } -/* DOCDOC chunk_free */ +/** Release <b>chunk</b> from a memarea, either by adding it to the freelist + * or by freeing it if the freelist is already too big. */ static void chunk_free(memarea_chunk_t *chunk) { diff --git a/src/common/util.c b/src/common/util.c index d40de03ceb..60adbb5bc6 100644 --- a/src/common/util.c +++ b/src/common/util.c @@ -1341,14 +1341,16 @@ update_approx_time(time_t now) */ static int ftime_skew = 0; static int ftime_slop = 60; -/* DOCDOC ftime_set_maximum_sloppiness */ +/** Set the largest amount of sloppiness we'll allow in fuzzy time + * comparisons. */ void ftime_set_maximum_sloppiness(int seconds) { tor_assert(seconds >= 0); ftime_slop = seconds; } -/* DOCDOC ftime_set_estimated_skew */ +/** Set the amount by which we believe our system clock to differ from + * real time. */ void ftime_set_estimated_skew(int seconds) { @@ -1362,21 +1364,21 @@ ftime_get_window(time_t now, ftime_t *ft_out) ft_out->latest = now + ftime_skew + ftime_slop; } #endif -/* DOCDOC ftime_maybe_after */ +/** Return true iff we think that <b>now</b> might be after <b>when</b>. */ int ftime_maybe_after(time_t now, time_t when) { /* It may be after when iff the latest possible current time is after when */ return (now + ftime_skew + ftime_slop) >= when; } -/* DOCDOC ftime_maybe_before */ +/** Return true iff we think that <b>now</b> might be before <b>when</b>. */ int ftime_maybe_before(time_t now, time_t when) { /* It may be before when iff the earliest possible current time is before */ return (now + ftime_skew - ftime_slop) < when; } -/* DOCDOC ftime_definitely_after */ +/** Return true if we think that <b>now</b> is definitely after <b>when</b>. */ int ftime_definitely_after(time_t now, time_t when) { @@ -1384,7 +1386,7 @@ ftime_definitely_after(time_t now, time_t when) * after when. */ return (now + ftime_skew - ftime_slop) >= when; } -/* DOCDOC ftime_definitely_before */ +/** Return true if we think that <b>now</b> is definitely before <b>when</b>. */ int ftime_definitely_before(time_t now, time_t when) { |