sarah
/
tor
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Resolve about 24 DOCDOCs

This commit is contained in:
Nick Mathewson 2012-06-05 00:17:54 -04:00
parent 064e7c19c6
commit 913067f788
17 changed files with 84 additions and 44 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
src/common/compat.c
View File

@ -2364,7 +2364,12 @@ tor_gettimeofday(struct timeval *timeval)
#define TIME_FNS_NEED_LOCKS
#endif
/* DOCDOC correct_tm */
/** Helper: Deal with confused or out-of-bounds values from localtime_r and
* friends. (On some platforms, they can give out-of-bounds values or can
* return NULL.) If <b>islocal</b>, this is a localtime result; otherwise
* it's from gmtime. The function returned <b>r</b>, when given <b>timep</b>
* as its input. If we need to store new results, store them in
* <b>resultbuf</b>. */
static struct tm *
correct_tm(int islocal, const time_t *timep, struct tm *resultbuf,
struct tm *r)

7
src/common/compat_libevent.h
View File

@ -59,10 +59,15 @@ struct timeval;
int tor_event_base_loopexit(struct event_base *base, struct timeval *tv);
#endif
/* DOCDOC tor_libevent_cfg */
/** Defines a configuration for using libevent with Tor: passed as an argument
* to tor_libevent_initialize() to describe how we want to set up. */
typedef struct tor_libevent_cfg {
/** Flag: if true, disable IOCP (assuming that it could be enabled). */
int disable_iocp;
/** How many CPUs should we use (relevant only with IOCP). */
int num_cpus;
/** How many milliseconds should we allow between updating bandwidth limits?
* (relevant only with bufferevents). */
int msec_per_tick;
} tor_libevent_cfg;

2
src/common/log.c
View File

@ -97,7 +97,7 @@ should_log_function_name(log_domain_mask_t domain, int severity)
/** A mutex to guard changes to logfiles and logging. */
static tor_mutex_t log_mutex;
/* DOCDOC log_mutex_initialized */
/** True iff we have initialized log_mutex */
static int log_mutex_initialized = 0;
/** Linked list of logfile_t. */

18
src/common/tortls.c
View File

