mirror of
https://gitlab.torproject.org/tpo/core/tor.git
synced 2024-11-10 21:23:58 +01:00
Resolve many DOCDOCs.
svn:r17662
This commit is contained in:
parent
2ad36f68c8
commit
6693f32530
@ -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);
|
||||
}
|
||||
|
||||
/** DOCDOC */
|
||||
/** Set <b>dest</b> equal to the IPv6 address in the in6_addr <b>in6</b>. */
|
||||
void
|
||||
tor_addr_from_in6(tor_addr_t *dest, const struct in6_addr *in6)
|
||||
{
|
||||
|
@ -53,7 +53,8 @@ typedef struct logfile_t {
|
||||
int is_temporary; /**< Boolean: close after initializing logging subsystem.*/
|
||||
int is_syslog; /**< Boolean: send messages to syslog. */
|
||||
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;
|
||||
|
||||
static void log_free(logfile_t *victim);
|
||||
@ -415,7 +416,7 @@ _log_err(log_domain_mask_t domain, const char *format, ...)
|
||||
}
|
||||
#endif
|
||||
|
||||
/** DOCDOC */
|
||||
/** Free all storage held by <b>victim</b>. */
|
||||
static void
|
||||
log_free(logfile_t *victim)
|
||||
{
|
||||
@ -730,14 +731,17 @@ log_level_to_string(int 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[] = {
|
||||
"GENERAL", "CRYPTO", "NET", "CONFIG", "FS", "PROTOCOL", "MM",
|
||||
"HTTP", "APP", "CONTROL", "CIRC", "REND", "BUG", "DIR", "DIRSERV",
|
||||
"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
|
||||
parse_log_domain(const char *domain)
|
||||
{
|
||||
|
@ -138,7 +138,7 @@ memarea_clear(memarea_t *area)
|
||||
area->first->next_mem = area->first->u.mem;
|
||||
}
|
||||
|
||||
/** DOCDOC */
|
||||
/** Remove all unused memarea chunks from the internal freelist. */
|
||||
void
|
||||
memarea_clear_freelist(void)
|
||||
{
|
||||
|
@ -1442,7 +1442,11 @@ tor_tls_used_v1_handshake(tor_tls_t *tls)
|
||||
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
|
||||
tor_tls_get_buffer_sizes(tor_tls_t *tls,
|
||||
int *rbuf_capacity, int *rbuf_bytes,
|
||||
|
@ -33,7 +33,8 @@ typedef struct tor_tls_t tor_tls_t;
|
||||
#define TOR_TLS_WANTWRITE -1
|
||||
#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 \
|
||||
case TOR_TLS_ERROR_MISC: \
|
||||
case TOR_TLS_ERROR_CONNREFUSED: \
|
||||
|
@ -1191,7 +1191,8 @@ options_act_reversible(or_options_t *old_options, char **msg)
|
||||
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
|
||||
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)
|
||||
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
|
||||
* 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
|
||||
@ -1500,8 +1505,6 @@ connection_ap_handshake_rewrite_and_attach(edge_connection_t *conn,
|
||||
if (s) {
|
||||
if (s[1] != '\0') {
|
||||
conn->chosen_exit_name = tor_strdup(s+1);
|
||||
/* DOCDOC */
|
||||
#define TRACKHOSTEXITS_RETRIES 5
|
||||
if (remapped_to_exit) /* 5 tries before it expires the addressmap */
|
||||
conn->chosen_exit_retries = TRACKHOSTEXITS_RETRIES;
|
||||
*s = 0;
|
||||
|
@ -2179,13 +2179,13 @@ write_http_response_header(dir_connection_t *conn, ssize_t length,
|
||||
}
|
||||
|
||||
#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 {
|
||||
uint64_t bytes;
|
||||
uint64_t count;
|
||||
uint64_t bytes; /**< How many bytes have we transferred? */
|
||||
uint64_t count; /**< How many requests have we made? */
|
||||
} 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 void
|
||||
@ -2222,7 +2222,7 @@ note_client_request(int purpose, int compressed, size_t bytes)
|
||||
tor_free(key);
|
||||
}
|
||||
|
||||
/** DOCDOC */
|
||||
/** Helper: initialize the request map to instrument downloads. */
|
||||
static void
|
||||
ensure_request_map_initialized(void)
|
||||
{
|
||||
@ -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. */
|
||||
}
|
||||
|
||||
/** Helper. Compare two fp_pair_t objects, and return -1, 0, or 1 as
|
||||
* appropriate. */
|
||||
static int
|
||||
_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);
|
||||
}
|
||||
|
||||
/** 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
|
||||
dir_split_resource_into_fingerprint_pairs(const char *res,
|
||||
smartlist_t *pairs_out)
|
||||
|
@ -229,7 +229,8 @@ dns_reset(void)
|
||||
return 0;
|
||||
}
|
||||
|
||||
/**DOCDOC*/
|
||||
/** Return true iff the most recent attempt to initialize the DNS subsystem
|
||||
* failed. */
|
||||
int
|
||||
has_dns_init_failed(void)
|
||||
{
|
||||
|
@ -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 */
|
||||
static int global_max_nameserver_timeout = 3;
|
||||
|
||||
/* DOCDOC */
|
||||
/* true iff we should use the 0x20 hack. */
|
||||
static int global_randomize_case = 1;
|
||||
|
||||
/* These are the timeout values for nameservers. If we find a nameserver is down */
|
||||
|
@ -23,10 +23,12 @@ typedef struct geoip_entry_t {
|
||||
intptr_t country; /**< An index into geoip_countries */
|
||||
} geoip_entry_t;
|
||||
|
||||
/** DOCDOC */
|
||||
/** For how many periods should we remember per-country request history? */
|
||||
#define REQUEST_HIST_LEN 3
|
||||
/** How long are the periods for which we should remember request history? */
|
||||
#define REQUEST_HIST_PERIOD (8*60*60)
|
||||
|
||||
/** A per-country record for GeoIP request history */
|
||||
typedef struct geoip_country_t {
|
||||
char countrycode[3];
|
||||
uint32_t n_v2_ns_requests[REQUEST_HIST_LEN];
|
||||
@ -269,8 +271,10 @@ static HT_HEAD(clientmap, clientmap_entry_t) client_history =
|
||||
/** Time at which we started tracking client IP history. */
|
||||
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;
|
||||
/** How many older request periods are we remembering? */
|
||||
static int n_old_request_periods = 0;
|
||||
|
||||
/** Hashtable helper: compute a hash of a clientmap_entry_t. */
|
||||
@ -312,7 +316,7 @@ geoip_note_client_seen(geoip_client_action_t action,
|
||||
#endif
|
||||
}
|
||||
|
||||
/* DOCDOC */
|
||||
/* Rotate the current request period. */
|
||||
while (current_request_period_starts + REQUEST_HIST_PERIOD < now) {
|
||||
if (!geoip_countries)
|
||||
geoip_countries = smartlist_create();
|
||||
@ -430,7 +434,8 @@ _c_hist_compare(const void **_a, const void **_b)
|
||||
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)
|
||||
|
||||
static INLINE unsigned
|
||||
@ -529,7 +534,9 @@ geoip_get_client_history(time_t now, geoip_client_action_t action)
|
||||
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 *
|
||||
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,
|
||||
}
|
||||
}
|
||||
|
||||
/** 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
|
||||
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 *
|
||||
decode_address_from_payload(tor_addr_t *addr_out, const char *payload,
|
||||
int payload_len)
|
||||
|
@ -777,7 +777,8 @@ rep_hist_record_mtbf_data(void)
|
||||
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 *
|
||||
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);
|
||||
}
|
||||
|
||||
/* DOCDOC */
|
||||
/** The last stability analysis document that we created, or NULL if we never
|
||||
* have created one. */
|
||||
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;
|
||||
/** Shortest allowable time between building two stability documents. */
|
||||
#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 *
|
||||
rep_hist_get_router_stability_doc(time_t now)
|
||||
{
|
||||
|
@ -4808,12 +4808,18 @@ struct routerset_t {
|
||||
* a router belongs to the set if it is _rejected_ by this policy. */
|
||||
smartlist_t *policies;
|
||||
|
||||
/** DOCDOC */
|
||||
/** A human-readable description of what this routerset is for. Used in
|
||||
* log messages. */
|
||||
char *description;
|
||||
|
||||
/** DOCDOC */
|
||||
/** A list of the country codes in this set. */
|
||||
smartlist_t *country_names;
|
||||
/** Total number of countries we knew about when we built <b>countries</b>. */
|
||||
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;
|
||||
};
|
||||
|
||||
@ -4830,7 +4836,8 @@ routerset_new(void)
|
||||
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 *
|
||||
routerset_get_countryname(const char *c)
|
||||
{
|
||||
@ -4981,14 +4988,15 @@ routerset_is_list(const routerset_t *set)
|
||||
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
|
||||
routerset_needs_geoip(const routerset_t *set)
|
||||
{
|
||||
return set && smartlist_len(set->country_names);
|
||||
}
|
||||
|
||||
/** DOCDOC */
|
||||
/** Return true iff there are no entries in <b>set</b>. */
|
||||
static int
|
||||
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
|
||||
* provided fields. Return higher values for more specific subentries.
|
||||
(If country is -1, then we take the country from addr.) */
|
||||
* provided fields. Return higher values for more specific subentries: a
|
||||
* 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
|
||||
routerset_contains(const routerset_t *set, const tor_addr_t *addr,
|
||||
uint16_t orport,
|
||||
@ -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
|
||||
* <b>include</b> not excluded in a more specific fashion by
|
||||
* <b>exclude</b>. DOCDOC */
|
||||
/** Add to <b>target</b> every routerinfo_t from <b>source</b> that is in
|
||||
* <b>include</b>, but not excluded in a more specific fashion by
|
||||
* <b>exclude</b>. If <b>running_only</b>, only include running routers.
|
||||
*/
|
||||
void
|
||||
routersets_get_disjunction(smartlist_t *target,
|
||||
const smartlist_t *source,
|
||||
@ -5217,14 +5230,15 @@ routerset_free(routerset_t *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
|
||||
routerinfo_set_country(routerinfo_t *ri)
|
||||
{
|
||||
ri->country = geoip_get_country_by_ip(ri->addr);
|
||||
}
|
||||
|
||||
/** DOCDOC */
|
||||
/** Set the country code of all routers in the routerlist. */
|
||||
void
|
||||
routerlist_refresh_countries(void)
|
||||
{
|
||||
|
Loading…
Reference in New Issue
Block a user