Commit f68c0426 authored by Nick Mathewson's avatar Nick Mathewson 🎨
Browse files

Resolve all currently pending DOCDOC items in master

parent 41e8bee1
......@@ -143,7 +143,8 @@ tor_open_cloexec(const char *path, int flags, unsigned mode)
return fd;
}
/** DOCDOC */
/** As fpoen(path,mode), but ensures that the O_CLOEXEC bit is set on the
* underlying file handle. */
FILE *
tor_fopen_cloexec(const char *path, const char *mode)
{
......
......@@ -3323,7 +3323,15 @@ process_handle_new(void)
return out;
}
/*DOCDOC*/
/**
* @name child-process states
*
* Each of these values represents a possible state that a child process can
* be in. They're used to determine what to say when telling the parent how
* far along we were before failure.
*
* @{
*/
#define CHILD_STATE_INIT 0
#define CHILD_STATE_PIPE 1
#define CHILD_STATE_MAXFD 2
......@@ -3334,7 +3342,7 @@ process_handle_new(void)
#define CHILD_STATE_CLOSEFD 7
#define CHILD_STATE_EXEC 8
#define CHILD_STATE_FAILEXEC 9
/** @} */
/** Start a program in the background. If <b>filename</b> contains a '/', then
* it will be treated as an absolute or relative path. Otherwise, on
* non-Windows systems, the system path will be searched for <b>filename</b>.
......
......@@ -409,8 +409,10 @@ void set_environment_variable_in_smartlist(struct smartlist_t *env_vars,
#define PROCESS_STATUS_ERROR -1
#ifdef UTIL_PRIVATE
/*DOCDOC*/
/** Structure to represent the state of a process with which Tor is
* communicating. The contents of this structure are private to util.c */
struct process_handle_t {
/** One of the PROCESS_STATUS_* values */
int status;
#ifdef _WIN32
HANDLE stdout_pipe;
......
......@@ -675,11 +675,12 @@ static const config_format_t state_format = {
/** Command-line and config-file options. */
static or_options_t *global_options = NULL;
/** DOCDOC */
/** The fallback options_t object; this is where we look for options not
* in torrc before we fall back to Tor's defaults. */
static or_options_t *global_default_options = NULL;
/** Name of most recently read torrc file. */
static char *torrc_fname = NULL;
/** DOCDOC */
/** Name of the most recently read torrc-defaults file.*/
static char *torrc_defaults_fname;
/** Persistent serialized state. */
static or_state_t *global_state = NULL;
......@@ -4345,8 +4346,8 @@ get_windows_conf_root(void)
}
#endif
/** Return the default location for our torrc file.
* DOCDOC defaults_file */
/** Return the default location for our torrc file (if <b>defaults_file</b> is
* false), or for the torrc-defaults file (if <b>defaults_file</b> is true). */
static const char *
get_default_conf_file(int defaults_file)
{
......@@ -4396,12 +4397,21 @@ check_nickname_list(const char *lst, const char *name, char **msg)
return r;
}
/** Learn config file name from command line arguments, or use the default,
* DOCDOC defaults_file */
/** Learn config file name from command line arguments, or use the default.
*
* If <b>defaults_file</b> is true, we're looking for torrc-defaults;
* otherwise, we're looking for the regular torrc_file.
*
* Set *<b>using_default_fname</b> to true if we're using the default
* configuration file name; or false if we've set it from the command line.
*
* Set *<b>ignore_missing_torrc</b> to true if we should ignore the resulting
* filename if it doesn't exist.
*/
static char *
find_torrc_filename(int argc, char **argv,
int defaults_file,
int *using_default_torrc, int *ignore_missing_torrc)
int *using_default_fname, int *ignore_missing_torrc)
{
char *fname=NULL;
int i;
......@@ -4427,14 +4437,14 @@ find_torrc_filename(int argc, char **argv,
fname = absfname;
}
*using_default_torrc = 0;
*using_default_fname = 0;
++i;
} else if (ignore_opt && !strcmp(argv[i],ignore_opt)) {
*ignore_missing_torrc = 1;
}
}
if (*using_default_torrc) {
if (*using_default_fname) {
/* didn't find one, try CONFDIR */
const char *dflt = get_default_conf_file(defaults_file);
if (dflt && file_status(dflt) == FN_FILE) {
......@@ -4458,8 +4468,13 @@ find_torrc_filename(int argc, char **argv,
return fname;
}
/** Load torrc from disk, setting torrc_fname if successful.
* DOCDOC defaults_file */
/** Load a configuration file from disk, setting torrc_fname or
* torrc_defaults_fname if successful.
*
* If <b>defaults_file</b> is true, load torrc-defaults; otherwise load torrc.
*
* Return the contents of the file on success, and NULL on failure.
*/
static char *
load_torrc_from_disk(int argc, char **argv, int defaults_file)
{
......@@ -5455,7 +5470,10 @@ warn_nonlocal_client_ports(const smartlist_t *ports, const char *portname)
} SMARTLIST_FOREACH_END(port);
}
/** DOCDOC */
/** Given a list of port_cfg_t in <b>ports</b>, warn any controller port there
* is listening on any non-loopback address. If <b>forbid</b> is true,
* then emit a stronger warning and remove the port from the list.
*/
static void
warn_nonlocal_controller_ports(smartlist_t *ports, unsigned forbid)
{
......@@ -5839,10 +5857,12 @@ parse_port_config(smartlist_t *out,
return retval;
}
/** DOCDOC */
/** Parse a list of config_line_t for an AF_UNIX unix socket listener option
* from <b>cfg</b> and add them to <b>out</b>. No fancy options are
* supported: the line contains nothing but the path to the AF_UNIX socket. */
static int
parse_socket_config(smartlist_t *out, const config_line_t *cfg,
int listener_type)
parse_unix_socket_config(smartlist_t *out, const config_line_t *cfg,
int listener_type)
{
if (!out)
......@@ -5928,9 +5948,9 @@ parse_ports(const or_options_t *options, int validate_only,
"configuration");
goto err;
}
if (parse_socket_config(ports,
options->ControlSocket,
CONN_TYPE_CONTROL_LISTENER) < 0) {
if (parse_unix_socket_config(ports,
options->ControlSocket,
CONN_TYPE_CONTROL_LISTENER) < 0) {
*msg = tor_strdup("Invalid ControlSocket configuration");
goto err;
}
......@@ -5980,7 +6000,8 @@ parse_ports(const or_options_t *options, int validate_only,
return retval;
}
/** DOCDOC */
/** Given a list of <b>port_cfg_t</b> in <b>ports</b>, check them for internal
* consistency and warn as appropriate. */
static int
check_server_ports(const smartlist_t *ports,
const or_options_t *options)
......
......@@ -1659,7 +1659,8 @@ connection_send_socks5_connect(connection_t *conn)
conn->proxy_state = PROXY_SOCKS5_WANT_CONNECT_OK;
}
/** DOCDOC */
/** Wrapper around fetch_from_(buf/evbuffer)_socks_client: see those functions
* for documentation of its behavior. */
static int
connection_fetch_from_buf_socks_client(connection_t *conn,
int state, char **reason)
......@@ -2239,7 +2240,9 @@ global_write_bucket_low(connection_t *conn, size_t attempt, int priority)
return 0;
}
/** DOCDOC */
/** Helper: adjusts our bandwidth history and informs the controller as
* appropriate, given that we have just read <b>num_read</b> bytes and written
* <b>num_written</b> bytes on <b>conn</b>. */
static void
record_num_bytes_transferred_impl(connection_t *conn,
time_t now, size_t num_read, size_t num_written)
......@@ -2270,7 +2273,8 @@ record_num_bytes_transferred_impl(connection_t *conn,
}
#ifdef USE_BUFFEREVENTS
/** DOCDOC */
/** Wrapper around fetch_from_(buf/evbuffer)_socks_client: see those functions
* for documentation of its behavior. */
static void
record_num_bytes_transferred(connection_t *conn,
time_t now, size_t num_read, size_t num_written)
......@@ -2592,7 +2596,8 @@ connection_get_rate_limit_totals(uint64_t *read_out, uint64_t *written_out)
}
}
/** DOCDOC */
/** Perform whatever operations are needed on <b>conn</b> to enable
* rate-limiting. */
void
connection_enable_rate_limiting(connection_t *conn)
{
......
......@@ -2673,12 +2673,12 @@ connection_ap_handshake_send_resolve(entry_connection_t *ap_conn)
return 0;
}
/** Make an AP connection_t, make a new linked connection pair, and attach
* one side to the conn, connection_add it, initialize it to circuit_wait,
* and call connection_ap_handshake_attach_circuit(conn) on it.
/** Make an AP connection_t linked to the connection_t <b>partner</b>. make a
* new linked connection pair, and attach one side to the conn, connection_add
* it, initialize it to circuit_wait, and call
* connection_ap_handshake_attach_circuit(conn) on it.
*
* Return the other end of the linked connection pair, or -1 if error.
* DOCDOC partner.
* Return the newly created end of the linked connection pair, or -1 if error.
*/
entry_connection_t *
connection_ap_make_link(connection_t *partner,
......
......@@ -2099,7 +2099,8 @@ connection_or_send_auth_challenge_cell(or_connection_t *conn)
*
* If <b>server</b> is false and <b>signing_key</b> is provided, calculate the
* entire authenticator, signed with <b>signing_key</b>.
* DOCDOC return value
*
* Return the length of the cell body on success, and -1 on failure.
*/
int
connection_or_compute_authenticate_cell_body(or_connection_t *conn,
......
......@@ -3788,7 +3788,10 @@ dir_routerdesc_download_failed(smartlist_t *failed, int status_code,
* every 10 or 60 seconds (FOO_DESCRIPTOR_RETRY_INTERVAL) in main.c. */
}
/* DOCDOC NM */
/** Called when a connection to download microdescriptors has failed in whole
* or in part. <b>failed</b> is a list of every microdesc digest we didn't
* get. <b>status_code</b> is the http status code we received. Reschedule the
* microdesc downloads as appropriate. */
static void
dir_microdesc_download_failed(smartlist_t *failed,
int status_code)
......
......@@ -1183,7 +1183,8 @@ update_v2_networkstatus_cache_downloads(time_t now)
}
}
/** DOCDOC */
/** Return true iff, given the options listed in <b>options</b>, <b>flavor</b>
* is the flavor of a consensus networkstatus that we would like to fetch. */
static int
we_want_to_fetch_flavor(const or_options_t *options, int flavor)
{
......@@ -1455,7 +1456,8 @@ networkstatus_get_latest_consensus(void)
return current_consensus;
}
/** DOCDOC */
/** Return the latest consensus we have whose flavor matches <b>f</b>, or NULL
* if we don't have one. */
networkstatus_t *
networkstatus_get_latest_consensus_by_flavor(consensus_flavor_t f)
{
......
......@@ -1251,7 +1251,8 @@ typedef struct or_connection_t {
* bandwidthburst. (OPEN ORs only) */
int write_bucket; /**< When this hits 0, stop writing. Like read_bucket. */
#else
/** DOCDOC */
/** A rate-limiting configuration object to determine how this connection
* set its read- and write- limits. */
/* XXXX we could share this among all connections. */
struct ev_token_bucket_cfg *bucket_cfg;
#endif
......@@ -1729,7 +1730,7 @@ typedef struct {
uint16_t or_port; /**< Port for TLS connections. */
uint16_t dir_port; /**< Port for HTTP directory connections. */
/* DOCDOC */
/** A router's IPv6 address, if it has one. */
/* XXXXX187 Actually these should probably be part of a list of addresses,
* not just a special case. Use abstractions to access these; don't do it
* directly. */
......
......@@ -4188,9 +4188,9 @@ any_trusted_dir_is_v1_authority(void)
/** For every current directory connection whose purpose is <b>purpose</b>,
* and where the resource being downloaded begins with <b>prefix</b>, split
* rest of the resource into base16 fingerprints, decode them, and set the
* rest of the resource into base16 fingerprints (or base64 fingerprints if
* purpose==DIR_PURPPOSE_FETCH_MICRODESC), decode them, and set the
* corresponding elements of <b>result</b> to a nonzero value.
* DOCDOC purpose==microdesc
*/
static void
list_pending_downloads(digestmap_t *result,
......@@ -4235,8 +4235,13 @@ list_pending_descriptor_downloads(digestmap_t *result, int extrainfo)
list_pending_downloads(result, purpose, "d/");
}
/** DOCDOC */
/*XXXX NM should use digest256, if one comes into being. */
/** For every microdescriptor we are currently downloading by descriptor
* digest, set result[d] to (void*)1. (Note that microdescriptor digests
* are 256-bit, and digestmap_t only holds 160-bit digests, so we're only
* getting the first 20 bytes of each digest here.)
*
* XXXX Let there be a digestmap256_t, and use that instead.
*/
void
list_pending_microdesc_downloads(digestmap_t *result)
{
......
......@@ -4169,7 +4169,10 @@ _find_by_keyword(smartlist_t *s, directory_keyword keyword,
return tok;
}
/** DOCDOC */
/** If there are any directory_token_t entries in <b>s</b> whose keyword is
* <b>k</b>, return a newly allocated smartlist_t containing all such entries,
* in the same order in which they occur in <b>s</b>. Otherwise return
* NULL. */
static smartlist_t *
find_all_by_keyword(smartlist_t *s, directory_keyword k)
{
......
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