@ -223,10 +223,12 @@ static int check_cert_lifetime_internal(int severity, const X509 *cert,
int past_tolerance, int future_tolerance);
/** Global TLS contexts. We keep them here because nobody else needs
* to touch them. */
* to touch them.
*
* @{ */
static tor_tls_context_t *server_tls_context = NULL;
/* DOCDOC client_tls_context */
static tor_tls_context_t *client_tls_context = NULL;
/**@}*/
/** True iff tor_tls_init() has been called. */
static int tls_library_is_initialized = 0;
@ -269,7 +271,9 @@ tor_tls_get_state_description(tor_tls_t *tls, char *buf, size_t sz)
tor_snprintf(buf, sz, "%s%s", ssl_state, tortls_state);
}
/* DOCDOC tor_tls_log_one_error */
/** Log a single error <b>err</b> as returned by ERR_get_error(), which was
* received while performing an operation <b>doing</b> on <b>tls</b>. Log
* the message at <b>severity</b>, in log domain <b>domain</b>. */
void
tor_tls_log_one_error(tor_tls_t *tls, unsigned long err,
int severity, int domain, const char *doing)
@ -314,8 +318,8 @@ tor_tls_log_one_error(tor_tls_t *tls, unsigned long err,
}
}
/** Log all pending tls errors at level <b>severity</b>. Use
* <b>doing</b> to describe our current activities.
/** Log all pending tls errors at level <b>severity</b> in log domain
* <b>domain</b>. Use <b>doing</b> to describe our current activities.
*/
static void
tls_log_errors(tor_tls_t *tls, int severity, int domain, const char *doing)
@ -1344,7 +1348,7 @@ tor_tls_client_is_using_v2_ciphers(const SSL *ssl, const char *address)
return 1;
}
/* DOCDOC tor_tls_debug_state_callback */
/** Invoked when a TLS state changes: log the change at severity 'debug' */
static void
tor_tls_debug_state_callback(const SSL *ssl, int type, int val)
{
@ -1624,7 +1628,7 @@ tor_tls_block_renegotiation(tor_tls_t *tls)
tls->ssl->s3->flags &= ~SSL3_FLAGS_ALLOW_UNSAFE_LEGACY_RENEGOTIATION;
}
/* DOCDOC tor_tls_assert_renegotiation_unblocked */
/** Assert that the flags that allow legacy renegotiation are still set */
void
tor_tls_assert_renegotiation_unblocked(tor_tls_t *tls)
{

1
src/common/util.h
View File

@ -72,7 +72,6 @@
/* Memory management */
void *_tor_malloc(size_t size DMALLOC_PARAMS) ATTR_MALLOC;
void *_tor_malloc_zero(size_t size DMALLOC_PARAMS) ATTR_MALLOC;
/* DOCDOC _tor_malloc_roundup */
void *_tor_malloc_roundup(size_t *size DMALLOC_PARAMS) ATTR_MALLOC;
void *_tor_calloc(size_t nmemb, size_t size DMALLOC_PARAMS) ATTR_MALLOC;
void *_tor_realloc(void *ptr, size_t size DMALLOC_PARAMS);

3
src/common/util_codedigest.c
View File

@ -1,7 +1,8 @@
#include "util.h"
/** DOCDOC */
/** Return a string describing the digest of the source files in src/common/
*/
const char *
libor_get_digests(void)
{

3
src/or/config.c
View File

@ -786,7 +786,8 @@ extern const char tor_git_revision[]; /* from tor_main.c */
/** The version of this Tor process, as parsed. */
static char *the_tor_version = NULL;
/* DOCDOC the_short_tor_version */
/** A shorter version of this Tor process's version, for export in our router
* descriptor. (Does not include the git version, if any.) */
static char *the_short_tor_version = NULL;
/** Return the current Tor version. */

3
src/or/config_codedigest.c
View File

@ -1,7 +1,8 @@
const char *tor_get_digests(void);
/** DOCDOC */
/** Return a string describing the digest of the source files in src/or/
*/
const char *
tor_get_digests(void)
{

10
src/or/control.c
View File

@ -920,12 +920,13 @@ handle_control_loadconf(control_connection_t *conn, uint32_t len,
return 0;
}
/* DOCDOC control_event_t */
/** Helper structure: maps event values to their names. */
struct control_event_t {
uint16_t event_code;
const char *event_name;
};
/* DOCDOC control_event_table */
/** Table mapping event values to their names. Used to implement SETEVENTS
* and GETINFO events/names, and to keep they in sync. */
static const struct control_event_t control_event_table[] = {
{ EVENT_CIRCUIT_STATUS, "CIRC" },
{ EVENT_CIRCUIT_STATUS_MINOR, "CIRC_MINOR" },
@ -3217,7 +3218,10 @@ is_valid_initial_command(control_connection_t *conn, const char *cmd)
* interfaces is broken. */
#define MAX_COMMAND_LINE_LENGTH (1024*1024)
/* DOCDOC peek_connection_has_control0_command */
/** Wrapper around peek_(evbuffer|buf)_has_control0 command: presents the same
* interface as those underlying functions, but takes a connection_t intead of
* an evbuffer or a buf_t.
*/
static int
peek_connection_has_control0_command(connection_t *conn)
{

4
src/or/networkstatus.c
View File

@ -78,7 +78,9 @@ typedef struct consensus_waiting_for_certs_t {
int dl_failed;
} consensus_waiting_for_certs_t;
/* DOCDOC consensus_waiting_for_certs */
/** An array, for each flavor of consensus we might want, of consensuses that
* we have downloaded, but which we cannot verify due to having insufficient
* authority certificates. */
static consensus_waiting_for_certs_t
consensus_waiting_for_certs[N_CONSENSUS_FLAVORS];

2
src/or/or.h
View File

@ -1065,7 +1065,7 @@ typedef struct connection_t {
uint64_t dirreq_id;
} connection_t;
/* DOCDOC listener_connection_t */
/** Subtype of connection_t; used for a listener socket. */
typedef struct listener_connection_t {
connection_t _base;

7
src/or/relay.c
View File

@ -64,7 +64,7 @@ static struct timeval cached_time_hires = {0, 0};
* cells. */
#define CELL_QUEUE_LOWWATER_SIZE 64
/* DOCDOC tor_gettimeofday_cached */
/** Return a fairly recent view of the current time. */
static void
tor_gettimeofday_cached(struct timeval *tv)
{
@ -74,7 +74,8 @@ tor_gettimeofday_cached(struct timeval *tv)
*tv = cached_time_hires;
}
/* DOCDOC tor_gettimeofday_cache_clear */
/** Reset the cached view of the current time, so that the next time we try
* to learn it, we will get an up-to-date value. */
void
tor_gettimeofday_cache_clear(void)
{
@ -2095,7 +2096,9 @@ static double ewma_scale_factor = 0.1;
/* DOCDOC ewma_enabled */
static int ewma_enabled = 0;
/*DOCDOC*/
#define EPSILON 0.00001
/*DOCDOC*/
#define LOG_ONEHALF -0.69314718055994529
/** Adjust the global cell scale factor based on <b>options</b> */

3
src/or/rendcommon.c
View File

@ -797,7 +797,8 @@ rend_cache_entry_free(rend_cache_entry_t *e)
tor_free(e);
}
/* DOCDOC _rend_cache_entry_free */
/** Helper: deallocate a rend_cache_entry_t. (Used with strmap_free(), which
* requires a function pointer whose argument is void*). */
static void
_rend_cache_entry_free(void *p)
{

6
src/or/rephist.c
View File

@ -1772,9 +1772,13 @@ rep_hist_load_state(or_state_t *state, char **err)
/*********************************************************************/
/* DOCDOC predicted_port_t */
/** A single predicted port: used to remember which ports we've made
* connections to, so that we can try to keep making circuits that can handle
* those ports. */
typedef struct predicted_port_t {
/** The port we connected to */
uint16_t port;
/** The time at which we last used it */
time_t time;
} predicted_port_t;

3
src/or/router.c
View File

@ -484,7 +484,8 @@ v3_authority_check_key_expiry(void)
last_warned = now;
}
/* DOCDOC router_initialize_tls_context */
/** Set up Tor's TLS contexts, based on our configuration and keys. Return 0
* on success, and -1 on failure. */
int
router_initialize_tls_context(void)
{

11
src/or/routerlist.h
View File

@ -85,14 +85,16 @@ void router_set_status(const char *digest, int up);
static int WRA_WAS_ADDED(was_router_added_t s);
static int WRA_WAS_OUTDATED(was_router_added_t s);
static int WRA_WAS_REJECTED(was_router_added_t s);
/** Return true iff the descriptor was added. It might still be necessary to
* check whether the descriptor generator should be notified.
/** Return true iff the outcome code in <b>s</b> indicates that the descriptor
* was added. It might still be necessary to check whether the descriptor
* generator should be notified.
*/
static INLINE int
WRA_WAS_ADDED(was_router_added_t s) {
return s == ROUTER_ADDED_SUCCESSFULLY || s == ROUTER_ADDED_NOTIFY_GENERATOR;
}
/** Return true iff the descriptor was not added because it was either:
/** Return true iff the outcome code in <b>s</b> indicates that the descriptor
* was not added because it was either:
* - not in the consensus
* - neither in the consensus nor in any networkstatus document
* - it was outdated.
@ -103,7 +105,8 @@ static INLINE int WRA_WAS_OUTDATED(was_router_added_t s)
s == ROUTER_NOT_IN_CONSENSUS ||
s == ROUTER_NOT_IN_CONSENSUS_OR_NETWORKSTATUS);
}
/* DOCDOC WRA_WAS_REJECTED */
/** Return true iff the outcome code in <b>s</b> indicates that the descriptor
* was flat-out rejected. */
static INLINE int WRA_WAS_REJECTED(was_router_added_t s)
{
return (s == ROUTER_AUTHDIR_REJECTS);

38
src/or/routerparse.c
View File

@ -263,7 +263,7 @@ typedef struct token_rule_t {
/* Argument multiplicity: exactly <b>n</b> arguments. */
#define EQ(n) n,n,0
/** List of tokens allowable in router descriptors */
/** List of tokens recognized in router descriptors */
static token_rule_t routerdesc_token_table[] = {
T0N("reject", K_REJECT, ARGS, NO_OBJ ),
T0N("accept", K_ACCEPT, ARGS, NO_OBJ ),
@ -296,7 +296,7 @@ static token_rule_t routerdesc_token_table[] = {
END_OF_TABLE
};
/** List of tokens allowable in extra-info documents. */
/** List of tokens recognized in extra-info documents. */
static token_rule_t extrainfo_token_table[] = {
T1_END( "router-signature", K_ROUTER_SIGNATURE, NO_ARGS, NEED_OBJ ),
T1( "published", K_PUBLISHED, CONCAT_ARGS, NO_OBJ ),
@ -333,7 +333,7 @@ static token_rule_t extrainfo_token_table[] = {
END_OF_TABLE
};
/** List of tokens allowable in the body part of v2 and v3 networkstatus
/** List of tokens recognized in the body part of v2 and v3 networkstatus
* documents. */
static token_rule_t rtrstatus_token_table[] = {
T01("p", K_P, CONCAT_ARGS, NO_OBJ ),
@ -346,7 +346,7 @@ static token_rule_t rtrstatus_token_table[] = {
END_OF_TABLE
};
/** List of tokens allowable in the header part of v2 networkstatus documents.
/** List of tokens recognized in the header part of v2 networkstatus documents.
*/
static token_rule_t netstatus_token_table[] = {
T1( "published", K_PUBLISHED, CONCAT_ARGS, NO_OBJ ),
@ -364,14 +364,14 @@ static token_rule_t netstatus_token_table[] = {
END_OF_TABLE
};
/** List of tokens allowable in the footer of v1/v2 directory/networkstatus
/** List of tokens recognized in the footer of v1/v2 directory/networkstatus
* footers. */
static token_rule_t dir_footer_token_table[] = {
T1("directory-signature", K_DIRECTORY_SIGNATURE, EQ(1), NEED_OBJ ),
END_OF_TABLE
};
/** List of tokens allowable in v1 directory headers/footers. */
/** List of tokens recognized in v1 directory headers/footers. */
static token_rule_t dir_token_table[] = {
/* don't enforce counts; this is obsolete. */
T( "network-status", K_NETWORK_STATUS, NO_ARGS, NO_OBJ ),
@ -403,14 +403,14 @@ static token_rule_t dir_token_table[] = {
NO_ARGS, NEED_OBJ), \
T01("dir-address", K_DIR_ADDRESS, GE(1), NO_OBJ),
/** List of tokens allowable in V3 authority certificates. */
/** List of tokens recognized in V3 authority certificates. */
static token_rule_t dir_key_certificate_table[] = {
CERTIFICATE_MEMBERS
T1("fingerprint", K_FINGERPRINT, CONCAT_ARGS, NO_OBJ ),
END_OF_TABLE
};
/** List of tokens allowable in rendezvous service descriptors */
/** List of tokens recognized in rendezvous service descriptors */
static token_rule_t desc_token_table[] = {
T1_START("rendezvous-service-descriptor", R_RENDEZVOUS_SERVICE_DESCRIPTOR,
EQ(1), NO_OBJ),
@ -424,7 +424,7 @@ static token_rule_t desc_token_table[] = {
END_OF_TABLE
};
/** List of tokens allowed in the (encrypted) list of introduction points of
/** List of tokens recognized in the (encrypted) list of introduction points of
* rendezvous service descriptors */
static token_rule_t ipo_token_table[] = {
T1_START("introduction-point", R_IPO_IDENTIFIER, EQ(1), NO_OBJ),
@ -435,7 +435,7 @@ static token_rule_t ipo_token_table[] = {
END_OF_TABLE
};
/** List of tokens allowed in the (possibly encrypted) list of introduction
/** List of tokens recognized in the (possibly encrypted) list of introduction
* points of rendezvous service descriptors */
static token_rule_t client_keys_token_table[] = {
T1_START("client-name", C_CLIENT_NAME, CONCAT_ARGS, NO_OBJ),
@ -444,7 +444,7 @@ static token_rule_t client_keys_token_table[] = {
END_OF_TABLE
};
/** List of tokens allowed in V3 networkstatus votes. */
/** List of tokens recognized in V3 networkstatus votes. */
static token_rule_t networkstatus_token_table[] = {
T1_START("network-status-version", K_NETWORK_STATUS_VERSION,
GE(1), NO_OBJ ),
@ -472,7 +472,7 @@ static token_rule_t networkstatus_token_table[] = {
END_OF_TABLE
};
/** List of tokens allowed in V3 networkstatus consensuses. */
/** List of tokens recognized in V3 networkstatus consensuses. */
static token_rule_t networkstatus_consensus_token_table[] = {
T1_START("network-status-version", K_NETWORK_STATUS_VERSION,
GE(1), NO_OBJ ),
@ -498,7 +498,7 @@ static token_rule_t networkstatus_consensus_token_table[] = {
END_OF_TABLE
};
/** List of tokens allowable in the footer of v1/v2 directory/networkstatus
/** List of tokens recognized in the footer of v1/v2 directory/networkstatus
* footers. */
static token_rule_t networkstatus_vote_footer_token_table[] = {
T01("directory-footer", K_DIRECTORY_FOOTER, NO_ARGS, NO_OBJ ),
@ -507,7 +507,7 @@ static token_rule_t networkstatus_vote_footer_token_table[] = {
END_OF_TABLE
};
/** List of tokens allowable in detached networkstatus signature documents. */
/** List of tokens recognized in detached networkstatus signature documents. */
static token_rule_t networkstatus_detached_signature_token_table[] = {
T1_START("consensus-digest", K_CONSENSUS_DIGEST, GE(1), NO_OBJ ),
T("additional-digest", K_ADDITIONAL_DIGEST,GE(3), NO_OBJ ),
@ -519,7 +519,7 @@ static token_rule_t networkstatus_detached_signature_token_table[] = {
END_OF_TABLE
};
/* DOCDOC microdesc_token_table */
/** List of tokens recognized in microdescriptors */
static token_rule_t microdesc_token_table[] = {
T1_START("onion-key", K_ONION_KEY, NO_ARGS, NEED_KEY_1024),
T01("family", K_FAMILY, ARGS, NO_OBJ ),
@ -4201,7 +4201,13 @@ find_all_exitpolicy(smartlist_t *s)
return out;
}
/* DOCDOC router_get_hash_impl_helper */
/** Helper function for <b>router_get_hash_impl</b>: given <b>s</b>,
* <b>s_len</b>, <b>start_str</b>, <b>end_str</b>, and <b>end_c</b> with the
* same semantics as in that function, set *<b>start_out</b> (inclusive) and
* *<b>end_out</b> (exclusive) to the boundaries of the string to be hashed.
*
* Return 0 on success and -1 on failure.
*/
static int
router_get_hash_impl_helper(const char *s, size_t s_len,
const char *start_str,