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)
{
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
#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>.
#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;
/** 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;
}
#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)
{
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;
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) {
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)
{
} 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)
{
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)
"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;
}
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)
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)
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)
}
#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)
}
}
-/** DOCDOC */
+/** Perform whatever operations are needed on <b>conn</b> to enable
+ * rate-limiting. */
void
connection_enable_rate_limiting(connection_t *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,
*
* 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,
* 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)
}
}
-/** 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)
{
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)
{
* 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
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. */
/** 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,
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)
{
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)
{
projects / thirdparty / tor.git / commitdiff
