Fix most DOCDOCs remaining and/or added by redox.

svn:r17734
This commit is contained in:
Nick Mathewson 2008-12-22 17:53:04 +00:00
parent 167d266dbf
commit 1e5f457461
23 changed files with 258 additions and 150 deletions

View File

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

View File

@ -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)
{

View File

@ -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)
{

View File

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

View File

@ -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 */

View File

@ -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)
{

View File

@ -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)
{

View File

@ -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)
{

View File

@ -549,7 +549,8 @@ buf_add_chunk_with_capacity(buf_t *buf, size_t capacity, int capped)
return chunk;
}
/** DOCDOC */
/** If we're using readv and writev, how many chunks are we willing to
* read/write at a time? */
#define N_IOV 3
/** Read up to <b>at_most</b> bytes from the socket <b>fd</b> into

View File

@ -153,7 +153,8 @@ conn_state_to_string(int type, int state)
return buf;
}
/* DOCDOC dir_connection_new */
/** Allocate and return a new dir_connection_t, initialized as by
* connection_init(). */
dir_connection_t *
dir_connection_new(int socket_family)
{
@ -161,7 +162,9 @@ dir_connection_new(int socket_family)
connection_init(time(NULL), TO_CONN(dir_conn), CONN_TYPE_DIR, socket_family);
return dir_conn;
}
/* DOCDOC or_connection_new */
/** Allocate and return a new or_connection_t, initialized as by
* connection_init(). */
or_connection_t *
or_connection_new(int socket_family)
{
@ -174,7 +177,9 @@ or_connection_new(int socket_family)
return or_conn;
}
/* DOCDOC edge_connection_new */
/** Allocate and return a new edge_connection_t, initialized as by
* connection_init(). */
edge_connection_t *
edge_connection_new(int type, int socket_family)
{
@ -185,7 +190,9 @@ edge_connection_new(int type, int socket_family)
edge_conn->socks_request = tor_malloc_zero(sizeof(socks_request_t));
return edge_conn;
}
/* DOCDOC control_connection_new */
/** Allocate and return a new control_connection_t, initialized as by
* connection_init(). */
control_connection_t *
control_connection_new(int socket_family)
{
@ -196,7 +203,9 @@ control_connection_new(int socket_family)
return control_conn;
}
/* DOCDOC connection_new */
/** Allocate, initialize, and return a new connection_t subtype of <b>type</b>
* to make or receive connections of address family <b>socket_family</b>. The
* type should be one of the CONN_TYPE_* constants. */
connection_t *
connection_new(int type, int socket_family)
{
@ -811,7 +820,9 @@ create_unix_sockaddr(const char *listenaddress, char **readable_address)
};
#endif /* HAVE_SYS_UN_H */
/* DOCDOC warn_too_many_conns */
/** Warn that an accept or a connect has failed because we're running up
* against our ulimit. Rate-limit these warnings so that we don't spam
* the log. */
static void
warn_too_many_conns(void)
{

View File

@ -83,13 +83,25 @@ static char authentication_cookie[AUTHENTICATION_COOKIE_LEN];
* of this so we can respond to getinfo status/bootstrap-phase queries. */
static char last_sent_bootstrap_message[BOOTSTRAP_MSG_LEN];
/** Flag for event_format_t. Indicates that we should use the old
* name format of nickname|hexdigest
*/
#define SHORT_NAMES 1
/** Flag for event_format_t. Indicates that we should use the new
* name format of $hexdigest[=~]nickname
*/
#define LONG_NAMES 2
#define ALL_NAMES (SHORT_NAMES|LONG_NAMES)
/** Flag for event_format_t. Indicates that we should use the new event
* format where extra event fields are allowed using a NAME=VAL format. */
#define EXTENDED_FORMAT 4
/** Flag for event_format_t. Indicates that we are using the old event format
* where extra fields aren't allowed. */
#define NONEXTENDED_FORMAT 8
#define ALL_FORMATS (EXTENDED_FORMAT|NONEXTENDED_FORMAT)
/* DOCDOC event_format_t */
/** Bit field of flags to select how to format a controller event. Recognized
* flags are SHORT_NAMES, LONG_NAMES, EXTENDED_FORMAT, NONEXTENDED_FORMAT. */
typedef int event_format_t;
static void connection_printf_to_buf(control_connection_t *conn,

View File

@ -862,18 +862,17 @@ _compare_strs(const void **a, const void **b)
return strcmp(s1, s2);
}
#define CONDITIONAL_CONSENSUS_FPR_LEN 3
#if (CONDITIONAL_CONSENSUS_FPR_LEN > DIGEST_LEN)
#error "conditional consensus fingerprint length is larger than digest length"
#endif
/** Return the URL we should use for a consensus download.
*
* This url depends on whether or not the server we go to
* is sufficiently new to support conditional consensus downloading,
* i.e. GET .../consensus/<b>fpr</b>+<b>fpr</b>+<b>fpr</b>
*/
#define CONDITIONAL_CONSENSUS_FPR_LEN 3
#if (CONDITIONAL_CONSENSUS_FPR_LEN > DIGEST_LEN)
#error "conditional consensus fingerprint length is larger than digest length"
#endif
/* DOCDOC directory_get_consensus_url */
static char *
directory_get_consensus_url(int supports_conditional_consensus)
{
@ -2195,7 +2194,10 @@ typedef struct request_t {
* of request. Maps from request type to pointer to request_t. */
static strmap_t *request_map = NULL;
/* DOCDOC note_client_request */
/** Record that a client request of <b>purpose</b> was made, and that
* <b>bytes</b> bytes of possibly <b>compressed</b> data were sent/received.
* Used to keep track of how much we've up/downloaded in what kind of
* request. */
static void
note_client_request(int purpose, int compressed, size_t bytes)
{

View File

@ -1587,7 +1587,8 @@ dirserv_get_runningrouters(void)
"v1 network status list", V1_AUTHORITY);
}
/* DOCDOC */
/** Return the latest downloaded consensus networkstatus in encoded, signed,
* optionally compressed format, suitable for sending to clients. */
cached_dir_t *
dirserv_get_consensus(void)
{

View File

@ -219,7 +219,9 @@ get_voter(const networkstatus_t *vote)
return smartlist_get(vote->voters, 0);
}
/* DOCDOC dir_src_ent_t */
/** Temporary structure used in constructing a list of dir-source entries
* for a consensus. One of these is generated for every vote, and one more
* for every legacy key in each vote. */
typedef struct dir_src_ent_t {
networkstatus_t *v;
const char *digest;
@ -236,7 +238,9 @@ _compare_votes_by_authority_id(const void **_a, const void **_b)
get_voter(b)->identity_digest, DIGEST_LEN);
}
/* DOCDOC _compare_dir_src_ents_by_authority_id */
/** Helper: Compare the dir_src_ent_ts in *<b>_a</b> and *<b>_b</b> by
* their identity digests, and return -1, 0, or 1 depending on their
* ordering */
static int
_compare_dir_src_ents_by_authority_id(const void **_a, const void **_b)
{

View File

@ -186,9 +186,10 @@ evdns_log_cb(int warn, const char *msg)
log(severity, LD_EXIT, "eventdns: %s", msg);
}
/* DOCDOC randfn */
/** Helper: passed to eventdns.c as a callback so it can generate random
* numbers for transaction IDs and 0x20-hack coding. */
static void
randfn(char *b, size_t n)
_dns_randfn(char *b, size_t n)
{
crypto_rand(b,n);
}
@ -198,7 +199,7 @@ int
dns_init(void)
{
init_cache_map();
evdns_set_random_bytes_fn(randfn);
evdns_set_random_bytes_fn(_dns_randfn);
if (get_options()->ServerDNSRandomizeCase)
evdns_set_option("randomize-case", "1", DNS_OPTIONS_ALL);
else

View File

@ -438,7 +438,8 @@ _c_hist_compare(const void **_a, const void **_b)
* are willing to talk about it? */
#define GEOIP_MIN_OBSERVATION_TIME (12*60*60)
/* DOCDOC round_to_next_multiple_of */
/** Return the lowest x such that x is at least <b>number</b>, and x modulo
* <b>divisor</b> == 0. */
static INLINE unsigned
round_to_next_multiple_of(unsigned number, unsigned divisor)
{
@ -589,7 +590,7 @@ geoip_get_request_history(time_t now, geoip_client_action_t action)
return result;
}
/* DOCDOC dump_geoip_stats */
/** Store all our geoip statistics into $DATADIR/geoip-stats. */
void
dump_geoip_stats(void)
{

View File

@ -1902,14 +1902,14 @@ try_locking(or_options_t *options, int err_if_locked)
}
}
/* DOCDOC have_lockfile */
/** Return true iff we've successfully acquired the lock file. */
int
have_lockfile(void)
{
return lockfile != NULL;
}
/* DOCDOC release_lockfile */
/** If we have successfully acquired the lock file, release it. */
void
release_lockfile(void)
{

View File

@ -235,7 +235,10 @@ addr_policy_permits_tor_addr(const tor_addr_t *addr, uint16_t port,
}
}
/* DOCDOC XXXX deprecate when possible. */
/** Return true iff <b> policy</b> (possibly NULL) will allow a connection to
* <b>addr</b>:<b>port</b>. <b>addr</b> is an IPv4 address given in host
* order. */
/* XXXX deprecate when possible. */
static int
addr_policy_permits_address(uint32_t addr, uint16_t port,
smartlist_t *policy)
@ -254,7 +257,8 @@ fascist_firewall_allows_address_or(const tor_addr_t *addr, uint16_t port)
reachable_or_addr_policy);
}
/** DOCDOC */
/** Return true iff we think our firewall will let us make an OR connection to
* <b>ri</b>. */
int
fascist_firewall_allows_or(routerinfo_t *ri)
{
@ -552,7 +556,8 @@ addr_policy_get_canonical_entry(addr_policy_t *e)
return found->policy;
}
/** DOCDOC */
/** As compare_to_addr_to_addr_policy, but instead of a tor_addr_t, takes
* in host order. */
addr_policy_result_t
compare_addr_to_addr_policy(uint32_t addr, uint16_t port, smartlist_t *policy)
{

View File

@ -1470,7 +1470,9 @@ packed_cell_alloc(void)
++total_cells_allocated;
return mp_pool_get(cell_pool);
}
/* DOCDOC dump_cell_pool_usage */
/** Log current statistics for cell pool allocation at log level
* <b>severity</b>. */
void
dump_cell_pool_usage(int severity)
{

View File

@ -149,14 +149,17 @@ get_my_v3_authority_signing_key(void)
return authority_signing_key;
}
/* DOCDOC get_my_v3_legacy_cert */
/** If we're an authority, and we're using a legacy authority identity key for
* emergency migration purposes, return the certificate associated with that
* key. */
authority_cert_t *
get_my_v3_legacy_cert(void)
{
return legacy_key_certificate;
}
/* DOCDOC get_my_v3_legacy_signing_key */
/** If we're an authority, and we're using a legacy authority identity key for
* emergency migration purposes, return that key. */
crypto_pk_env_t *
get_my_v3_legacy_signing_key(void)
{
@ -285,10 +288,14 @@ init_key_from_file(const char *fname, int generate, int severity)
return NULL;
}
/* DOCDOC load_authority_keyset */
/** Try to load the vote-signing private key and certificate for being a v3
* directory authority, and make sure they match. If <b>legacy</b>, load a
* legacy key/cert set for emergency key migration; otherwise load the regular
* key/cert set. On success, store them into *<b>key_out</b> and
* *<b>cert_out</b> respectively, and return 0. On failrue, return -1. */
static int
load_authority_keyset(int legacy, crypto_pk_env_t **key_out,
authority_cert_t **cert_out)
authority_cert_t **cert_out)
{
int r = -1;
char *fname = NULL, *cert = NULL;

View File

@ -549,7 +549,8 @@ router_should_rebuild_store(desc_store_t *store)
return store->journal_len > (1<<15);
}
/* DOCDOC desc_get_store */
/** Return the desc_store_t in <b>rl</b> that should be used to store
* <b>sd</b>. */
static INLINE desc_store_t *
desc_get_store(routerlist_t *rl, signed_descriptor_t *sd)
{
@ -2466,7 +2467,10 @@ dump_routerlist_mem_usage(int severity)
#endif
}
/* DOCDOC _routerlist_find_elt */
/** Debugging helper: If <b>idx</b> is nonnegative, assert that <b>ri</b> is
* in <b>sl</b> at position <b>idx</b>. Otherwise, search <b>sl</b> for
* <b>ri</b>. Return the index of <b>ri</b> in <b>sl</b>, or -1 if <b>ri</b>
* is not in <b>sl</b>. */
static INLINE int
_routerlist_find_elt(smartlist_t *sl, void *ri, int idx)
{

View File

@ -2847,7 +2847,11 @@ token_free(directory_token_t *tok)
goto done_tokenizing; \
STMT_END
/* DOCDOC token_check_object */
/** Helper: make sure that the token <b>tok</b> with keyword <b>kwd</b> obeys
* the object syntax of <b>o_syn</b>. Allocate all storage in <b>area</b>.
* Return <b>tok</b> on success, or a new _ERR token if the token didn't
* conform to the syntax we wanted.
**/
static INLINE directory_token_t *
token_check_object(memarea_t *area, const char *kwd,
directory_token_t *tok, obj_syntax o_syn)
@ -2855,6 +2859,7 @@ token_check_object(memarea_t *area, const char *kwd,
char ebuf[128];
switch (o_syn) {
case NO_OBJ:
/* No object is allowed for this token. */
if (tok->object_body) {
tor_snprintf(ebuf, sizeof(ebuf), "Unexpected object for %s", kwd);
RET_ERR(ebuf);
@ -2865,20 +2870,21 @@ token_check_object(memarea_t *area, const char *kwd,
}
break;
case NEED_OBJ:
/* There must be a (non-key) object. */
if (!tok->object_body) {
tor_snprintf(ebuf, sizeof(ebuf), "Missing object for %s", kwd);
RET_ERR(ebuf);
}
break;
case NEED_KEY_1024:
case NEED_SKEY_1024:
case NEED_KEY_1024: /* There must be a 1024-bit public key. */
case NEED_SKEY_1024: /* There must be a 1024-bit private key. */
if (tok->key && crypto_pk_keysize(tok->key) != PK_BYTES) {
tor_snprintf(ebuf, sizeof(ebuf), "Wrong size on key for %s: %d bits",
kwd, (int)crypto_pk_keysize(tok->key));
RET_ERR(ebuf);
}
/* fall through */
case NEED_KEY:
case NEED_KEY: /* There must be some kind of key. */
if (!tok->key) {
tor_snprintf(ebuf, sizeof(ebuf), "Missing public key for %s", kwd);
}
@ -2897,6 +2903,7 @@ token_check_object(memarea_t *area, const char *kwd,
}
break;
case OBJ_OK:
/* Anything goes with this token. */
break;
}

View File

@ -54,7 +54,9 @@ int have_failed = 0;
static char temp_dir[256];
/* DOCDOC setup_directory */
/** Select and create the temporary directory we'll use to run our unit tests.
* Store it in <b>temp_dir</b>. Exit immediately if we can't create it.
* idempotent. */
static void
setup_directory(void)
{
@ -79,7 +81,7 @@ setup_directory(void)
is_setup = 1;
}
/* DOCDOC get_fname */
/** Return a filename relative to our testing temporary directory */
static const char *
get_fname(const char *name)
{
@ -89,7 +91,8 @@ get_fname(const char *name)
return buf;
}
/* DOCDOC remove_directory */
/** Remove all files stored under the temporary directory, and the directory
* itself. */
static void
remove_directory(void)
{
@ -113,12 +116,17 @@ remove_directory(void)
#undef CACHE_GENERATED_KEYS
static crypto_pk_env_t *pregen_keys[5] = {NULL, NULL, NULL, NULL, NULL};
/* DOCDOC pk_generate */
#define N_PREGEN_KEYS ((int)(sizeof(pregen_keys)/sizeof(pregen_keys[0])))
/** Generate and return a new keypair for use in unit tests. If we're using
* the key cache optimization, we might reuse keys: we only guarantee that
* keys made with distinct values for <b>idx</b> are different. The value of
* <b>idx</b> must be at least 0, and less than N_PREGEN_KEYS. */
static crypto_pk_env_t *
pk_generate(int idx)
{
#ifdef CACHE_GENERATED_KEYS
tor_assert(idx < (int)(sizeof(pregen_keys)/sizeof(pregen_keys[0])));
tor_assert(idx < N_PREGEN_KEYS);
if (! pregen_keys[idx]) {
pregen_keys[idx] = crypto_new_pk_env();
tor_assert(!crypto_pk_generate_key(pregen_keys[idx]));
@ -133,12 +141,12 @@ pk_generate(int idx)
#endif
}
/* DOCDOC free_pregenerated_keys */
/** Free all storage used for the cached key optimization. */
static void
free_pregenerated_keys(void)
{
unsigned idx;
for (idx = 0; idx < sizeof(pregen_keys)/sizeof(pregen_keys[0]); ++idx) {
for (idx = 0; idx < N_PREGEN_KEYS; ++idx) {
if (pregen_keys[idx]) {
crypto_free_pk_env(pregen_keys[idx]);
pregen_keys[idx] = NULL;
@ -146,7 +154,7 @@ free_pregenerated_keys(void)
}
}
/* DOCDOC test_buffers */
/** Run unit tests for buffers.c */
static void
test_buffers(void)
{
@ -389,7 +397,7 @@ test_buffers(void)
buf_free(buf2);
}
/* DOCDOC test_crypto_dh */
/** Run unit tests for Diffie-Hellman functionality. */
static void
test_crypto_dh(void)
{
@ -431,7 +439,8 @@ test_crypto_dh(void)
crypto_dh_free(dh2);
}
/* DOCDOC test_crypto_rng */
/** Run unit tests for our random number generation function and its wrappers.
*/
static void
test_crypto_rng(void)
{
@ -469,7 +478,7 @@ test_crypto_rng(void)
;
}
/* DOCDOC test_crypto_aes */
/** Run unit tests for our AES functionality */
static void
test_crypto_aes(void)
{
@ -599,7 +608,7 @@ test_crypto_aes(void)
tor_free(data3);
}
/* DOCDOC test_crypto_sha */
/** Run unit tests for our SHA-1 functionality */
static void
test_crypto_sha(void)
{
@ -668,7 +677,7 @@ test_crypto_sha(void)
crypto_free_digest_env(d2);
}
/* DOCDOC test_crypto_pk */
/** Run unit tests for our public key crypto functions */
static void
test_crypto_pk(void)
{
@ -778,7 +787,7 @@ test_crypto_pk(void)
tor_free(encoded);
}
/* DOCDOC test_crypto */
/** Run unit tests for misc crypto functionality. */
static void
test_crypto(void)
{
@ -887,7 +896,7 @@ test_crypto(void)
tor_free(data3);
}
/* DOCDOC test_crypto_s2k */
/** Run unit tests for our secret-to-key passphrase hashing functionality. */
static void
test_crypto_s2k(void)
{
@ -920,7 +929,8 @@ test_crypto_s2k(void)
tor_free(buf3);
}
/* DOCDOC _compare_strs */
/** Helper: return a tristate based on comparing the strings in *<b>a</b> and
* *<b>b</b>. */
static int
_compare_strs(const void **a, const void **b)
{
@ -928,7 +938,8 @@ _compare_strs(const void **a, const void **b)
return strcmp(s1, s2);
}
/* DOCDOC _compare_without_first_ch */
/** Helper: return a tristate based on comparing the strings in *<b>a</b> and
* *<b>b</b>, excluding a's first character, and ignoring case. */
static int
_compare_without_first_ch(const void *a, const void **b)
{
@ -936,7 +947,7 @@ _compare_without_first_ch(const void *a, const void **b)
return strcasecmp(s1+1, s2);
}
/* DOCDOC test_util */
/** Test basic utility functionality. */
static void
test_util(void)
{
@ -1429,7 +1440,7 @@ _test_eq_ip6(struct in6_addr *a, struct in6_addr *b, const char *e1,
test_eq(port2, pt2); \
STMT_END
/* DOCDOC test_util_ip6_helpers */
/** Run unit tests for IPv6 encoding/decoding/manipulation functions. */
static void
test_util_ip6_helpers(void)
{
@ -1755,7 +1766,7 @@ test_util_ip6_helpers(void)
;
}
/* DOCDOC test_util_smartlist_basic */
/** Run unit tests for basic dynamic-sized array functionality. */
static void
test_util_smartlist_basic(void)
{
@ -1794,7 +1805,7 @@ test_util_smartlist_basic(void)
smartlist_free(sl);
}
/* DOCDOC test_util_smartlist_strings */
/** Run unit tests for smartlist-of-strings functionality. */
static void
test_util_smartlist_strings(void)
{
@ -2024,7 +2035,7 @@ test_util_smartlist_strings(void)
tor_free(cp_alloc);
}
/* DOCDOC test_util_smartlist_overlap */
/** Run unit tests for smartlist set manipulation functions. */
static void
test_util_smartlist_overlap(void)
{
@ -2077,7 +2088,7 @@ test_util_smartlist_overlap(void)
smartlist_free(sl);
}
/* DOCDOC test_util_smartlist_digests */
/** Run unit tests for smartlist-of-digests functions. */
static void
test_util_smartlist_digests(void)
{
@ -2110,7 +2121,7 @@ test_util_smartlist_digests(void)
smartlist_free(sl);
}
/* DOCDOC test_util_smartlist_join */
/** Run unit tests for concatenate-a-smartlist-of-strings functions. */
static void
test_util_smartlist_join(void)
{
@ -2162,7 +2173,7 @@ test_util_smartlist_join(void)
tor_free(joined);
}
/* DOCDOC test_util_bitarray */
/** Run unit tests for bitarray code */
static void
test_util_bitarray(void)
{
@ -2204,7 +2215,8 @@ test_util_bitarray(void)
bitarray_free(ba);
}
/* DOCDOC test_util_digestset */
/** Run unit tests for digest set code (implemented as a hashtable or as a
* bloom filter) */
static void
test_util_digestset(void)
{
@ -2253,18 +2265,18 @@ static strmap_t *_thread_test_strmap = NULL;
static char *_thread1_name = NULL;
static char *_thread2_name = NULL;
/* DOCDOC _thread_test_func */
static void _thread_test_func(void* _s) ATTR_NORETURN;
static int t1_count = 0;
static int t2_count = 0;
/** Helper function for threading unit tests: This function runs in a
* subthread. It grabs its own mutex (start1 or start2) to make sure that it
* should start, then it repeatedly alters _test_thread_strmap protected by
* _thread_test_mutex. */
static void
_thread_test_func(void* _s)
{
/* This function runs in a subthread. It grabs its own mutex (start1 or
* start2) to make sure that it should start, then it repeatedly alters
* _test_thread_strmap protected by _thread_test_mutex. */
char *s = _s;
int i, *count;
tor_mutex_t *m;
@ -2299,7 +2311,7 @@ _thread_test_func(void* _s)
spawn_exit();
}
/* DOCDOC test_util_threads */
/** Run unit tests for threading logic. */
static void
test_util_threads(void)
{
@ -2371,14 +2383,14 @@ test_util_threads(void)
tor_mutex_free(_thread_test_start2);
}
/* DOCDOC _compare_strings_for_pqueue */
/** Helper: return a tristate based on comparing two strings. */
static int
_compare_strings_for_pqueue(const void *s1, const void *s2)
{
return strcmp((const char*)s1, (const char*)s2);
}
/* DOCDOC test_util_pqueue */
/** Run unit tests for heap-based priority queue functions. */
static void
test_util_pqueue(void)
{
@ -2436,7 +2448,7 @@ test_util_pqueue(void)
smartlist_free(sl);
}
/* DOCDOC test_util_gzip */
/** Run unit tests for compression functions */
static void
test_util_gzip(void)
{
@ -2543,7 +2555,7 @@ test_util_gzip(void)
tor_free(buf1);
}
/* DOCDOC test_util_strmap */
/** Run unit tests for string-to-void* map functions */
static void
test_util_strmap(void)
{
@ -2634,7 +2646,7 @@ test_util_strmap(void)
tor_free(visited);
}
/* DOCDOC test_util_mmap */
/** Run unit tests for mmap() wrapper functionality. */
static void
test_util_mmap(void)
{
@ -2711,7 +2723,7 @@ test_util_mmap(void)
tor_munmap_file(mapping);
}
/* DOCDOC test_util_control_formats */
/** Run unit tests for escaping/unescaping data for use by controllers. */
static void
test_util_control_formats(void)
{
@ -2729,7 +2741,7 @@ test_util_control_formats(void)
tor_free(out);
}
/* DOCDOC test_onion_handshake */
/** Run unit tests for the onion handshake code. */
static void
test_onion_handshake(void)
{
@ -2778,7 +2790,7 @@ test_onion_handshake(void)
extern smartlist_t *fingerprint_list;
/* DOCDOC test_dir_format */
/** Run unit tests for router descriptor generation logic. */
static void
test_dir_format(void)
{
@ -3099,7 +3111,7 @@ test_dir_format(void)
tor_free(dir2); /* And more !*/
}
/* DOCDOC test_dirutil */
/** Run unit tests for misc directory functions. */
static void
test_dirutil(void)
{
@ -3135,7 +3147,9 @@ extern const char AUTHORITY_SIGNKEY_2[];
extern const char AUTHORITY_CERT_3[];
extern const char AUTHORITY_SIGNKEY_3[];
/* DOCDOC test_same_voter */
/** Helper: Test that two networkstatus_voter_info_t do in fact represent the
* same voting authority, and that they do in fact have all the same
* information. */
static void
test_same_voter(networkstatus_voter_info_t *v1,
networkstatus_voter_info_t *v2)
@ -3152,7 +3166,7 @@ test_same_voter(networkstatus_voter_info_t *v1,
;
}
/* DOCDOC test_util_order_functions */
/** Run unit tests for getting the median of a list. */
static void
test_util_order_functions(void)
{
@ -3182,7 +3196,8 @@ test_util_order_functions(void)
;
}
/* DOCDOC generate_ri_from_rs */
/** Helper: Make a new routerinfo containing the right information for a
* given vote_routerstatus_t. */
static routerinfo_t *
generate_ri_from_rs(const vote_routerstatus_t *vrs)
{
@ -3205,7 +3220,8 @@ generate_ri_from_rs(const vote_routerstatus_t *vrs)
return r;
}
/* DOCDOC test_v3_networkstatus */
/** Run unit tests for generating and parsing V3 consensus networkstatus
* documents. */
static void
test_v3_networkstatus(void)
{
@ -3704,7 +3720,9 @@ test_v3_networkstatus(void)
ns_detached_signatures_free(dsig2);
}
/* DOCDOC test_policy_summary_helper */
/** Helper: Parse the exit policy string in <b>policy_str</b>, and make sure
* that policies_summarize() produces the string <b>expected_summary</b> from
* it. */
static void
test_policy_summary_helper(const char *policy_str,
const char *expected_summary)
@ -3731,7 +3749,7 @@ test_policy_summary_helper(const char *policy_str,
addr_policy_list_free(policy);
}
/* DOCDOC test_policies */
/** Run unit tests for generating summary lines of exit policies */
static void
test_policies(void)
{
@ -3890,7 +3908,7 @@ test_policies(void)
}
}
/* DOCDOC test_rend_fns */
/** Run unit tests for basic rendezvous functions. */
static void
test_rend_fns(void)
{
@ -3956,7 +3974,7 @@ test_rend_fns(void)
tor_free(encoded);
}
/* DOCDOC bench_aes */
/** Run AES performance benchmarks. */
static void
bench_aes(void)
{
@ -3988,7 +4006,7 @@ bench_aes(void)
crypto_free_cipher_env(c);
}
/* DOCDOC bench_dmap */
/** Run digestmap_t performance benchmarks. */
static void
bench_dmap(void)
{
@ -4052,7 +4070,7 @@ bench_dmap(void)
smartlist_free(sl2);
}
/* DOCDOC test_util_mempool */
/** Run unittests for memory pool allocator */
static void
test_util_mempool(void)
{
@ -4110,7 +4128,7 @@ test_util_mempool(void)
mp_pool_destroy(pool);
}
/* DOCDOC test_util_memarea */
/** Run unittests for memory area allocator */
static void
test_util_memarea(void)
{
@ -4206,7 +4224,8 @@ test_util_memarea(void)
tor_free(malloced_ptr);
}
/* DOCDOC test_util_datadir */
/** Run unit tests for utility functions to get file names relative to
* the data directory. */
static void
test_util_datadir(void)
{
@ -4239,8 +4258,7 @@ test_util_datadir(void)
tor_free(f);
}
/* Test AES-CTR encryption and decryption with IV. */
/* DOCDOC test_crypto_aes_iv */
/** Test AES-CTR encryption and decryption with IV. */
static void
test_crypto_aes_iv(void)
{
@ -4376,8 +4394,7 @@ test_crypto_aes_iv(void)
crypto_free_cipher_env(cipher);
}
/* Test base32 decoding. */
/* DOCDOC test_crypto_base32_decode */
/** Test base32 decoding. */
static void
test_crypto_base32_decode(void)
{
@ -4412,8 +4429,7 @@ test_crypto_base32_decode(void)
;
}
/* Test encoding and parsing of v2 rendezvous service descriptors. */
/* DOCDOC test_rend_fns_v2 */
/** Test encoding and parsing of v2 rendezvous service descriptors. */
static void
test_rend_fns_v2(void)
{
@ -4514,7 +4530,7 @@ test_rend_fns_v2(void)
tor_free(intro_points_encrypted);
}
/* DOCDOC test_geoip */
/** Run unit tests for GeoIP code. */
static void
test_geoip(void)
{
@ -4580,6 +4596,7 @@ static struct {
void (*test_fn)(void);
int is_subent;
int selected;
int is_default;
} test_array[] = {
ENT(buffers),
ENT(crypto),
@ -4618,11 +4635,12 @@ static struct {
ENT(rend_fns),
SUBENT(rend_fns, v2),
ENT(geoip),
{ NULL, NULL, 0, 0 },
{ NULL, NULL, 0, 0, 0 },
};
static void syntax(void) ATTR_NORETURN;
/* DOCDOC syntax */
/** Print a syntax usage message, and exit.*/
static void
syntax(void)
{
@ -4638,7 +4656,8 @@ syntax(void)
exit(0);
}
/* DOCDOC main */
/** Main entry point for unit test code: parse the command line, and run
* some unit tests. */
int
main(int c, char**v)
{