Commit 6693f325 authored by Nick Mathewson's avatar Nick Mathewson 🐻
Browse files

Resolve many DOCDOCs.

svn:r17662
parent 2ad36f68
...@@ -630,7 +630,7 @@ tor_addr_from_ipv6_bytes(tor_addr_t *dest, const char *ipv6_bytes) ...@@ -630,7 +630,7 @@ tor_addr_from_ipv6_bytes(tor_addr_t *dest, const char *ipv6_bytes)
memcpy(dest->addr.in6_addr.s6_addr, ipv6_bytes, 16); memcpy(dest->addr.in6_addr.s6_addr, ipv6_bytes, 16);
} }
/** DOCDOC */ /** Set <b>dest</b> equal to the IPv6 address in the in6_addr <b>in6</b>. */
void void
tor_addr_from_in6(tor_addr_t *dest, const struct in6_addr *in6) tor_addr_from_in6(tor_addr_t *dest, const struct in6_addr *in6)
{ {
......
...@@ -53,7 +53,8 @@ typedef struct logfile_t { ...@@ -53,7 +53,8 @@ typedef struct logfile_t {
int is_temporary; /**< Boolean: close after initializing logging subsystem.*/ int is_temporary; /**< Boolean: close after initializing logging subsystem.*/
int is_syslog; /**< Boolean: send messages to syslog. */ int is_syslog; /**< Boolean: send messages to syslog. */
log_callback callback; /**< If not NULL, send messages to this function. */ log_callback callback; /**< If not NULL, send messages to this function. */
log_severity_list_t *severities; /**< DOCDOC */ log_severity_list_t *severities; /**< Which severity of messages should we
* log for each log domain? */
} logfile_t; } logfile_t;
static void log_free(logfile_t *victim); static void log_free(logfile_t *victim);
...@@ -415,7 +416,7 @@ _log_err(log_domain_mask_t domain, const char *format, ...) ...@@ -415,7 +416,7 @@ _log_err(log_domain_mask_t domain, const char *format, ...)
} }
#endif #endif
/** DOCDOC */ /** Free all storage held by <b>victim</b>. */
static void static void
log_free(logfile_t *victim) log_free(logfile_t *victim)
{ {
...@@ -730,14 +731,17 @@ log_level_to_string(int level) ...@@ -730,14 +731,17 @@ log_level_to_string(int level)
return sev_to_string(level); return sev_to_string(level);
} }
/** DOCDOC */ /** NULL-terminated array of names for log domains such that domain_list[dom]
* is a description of <b>dom</b>. */
static const char *domain_list[] = { static const char *domain_list[] = {
"GENERAL", "CRYPTO", "NET", "CONFIG", "FS", "PROTOCOL", "MM", "GENERAL", "CRYPTO", "NET", "CONFIG", "FS", "PROTOCOL", "MM",
"HTTP", "APP", "CONTROL", "CIRC", "REND", "BUG", "DIR", "DIRSERV", "HTTP", "APP", "CONTROL", "CIRC", "REND", "BUG", "DIR", "DIRSERV",
"OR", "EDGE", "ACCT", "HIST", NULL "OR", "EDGE", "ACCT", "HIST", NULL
}; };
/** DOCDOC */ /** Return the log domain for which <b>domain</b> is the name, or 0 if there
* is no such name. */
/*XXXX021 0 could mean "no such domain" or LD_GENERAL. Fix that. */
static log_domain_mask_t static log_domain_mask_t
parse_log_domain(const char *domain) parse_log_domain(const char *domain)
{ {
......
...@@ -138,7 +138,7 @@ memarea_clear(memarea_t *area) ...@@ -138,7 +138,7 @@ memarea_clear(memarea_t *area)
area->first->next_mem = area->first->u.mem; area->first->next_mem = area->first->u.mem;
} }
/** DOCDOC */ /** Remove all unused memarea chunks from the internal freelist. */
void void
memarea_clear_freelist(void) memarea_clear_freelist(void)
{ {
......
...@@ -1442,7 +1442,11 @@ tor_tls_used_v1_handshake(tor_tls_t *tls) ...@@ -1442,7 +1442,11 @@ tor_tls_used_v1_handshake(tor_tls_t *tls)
return 1; return 1;
} }
/** DOCDOC */ /** Examine the amount of memory used and available for buffers in <b>tls</b>.
* Set *<b>rbuf_capacity</b> to the amount of storage allocated for the read
* buffer and *<b>rbuf_bytes</b> to the amount actually used.
* Set *<b>wbuf_capacity</b> to the amount of storage allocated for the write
* buffer and *<b>wbuf_bytes</b> to the amount actually used. */
void void
tor_tls_get_buffer_sizes(tor_tls_t *tls, tor_tls_get_buffer_sizes(tor_tls_t *tls,
int *rbuf_capacity, int *rbuf_bytes, int *rbuf_capacity, int *rbuf_bytes,
......
...@@ -33,7 +33,8 @@ typedef struct tor_tls_t tor_tls_t; ...@@ -33,7 +33,8 @@ typedef struct tor_tls_t tor_tls_t;
#define TOR_TLS_WANTWRITE -1 #define TOR_TLS_WANTWRITE -1
#define TOR_TLS_DONE 0 #define TOR_TLS_DONE 0
/** DOCDOC XXXX021 also rename me. */ /** Collection of case statements for all TLS errors that are not due to
* underlying IO failure. */
#define CASE_TOR_TLS_ERROR_ANY_NONIO \ #define CASE_TOR_TLS_ERROR_ANY_NONIO \
case TOR_TLS_ERROR_MISC: \ case TOR_TLS_ERROR_MISC: \
case TOR_TLS_ERROR_CONNREFUSED: \ case TOR_TLS_ERROR_CONNREFUSED: \
......
...@@ -1191,7 +1191,8 @@ options_act_reversible(or_options_t *old_options, char **msg) ...@@ -1191,7 +1191,8 @@ options_act_reversible(or_options_t *old_options, char **msg)
return r; return r;
} }
/** DOCDOC */ /** If we need to have a GEOIP ip-to-country map to run with our configured
* options, return 1 and set *<b>reason_out</b> to a description of why. */
int int
options_need_geoip_info(or_options_t *options, const char **reason_out) options_need_geoip_info(or_options_t *options, const char **reason_out)
{ {
......
...@@ -1361,6 +1361,11 @@ consider_plaintext_ports(edge_connection_t *conn, uint16_t port) ...@@ -1361,6 +1361,11 @@ consider_plaintext_ports(edge_connection_t *conn, uint16_t port)
return 0; return 0;
} }
/** How many times do we try connecting with an exit configured via
* TrackHostExits before concluding that it won't work any more and trying a
* different one? */
#define TRACKHOSTEXITS_RETRIES 5
/** Connection <b>conn</b> just finished its socks handshake, or the /** Connection <b>conn</b> just finished its socks handshake, or the
* controller asked us to take care of it. If <b>circ</b> is defined, * controller asked us to take care of it. If <b>circ</b> is defined,
* then that's where we'll want to attach it. Otherwise we have to * then that's where we'll want to attach it. Otherwise we have to
...@@ -1500,8 +1505,6 @@ connection_ap_handshake_rewrite_and_attach(edge_connection_t *conn, ...@@ -1500,8 +1505,6 @@ connection_ap_handshake_rewrite_and_attach(edge_connection_t *conn,
if (s) { if (s) {
if (s[1] != '\0') { if (s[1] != '\0') {
conn->chosen_exit_name = tor_strdup(s+1); conn->chosen_exit_name = tor_strdup(s+1);
/* DOCDOC */
#define TRACKHOSTEXITS_RETRIES 5
if (remapped_to_exit) /* 5 tries before it expires the addressmap */ if (remapped_to_exit) /* 5 tries before it expires the addressmap */
conn->chosen_exit_retries = TRACKHOSTEXITS_RETRIES; conn->chosen_exit_retries = TRACKHOSTEXITS_RETRIES;
*s = 0; *s = 0;
......
...@@ -2179,13 +2179,13 @@ write_http_response_header(dir_connection_t *conn, ssize_t length, ...@@ -2179,13 +2179,13 @@ write_http_response_header(dir_connection_t *conn, ssize_t length,
} }
#ifdef INSTRUMENT_DOWNLOADS #ifdef INSTRUMENT_DOWNLOADS
/** Map used to keep track of how much data we've up/downloaded in what kind
* of request. Maps from request type to pointer to uint64_t. */
typedef struct request_t { typedef struct request_t {
uint64_t bytes; uint64_t bytes; /**< How many bytes have we transferred? */
uint64_t count; uint64_t count; /**< How many requests have we made? */
} request_t; } request_t;
/** Map used to keep track of how much data we've up/downloaded in what kind
* of request. Maps from request type to pointer to request_t. */
static strmap_t *request_map = NULL; static strmap_t *request_map = NULL;
static void static void
...@@ -2222,7 +2222,7 @@ note_client_request(int purpose, int compressed, size_t bytes) ...@@ -2222,7 +2222,7 @@ note_client_request(int purpose, int compressed, size_t bytes)
tor_free(key); tor_free(key);
} }
/** DOCDOC */ /** Helper: initialize the request map to instrument downloads. */
static void static void
ensure_request_map_initialized(void) ensure_request_map_initialized(void)
{ {
...@@ -3394,6 +3394,8 @@ dir_routerdesc_download_failed(smartlist_t *failed, int status_code, ...@@ -3394,6 +3394,8 @@ dir_routerdesc_download_failed(smartlist_t *failed, int status_code,
* every 10 or 60 seconds (FOO_DESCRIPTOR_RETRY_INTERVAL) in main.c. */ * every 10 or 60 seconds (FOO_DESCRIPTOR_RETRY_INTERVAL) in main.c. */
} }
/** Helper. Compare two fp_pair_t objects, and return -1, 0, or 1 as
* appropriate. */
static int static int
_compare_pairs(const void **a, const void **b) _compare_pairs(const void **a, const void **b)
{ {
...@@ -3405,7 +3407,10 @@ _compare_pairs(const void **a, const void **b) ...@@ -3405,7 +3407,10 @@ _compare_pairs(const void **a, const void **b)
return memcmp(fp1->second, fp2->second, DIGEST_LEN); return memcmp(fp1->second, fp2->second, DIGEST_LEN);
} }
/** DOCDOC */ /** Divide a string <b>res</b> of the form FP1-FP2+FP3-FP4...[.z], where each
* FP is a hex-encoded fingerprint, into a sequence of distinct sorted
* fp_pair_t. Skip malformed pairs. On success, return 0 and add those
* fp_pair_t into <b>pairs_out</b>. On failure, return -1. */
int int
dir_split_resource_into_fingerprint_pairs(const char *res, dir_split_resource_into_fingerprint_pairs(const char *res,
smartlist_t *pairs_out) smartlist_t *pairs_out)
......
...@@ -229,7 +229,8 @@ dns_reset(void) ...@@ -229,7 +229,8 @@ dns_reset(void)
return 0; return 0;
} }
/**DOCDOC*/ /** Return true iff the most recent attempt to initialize the DNS subsystem
* failed. */
int int
has_dns_init_failed(void) has_dns_init_failed(void)
{ {
......
...@@ -307,7 +307,7 @@ static int global_max_retransmits = 3; /* number of times we'll retransmit a req ...@@ -307,7 +307,7 @@ static int global_max_retransmits = 3; /* number of times we'll retransmit a req
/* number of timeouts in a row before we consider this server to be down */ /* number of timeouts in a row before we consider this server to be down */
static int global_max_nameserver_timeout = 3; static int global_max_nameserver_timeout = 3;
/* DOCDOC */ /* true iff we should use the 0x20 hack. */
static int global_randomize_case = 1; static int global_randomize_case = 1;
/* These are the timeout values for nameservers. If we find a nameserver is down */ /* These are the timeout values for nameservers. If we find a nameserver is down */
......
...@@ -23,10 +23,12 @@ typedef struct geoip_entry_t { ...@@ -23,10 +23,12 @@ typedef struct geoip_entry_t {
intptr_t country; /**< An index into geoip_countries */ intptr_t country; /**< An index into geoip_countries */
} geoip_entry_t; } geoip_entry_t;
/** DOCDOC */ /** For how many periods should we remember per-country request history? */
#define REQUEST_HIST_LEN 3 #define REQUEST_HIST_LEN 3
/** How long are the periods for which we should remember request history? */
#define REQUEST_HIST_PERIOD (8*60*60) #define REQUEST_HIST_PERIOD (8*60*60)
/** A per-country record for GeoIP request history */
typedef struct geoip_country_t { typedef struct geoip_country_t {
char countrycode[3]; char countrycode[3];
uint32_t n_v2_ns_requests[REQUEST_HIST_LEN]; uint32_t n_v2_ns_requests[REQUEST_HIST_LEN];
...@@ -269,8 +271,10 @@ static HT_HEAD(clientmap, clientmap_entry_t) client_history = ...@@ -269,8 +271,10 @@ static HT_HEAD(clientmap, clientmap_entry_t) client_history =
/** Time at which we started tracking client IP history. */ /** Time at which we started tracking client IP history. */
static time_t client_history_starts = 0; static time_t client_history_starts = 0;
/** DOCDOC */ /** When did the current period of checking per-country request history
* start? */
static time_t current_request_period_starts = 0; static time_t current_request_period_starts = 0;
/** How many older request periods are we remembering? */
static int n_old_request_periods = 0; static int n_old_request_periods = 0;
/** Hashtable helper: compute a hash of a clientmap_entry_t. */ /** Hashtable helper: compute a hash of a clientmap_entry_t. */
...@@ -312,7 +316,7 @@ geoip_note_client_seen(geoip_client_action_t action, ...@@ -312,7 +316,7 @@ geoip_note_client_seen(geoip_client_action_t action,
#endif #endif
} }
/* DOCDOC */ /* Rotate the current request period. */
while (current_request_period_starts + REQUEST_HIST_PERIOD < now) { while (current_request_period_starts + REQUEST_HIST_PERIOD < now) {
if (!geoip_countries) if (!geoip_countries)
geoip_countries = smartlist_create(); geoip_countries = smartlist_create();
...@@ -430,7 +434,8 @@ _c_hist_compare(const void **_a, const void **_b) ...@@ -430,7 +434,8 @@ _c_hist_compare(const void **_a, const void **_b)
return strcmp(a->country, b->country); return strcmp(a->country, b->country);
} }
/*DOCDOC*/ /** How long do we have to have observed per-country request history before we
* are willing to talk about it? */
#define GEOIP_MIN_OBSERVATION_TIME (12*60*60) #define GEOIP_MIN_OBSERVATION_TIME (12*60*60)
static INLINE unsigned static INLINE unsigned
...@@ -529,7 +534,9 @@ geoip_get_client_history(time_t now, geoip_client_action_t action) ...@@ -529,7 +534,9 @@ geoip_get_client_history(time_t now, geoip_client_action_t action)
return result; return result;
} }
/**DOCDOC*/ /** Return a newly allocated string holding the per-country request history
* for <b>action</b> in a format suitable for an extra-info document, or NULL
* on failure. */
char * char *
geoip_get_request_history(time_t now, geoip_client_action_t action) geoip_get_request_history(time_t now, geoip_client_action_t action)
{ {
......
...@@ -1844,7 +1844,13 @@ append_cell_to_circuit_queue(circuit_t *circ, or_connection_t *orconn, ...@@ -1844,7 +1844,13 @@ append_cell_to_circuit_queue(circuit_t *circ, or_connection_t *orconn,
} }
} }
/** DOCDOC */ /** Append an encoded value of <b>addr<b> to <b>payload_out</b>, which must
* have at least 18 bytes of free space. The encoding is, as specified in
* tor-spec.txt:
* RESOLVED_TYPE_IPV4 or RESOLVED_TYPE_IPV6 [1 byte]
* LENGTH [1 byte]
* ADDRESS [length bytes]
* Return the number of bytes added, or -1 on error */
int int
append_address_to_payload(char *payload_out, const tor_addr_t *addr) append_address_to_payload(char *payload_out, const tor_addr_t *addr)
{ {
...@@ -1867,7 +1873,10 @@ append_address_to_payload(char *payload_out, const tor_addr_t *addr) ...@@ -1867,7 +1873,10 @@ append_address_to_payload(char *payload_out, const tor_addr_t *addr)
} }
} }
/** DODOC */ /** Given <b>payload_len</b> bytes at <b>payload</b>, starting with an address
* encoded as by append_address_to_payload(), try to decode the address into
* *<b>addr_out</b>. Return the next byte in the payload after the address on
* success, or NULL on failure. */
const char * const char *
decode_address_from_payload(tor_addr_t *addr_out, const char *payload, decode_address_from_payload(tor_addr_t *addr_out, const char *payload,
int payload_len) int payload_len)
......
...@@ -777,7 +777,8 @@ rep_hist_record_mtbf_data(void) ...@@ -777,7 +777,8 @@ rep_hist_record_mtbf_data(void)
return -1; return -1;
} }
/** DOCDOC */ /** Format the current tracked status of the router in <b>hist</b> at time
* <b>now</b> for analysis; return it in a newly allocated string. */
static char * static char *
rep_hist_format_router_status(or_history_t *hist, time_t now) rep_hist_format_router_status(or_history_t *hist, time_t now)
{ {
...@@ -821,12 +822,17 @@ rep_hist_format_router_status(or_history_t *hist, time_t now) ...@@ -821,12 +822,17 @@ rep_hist_format_router_status(or_history_t *hist, time_t now)
return tor_strdup(buf); return tor_strdup(buf);
} }
/* DOCDOC */ /** The last stability analysis document that we created, or NULL if we never
* have created one. */
static char *last_stability_doc = NULL; static char *last_stability_doc = NULL;
/** The last time we created a stability analysis document, or 0 if we never
* have created one. */
static time_t built_last_stability_doc_at = 0; static time_t built_last_stability_doc_at = 0;
/** Shortest allowable time between building two stability documents. */
#define MAX_STABILITY_DOC_BUILD_RATE (3*60) #define MAX_STABILITY_DOC_BUILD_RATE (3*60)
/* DOCDOC */ /** Return a pointer to a NUL-terminated document describing our view of the
* stability of the routers we've been tracking. Return NULL on failure. */
const char * const char *
rep_hist_get_router_stability_doc(time_t now) rep_hist_get_router_stability_doc(time_t now)
{ {
......
...@@ -4808,12 +4808,18 @@ struct routerset_t { ...@@ -4808,12 +4808,18 @@ struct routerset_t {
* a router belongs to the set if it is _rejected_ by this policy. */ * a router belongs to the set if it is _rejected_ by this policy. */
smartlist_t *policies; smartlist_t *policies;
/** DOCDOC */ /** A human-readable description of what this routerset is for. Used in
* log messages. */
char *description; char *description;
/** DOCDOC */ /** A list of the country codes in this set. */
smartlist_t *country_names; smartlist_t *country_names;
/** Total number of countries we knew about when we built <b>countries</b>. */
int n_countries; int n_countries;
/** Bit array mapping the return value of geoip_get_country() to 1 iff the
* country is a member of this routerset. Note that we MUST call
* routerset_refresh_countries() whenever the geoip country list is
* reloaded. */
bitarray_t *countries; bitarray_t *countries;
}; };
...@@ -4830,7 +4836,8 @@ routerset_new(void) ...@@ -4830,7 +4836,8 @@ routerset_new(void)
return result; return result;
} }
/** DOCDOC */ /** If <b>c</b> is a country code in the form {cc}, return a newly allocated
* string holding the "cc" part. Else, return NULL. */
static char * static char *
routerset_get_countryname(const char *c) routerset_get_countryname(const char *c)
{ {
...@@ -4981,14 +4988,15 @@ routerset_is_list(const routerset_t *set) ...@@ -4981,14 +4988,15 @@ routerset_is_list(const routerset_t *set)
smartlist_len(set->policies) == 0; smartlist_len(set->policies) == 0;
} }
/** DOCDOC */ /** Return true iff we need a GeoIP IP-to-country database to make sense of
* <b>set</b>. */
int int
routerset_needs_geoip(const routerset_t *set) routerset_needs_geoip(const routerset_t *set)
{ {
return set && smartlist_len(set->country_names); return set && smartlist_len(set->country_names);
} }
/** DOCDOC */ /** Return true iff there are no entries in <b>set</b>. */
static int static int
routerset_is_empty(const routerset_t *set) routerset_is_empty(const routerset_t *set)
{ {
...@@ -4996,8 +5004,12 @@ routerset_is_empty(const routerset_t *set) ...@@ -4996,8 +5004,12 @@ routerset_is_empty(const routerset_t *set)
} }
/** Helper. Return true iff <b>set</b> contains a router based on the other /** Helper. Return true iff <b>set</b> contains a router based on the other
* provided fields. Return higher values for more specific subentries. * provided fields. Return higher values for more specific subentries: a
(If country is -1, then we take the country from addr.) */ * single router is more specific than an address range of routers, which is
* more specific in turn than a country code.
*
* (If country is -1, then we take the country
* from addr.) */
static int static int
routerset_contains(const routerset_t *set, const tor_addr_t *addr, routerset_contains(const routerset_t *set, const tor_addr_t *addr,
uint16_t orport, uint16_t orport,
...@@ -5102,9 +5114,10 @@ routerset_get_all_routers(smartlist_t *out, const routerset_t *routerset, ...@@ -5102,9 +5114,10 @@ routerset_get_all_routers(smartlist_t *out, const routerset_t *routerset,
} }
} }
/** Add to <b>target</b> every node from <b>source</b> that is in /** Add to <b>target</b> every routerinfo_t from <b>source</b> that is in
* <b>include</b> not excluded in a more specific fashion by * <b>include</b>, but not excluded in a more specific fashion by
* <b>exclude</b>. DOCDOC */ * <b>exclude</b>. If <b>running_only</b>, only include running routers.
*/
void void
routersets_get_disjunction(smartlist_t *target, routersets_get_disjunction(smartlist_t *target,
const smartlist_t *source, const smartlist_t *source,
...@@ -5217,14 +5230,15 @@ routerset_free(routerset_t *routerset) ...@@ -5217,14 +5230,15 @@ routerset_free(routerset_t *routerset)
tor_free(routerset); tor_free(routerset);
} }
/** DOCDOC */ /** Refresh the country code of <b>ri</b>. This function MUST be called on
* each router when the GeoIP database is reloaded, and on all new routers. */
void void
routerinfo_set_country(routerinfo_t *ri) routerinfo_set_country(routerinfo_t *ri)
{ {
ri->country = geoip_get_country_by_ip(ri->addr); ri->country = geoip_get_country_by_ip(ri->addr);
} }
/** DOCDOC */ /** Set the country code of all routers in the routerlist. */
void void
routerlist_refresh_countries(void) routerlist_refresh_countries(void)
{ {
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment