Commit fefba953 authored by Nick Mathewson's avatar Nick Mathewson 👁
Browse files

r11629@catbus: nickm | 2007-02-02 15:06:17 -0500

 Removing the last DOCDOC comment hurt so much that I had to use Doxygen to identify undocumented macros and comments, and add 150 more DOCDOCs to point out where they were.  Oops.  Hey, kids!  Fixing some of these could be your first Tor patch!


svn:r9477
parent e521c96c
......@@ -107,17 +107,20 @@ const char compat_c_id[] =
#include "strlcat.c"
#endif
/* used by inet_addr, not defined on solaris anywhere!? */
#ifndef INADDR_NONE
/* This is used by inet_addr, but apparently Solaris doesn't define it
* anyplace. */
#define INADDR_NONE ((unsigned long) -1)
#endif
#ifdef HAVE_SYS_MMAN_H
/** DOCDOC */
typedef struct tor_mmap_impl_t {
tor_mmap_t base;
size_t mapping_size; /**< Size of the actual mapping. (This is this file
* size, rounded up to the nearest page.) */
} tor_mmap_impl_t;
/** DOCDOC */
tor_mmap_t *
tor_mmap_file(const char *filename)
{
......@@ -165,6 +168,7 @@ tor_mmap_file(const char *filename)
return &(res->base);
}
/** DOCDOC */
void
tor_munmap_file(tor_mmap_t *handle)
{
......@@ -174,6 +178,7 @@ tor_munmap_file(tor_mmap_t *handle)
tor_free(h);
}
#elif defined(MS_WINDOWS)
/** DOCDOC */
typedef struct win_mmap_t {
tor_mmap_t base;
HANDLE file_handle;
......@@ -966,6 +971,7 @@ typedef struct tor_pthread_data_t {
void (*func)(void *);
void *data;
} tor_pthread_data_t;
/** DOCDOC */
static void *
tor_pthread_helper_fn(void *_data)
{
......@@ -1092,6 +1098,8 @@ tor_gettimeofday(struct timeval *timeval)
}
#if defined(TOR_IS_MULTITHREADED) && !defined(MS_WINDOWS)
/** Defined iff we need to add locks when defining fake versions of reentrant
* versions of time-related functions. */
#define TIME_FNS_NEED_LOCKS
#endif
......@@ -1206,6 +1214,7 @@ tor_get_thread_id(void)
struct tor_mutex_t {
pthread_mutex_t mutex;
};
/** DOCDOC */
tor_mutex_t *
tor_mutex_new(void)
{
......@@ -1213,18 +1222,21 @@ tor_mutex_new(void)
pthread_mutex_init(&mutex->mutex, NULL);
return mutex;
}
/** DOCDOC */
void
tor_mutex_acquire(tor_mutex_t *m)
{
tor_assert(m);
pthread_mutex_lock(&m->mutex);
}
/** DOCDOC */
void
tor_mutex_release(tor_mutex_t *m)
{
tor_assert(m);
pthread_mutex_unlock(&m->mutex);
}
/** DOCDOC */
void
tor_mutex_free(tor_mutex_t *m)
{
......@@ -1232,6 +1244,7 @@ tor_mutex_free(tor_mutex_t *m)
pthread_mutex_destroy(&m->mutex);
tor_free(m);
}
/** DOCDOC */
unsigned long
tor_get_thread_id(void)
{
......
......@@ -28,8 +28,7 @@ const char container_c_id[] =
#include "ht.h"
/* All newly allocated smartlists have this capacity.
*/
/** All newly allocated smartlists have this capacity. */
#define SMARTLIST_DEFAULT_CAPACITY 32
/** Allocate and return an empty smartlist.
......
......@@ -11,7 +11,12 @@
#include "compat.h"
#include "util.h"
/** A resizeable list of pointers, with associated helpful functionality. */
/** A resizeable list of pointers, with associated helpful functionality.
*
* The members of this struct are exposed only so that macros and inlines can
* use them; all access to smartlist internals should go throuch the functions
* and macros defined here.
**/
typedef struct smartlist_t {
/** <b>list</b> has enough capacity to store exactly <b>capacity</b> elements
* before it needs to be resized. Only the first <b>num_used</b> (\<=
......
......@@ -550,7 +550,7 @@ crypto_pk_read_public_key_from_string(crypto_pk_env_t *env, const char *src,
return 0;
}
/* Write the private key from 'env' into the file named by 'fname',
/** Write the private key from 'env' into the file named by 'fname',
* PEM-encoded. Return 0 on success, -1 on failure.
*/
int
......
......@@ -160,12 +160,14 @@ void *smartlist_choose(const struct smartlist_t *sl);
int base64_encode(char *dest, size_t destlen, const char *src, size_t srclen);
int base64_decode(char *dest, size_t destlen, const char *src, size_t srclen);
/** Characters that can appear (case-insensitively) in a base-32 encoding. */
#define BASE32_CHARS "abcdefghijklmnopqrstuvwxyz234567"
void base32_encode(char *dest, size_t destlen, const char *src, size_t srclen);
int digest_to_base64(char *d64, const char *digest);
int digest_from_base64(char *digest, const char *d64);
/** DOCDOC */
#define S2K_SPECIFIER_LEN 9
void secret_to_key(char *key_out, size_t key_out_len, const char *secret,
size_t secret_len, const char *s2k_specifier);
......
......@@ -90,6 +90,7 @@
/** Bandwidth accounting. */
#define LD_ACCT (1u<<17)
/** DOCDOC */
typedef void (*log_callback)(int severity, uint32_t domain, const char *msg);
int parse_log_level(const char *level);
......
......@@ -299,6 +299,7 @@ detect_compression_method(const char *in, size_t in_len)
}
}
/** DOCDOC */
struct tor_zlib_state_t {
struct z_stream_s stream;
int compress;
......
......@@ -12,6 +12,7 @@
#define __TORGZIP_H
#define TORGZIP_H_ID "$Id$"
/** DOCDOC */
typedef enum {
NO_METHOD=0, GZIP_METHOD=1, ZLIB_METHOD=2, UNKNOWN_METHOD=3
} compress_method_t;
......@@ -31,6 +32,7 @@ int is_gzip_supported(void);
compress_method_t detect_compression_method(const char *in, size_t in_len);
/** DOCDOC */
typedef enum {
TOR_ZLIB_OK, TOR_ZLIB_DONE, TOR_ZLIB_BUF_FULL, TOR_ZLIB_ERR
} tor_zlib_output_t;
......
......@@ -103,6 +103,7 @@ tls_log_errors(int severity, const char *doing)
}
}
/** DOCDOC */
static int
tor_errno_to_tls_error(int e)
{
......@@ -205,6 +206,7 @@ tor_tls_init(void)
}
}
/** DOCDOC */
void
tor_tls_free_all(void)
{
......@@ -720,6 +722,7 @@ tor_tls_get_peer_cert_nickname(int severity, tor_tls_t *tls,
return r;
}
/** DOCDOC */
static void
log_cert_lifetime(X509 *cert, const char *problem)
{
......
......@@ -31,7 +31,7 @@ typedef struct tor_tls_t tor_tls_t;
#define TOR_TLS_WANTWRITE -1
#define TOR_TLS_DONE 0
/* Use this macro in a switch statement to catch _any_ TLS error. That way,
/** Use this macro in a switch statement to catch _any_ TLS error. That way,
* if more errors are added, your switches will still work. */
#define CASE_TOR_TLS_ERROR_ANY \
case TOR_TLS_ERROR_MISC: \
......
......@@ -125,7 +125,7 @@ _tor_malloc(size_t size DMALLOC_PARAMS)
return result;
}
/* Allocate a chunk of <b>size</b> bytes of memory, fill the memory with
/** Allocate a chunk of <b>size</b> bytes of memory, fill the memory with
* zero bytes, and return a pointer to the result. Log and terminate
* the process on error. (Same as calloc(size,1), but never returns NULL.)
*/
......@@ -361,7 +361,7 @@ tor_strisnonupper(const char *s)
return 1;
}
/* Compares the first strlen(s2) characters of s1 with s2. Returns as for
/** Compares the first strlen(s2) characters of s1 with s2. Returns as for
* strcmp.
*/
int
......@@ -371,7 +371,7 @@ strcmpstart(const char *s1, const char *s2)
return strncmp(s1, s2, n);
}
/* Compares the first strlen(s2) characters of s1 with s2. Returns as for
/** Compares the first strlen(s2) characters of s1 with s2. Returns as for
* strcasecmp.
*/
int
......@@ -381,7 +381,7 @@ strcasecmpstart(const char *s1, const char *s2)
return strncasecmp(s1, s2, n);
}
/* Compares the last strlen(s2) characters of s1 with s2. Returns as for
/** Compares the last strlen(s2) characters of s1 with s2. Returns as for
* strcmp.
*/
int
......@@ -394,7 +394,7 @@ strcmpend(const char *s1, const char *s2)
return strncmp(s1+(n1-n2), s2, n2);
}
/* Compares the last strlen(s2) characters of s1 with s2. Returns as for
/** Compares the last strlen(s2) characters of s1 with s2. Returns as for
* strcasecmp.
*/
int
......@@ -624,7 +624,7 @@ hex_decode_digit(char c)
}
}
/** Given a hexadecimal string of <b>srclen</b> bytes in <b>src/b>, decode it
/** Given a hexadecimal string of <b>srclen</b> bytes in <b>src</b>, decode it
* and store the result in the <b>destlen</b>-byte buffer at <b>dest</b>.
* Return 0 on success, -1 on failure. */
int
......@@ -878,7 +878,9 @@ tv_addms(struct timeval *a, long ms)
a->tv_usec %= 1000000;
}
/** DOCDOC */
#define IS_LEAPYEAR(y) (!(y % 4) && ((y % 100) || !(y % 400)))
/** DOCDOC */
static int
n_leapdays(int y1, int y2)
{
......@@ -1263,7 +1265,7 @@ write_str_to_file(const char *fname, const char *str, int bin)
}
/** Helper: given a set of flags as passed to open(2), open the file
* <b>fname</b> and write all the sized_chunk_t structs in <b>chunks</t> to
* <b>fname</b> and write all the sized_chunk_t structs in <b>chunks</b> to
* the file. Do so as atomically as possible e.g. by opening temp files and
* renaming. */
static int
......@@ -1320,7 +1322,7 @@ write_chunks_to_file_impl(const char *fname, const smartlist_t *chunks,
return -1;
}
/* Given a smartlist of sized_chunk_t, write them atomically to a file
/** Given a smartlist of sized_chunk_t, write them atomically to a file
* <b>fname</b>, overwriting or creating the file as necessary. */
int
write_chunks_to_file(const char *fname, const smartlist_t *chunks, int bin)
......@@ -1962,8 +1964,11 @@ get_interface_address(int severity, uint32_t *addr)
#ifndef MS_WINDOWS
/* Based on code contributed by christian grothoff */
/** DOCDOC */
static int start_daemon_called = 0;
/** DOCDOC */
static int finish_daemon_called = 0;
/** DOCDOC */
static int daemon_filedes[2];
/** Start putting the process into daemon mode: fork and drop all resources
* except standard fds. The parent process never returns, but stays around
......
......@@ -39,10 +39,13 @@
#error "Sorry; we don't support building with NDEBUG."
#else
#ifdef __GNUC__
/** DOCDOC */
#define PREDICT_FALSE(x) PREDICT((x) == ((typeof(x)) 0), 0)
#else
#define PREDICT_FALSE(x) !(x)
#endif
/** DOCDOC */
#define tor_assert(expr) do { \
if (PREDICT_FALSE(expr)) { \
log(LOG_ERR, LD_BUG, "%s:%d: %s: Assertion %s failed; aborting.", \
......@@ -106,6 +109,8 @@ extern int dmalloc_free(const char *file, const int line, void *pnt,
#endif
/* String manipulation */
/** DOCDOC */
#define HEX_CHARACTERS "0123456789ABCDEFabcdef"
void tor_strlower(char *s) ATTR_NONNULL((1));
void tor_strupper(char *s) ATTR_NONNULL((1));
......@@ -118,6 +123,7 @@ int strcmpend(const char *s1, const char *s2) ATTR_PURE ATTR_NONNULL((1,2));
int strcasecmpend(const char *s1, const char *s2)
ATTR_PURE ATTR_NONNULL((1,2));
int tor_strstrip(char *s, const char *strip) ATTR_NONNULL((1,2));
/** DOCDOC */
typedef enum {
ALWAYS_TERMINATE, NEVER_TERMINATE, TERMINATE_IF_EVEN
} part_finish_rule_t;
......@@ -163,9 +169,11 @@ int parse_iso_time(const char *buf, time_t *t);
int write_all(int fd, const char *buf, size_t count, int isSocket);
int read_all(int fd, char *buf, size_t count, int isSocket);
/** DOCDOC */
typedef enum { FN_ERROR, FN_NOENT, FN_FILE, FN_DIR} file_status_t;
file_status_t file_status(const char *filename);
/** DOCDOC */
typedef enum { CPD_NONE, CPD_CREATE, CPD_CHECK } cpd_check_t;
int check_private_dir(const char *dirname, cpd_check_t check);
int write_str_to_file(const char *fname, const char *str, int bin);
......
......@@ -22,7 +22,7 @@ const char buffers_c_id[] =
#ifdef SENTINELS
/* If SENTINELS is defined, check for attempts to write beyond the
* end/before the start of the buffer.
* end/before the start of the buffer. DOCDOC macros
*/
#define START_MAGIC 0x70370370u
#define END_MAGIC 0xA0B0C0D0u
......@@ -49,6 +49,7 @@ const char buffers_c_id[] =
#define INLINE
#endif
/* DOCDOC */
#define BUFFER_MAGIC 0xB0FFF312u
/** A resizeable buffer, optimized for reading and writing. */
struct buf_t {
......
......@@ -288,7 +288,7 @@ origin_circuit_init(uint8_t purpose, int onehop_tunnel,
return circ;
}
/** Build a new circuit for <b>purpose</b>. If <b>info/b>
/** Build a new circuit for <b>purpose</b>. If <b>info</b>
* is defined, then use that as your exit router, else choose a suitable
* exit node.
*
......@@ -1117,6 +1117,7 @@ router_handles_some_port(routerinfo_t *router, smartlist_t *needed_ports)
return 0;
}
/* DOCDOC */
static int
ap_stream_wants_exit_attention(connection_t *conn)
{
......@@ -1982,6 +1983,7 @@ control_event_guard_deferred(void)
#endif
}
/* DOCDOC */
#define NUM_ENTRY_PICK_TRIES 100
/** Add a new (preferably stable and fast) router to our
......
......@@ -48,12 +48,14 @@ _orconn_circid_entries_eq(orconn_circid_circuit_map_t *a,
return a->or_conn == b->or_conn && a->circ_id == b->circ_id;
}
/** DOCDOC */
static INLINE unsigned int
_orconn_circid_entry_hash(orconn_circid_circuit_map_t *a)
{
return (((unsigned)a->circ_id)<<16) ^ (unsigned)(uintptr_t)(a->or_conn);
}
/** DOCDOC */
static HT_HEAD(orconn_circid_map, orconn_circid_circuit_map_t)
orconn_circid_circuit_map = HT_INITIALIZER();
HT_PROTOTYPE(orconn_circid_map, orconn_circid_circuit_map_t, node,
......@@ -279,6 +281,7 @@ origin_circuit_new(void)
return circ;
}
/** DOCDOC */
or_circuit_t *
or_circuit_new(uint16_t p_circ_id, or_connection_t *p_conn)
{
......
......@@ -22,7 +22,7 @@ extern circuit_t *global_circuitlist; /* from circuitlist.c */
static void circuit_expire_old_circuits(time_t now);
static void circuit_increment_failure_count(void);
/* Return 1 if <b>circ</b> could be returned by circuit_get_best().
/** Return 1 if <b>circ</b> could be returned by circuit_get_best().
* Else return 0.
*/
static int
......@@ -112,7 +112,7 @@ circuit_is_acceptable(circuit_t *circ, edge_connection_t *conn,
return 1;
}
/* Return 1 if circuit <b>a</b> is better than circuit <b>b</b> for
/** Return 1 if circuit <b>a</b> is better than circuit <b>b</b> for
* <b>purpose</b>, and return 0 otherwise. Used by circuit_get_best.
*/
static int
......@@ -566,8 +566,10 @@ circuit_expire_old_circuits(time_t now)
}
}
/** DOCDOC */
#define NUM_PARALLEL_TESTING_CIRCS 4
/** DOCDOC */
static int have_performed_bandwidth_test = 0;
/** Reset have_performed_bandwidth_test, so we'll start building
......@@ -774,6 +776,7 @@ circuit_build_failed(origin_circuit_t *circ)
* circuit_launch_new and circuit_*_failure_count.
*/
static int n_circuit_failures = 0;
/** DOCDOC */
static int did_circs_fail_last_period = 0;
/** Don't retry launching a new circuit if we try this many times with no
......
......@@ -102,6 +102,7 @@ typedef struct config_var_t {
const char *initvalue; /**< String (or null) describing initial value. */
} config_var_t;
/** DOCDOC */
#define STRUCT_VAR_P(st, off) \
((void*) ( ((char*)st) + off ) )
......@@ -511,6 +512,7 @@ static config_var_description_t state_description[] = {
{ NULL, NULL },
};
/** DOCDOC */
typedef int (*validate_fn_t)(void*,void*,int,char**);
/** Information on the keys, value types, key-to-struct-member mappings,
......@@ -529,6 +531,7 @@ typedef struct {
config_var_t *extra;
} config_format_t;
/** DOCDOC */
#define CHECK(fmt, cfg) do { \
tor_assert(fmt && cfg); \
tor_assert((fmt)->magic == \
......@@ -591,8 +594,10 @@ static void check_libevent_version(const char *m, int server);
/*static*/ or_options_t *options_new(void);
/** DOCDOC */
#define OR_OPTIONS_MAGIC 9090909
/** DOCDOC */
static config_format_t options_format = {
sizeof(or_options_t),
OR_OPTIONS_MAGIC,
......@@ -604,12 +609,15 @@ static config_format_t options_format = {
NULL
};
/** DOCDOC */
#define OR_STATE_MAGIC 0x57A73f57
/** DOCDOC */
static config_var_t state_extra_var = {
"__extra", CONFIG_TYPE_LINELIST, STRUCT_OFFSET(or_state_t, ExtraLines), NULL
};
/** DOCDOC */
static config_format_t state_format = {
sizeof(or_state_t),
OR_STATE_MAGIC,
......@@ -1443,6 +1451,7 @@ option_get_assignment(or_options_t *options, const char *key)
return get_assigned_option(&options_format, options, key);
}
/** DOCDOC */
static config_line_t *
config_lines_dup(const config_line_t *inp)
{
......@@ -1459,6 +1468,7 @@ config_lines_dup(const config_line_t *inp)
return result;
}
/** DOCDOC */
static config_line_t *
get_assigned_option(config_format_t *fmt, or_options_t *options,
const char *key)
......@@ -2135,7 +2145,7 @@ config_init(config_format_t *fmt, void *options)
}
}
/* Allocate and return a new string holding the written-out values of the vars
/** Allocate and return a new string holding the written-out values of the vars
* in 'options'. If 'minimal', do not write out any default-valued vars.
* Else, if comment_defaults, write default values as comments.
*/
......@@ -2230,7 +2240,7 @@ options_dump(or_options_t *options, int minimal)
return config_dump(&options_format, options, minimal, 0);
}
/* Return 0 if every element of sl is a string holding a decimal
/** Return 0 if every element of sl is a string holding a decimal
* representation of a port number, or if sl is NULL.
* Otherwise set *msg and return -1. */
static int
......@@ -3795,6 +3805,7 @@ static const struct {
{ NULL, LE_OTHER }
};
/** DOCDOC */
static le_version_t
decode_libevent_version(void)
{
......
......@@ -24,7 +24,7 @@ const char connection_edge_c_id[] =
#define TRANS_PF
#endif
/* List of exit_redirect_t */
/** List of exit_redirect_t for every configured RedirectExit. */
static smartlist_t *redirect_exit_list = NULL;
static int connection_ap_handshake_process_socks(edge_connection_t *conn);
......@@ -927,7 +927,7 @@ client_dns_set_reverse_addressmap(const char *address, const char *v,
* application accidentally tried to connect to them directly (not
* via Tor), it wouldn't get too far astray.
*
* Eventually, we should probably make this configurable.
* These options are configured by parse_virtual_addr_network().
*/
static uint32_t virtual_addr_network = 0x7fc00000u;
static uint32_t virtual_addr_netmask = 0xffc00000u;
......@@ -1182,7 +1182,7 @@ addressmap_get_mappings(smartlist_t *sl, time_t min_expires,
}
}
/* 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,
* then that's where we'll want to attach it. Otherwise we have to
* figure it out ourselves.
......@@ -1394,6 +1394,7 @@ connection_ap_handshake_rewrite_and_attach(edge_connection_t *conn,
safe_str(conn->rend_query));
rend_client_refetch_renddesc(conn->rend_query);
} else { /* r > 0 */
/** DOCDOC */
#define NUM_SECONDS_BEFORE_REFETCH (60*15)
if (time(NULL) - entry->received < NUM_SECONDS_BEFORE_REFETCH) {
conn->_base.state = AP_CONN_STATE_CIRCUIT_WAIT;
......
......@@ -810,7 +810,9 @@ connection_or_count_pending_circs(or_connection_t *or_conn)
return cnt;
}
/** DOCDOC */
#define BUF_FULLNESS_THRESHOLD (128*1024)
/** DOCDOC */
#define BUF_EMPTINESS_THRESHOLD (96*1024)
/** Return true iff there is so much data waiting to be flushed on <b>conn</b>
......
......@@ -11,8 +11,10 @@ const char control_c_id[] =
#include "or.h"
/** DOCDOC */
#define STATE_IS_OPEN(s) ((s) == CONTROL_CONN_STATE_OPEN_V0 || \
(s) == CONTROL_CONN_STATE_OPEN_V1)
/** DOCDOC */
#define STATE_IS_V0(s) ((s) == CONTROL_CONN_STATE_NEEDAUTH_V0 || \
(s) == CONTROL_CONN_STATE_OPEN_V0)
......@@ -685,6 +687,7 @@ send_control1_event_string(uint16_t event, event_format_t which,
}
}
/** DOCDOC */
static void
send_control1_event_impl(uint16_t event, event_format_t which, int extended,
const char *format, va_list ap)
......@@ -1437,6 +1440,7 @@ handle_control_mapaddress(control_connection_t *conn, uint32_t len,
return 0;
}
/** DOCDOC */
static int
getinfo_helper_misc(control_connection_t *conn, const char *question,
char **answer)
......@@ -1474,6 +1478,7 @@ getinfo_helper_misc(control_connection_t *conn, const char *question,
return 0;
}
/** DOCDOC */
static int
getinfo_helper_dir(control_connection_t *control_conn,
const char *question, char **answer)
......@@ -1581,6 +1586,7 @@ getinfo_helper_dir(control_connection_t *control_conn,
return 0;
}
/** DOCDOC */
static int
getinfo_helper_events(control_connection_t *control_conn,
const char *question, char **answer)
......@@ -1726,9 +1732,11 @@ getinfo_helper_events(control_connection_t *control_conn,
return 0;
}
/** DOCDOC */
typedef int (*getinfo_helper_t)(control_connection_t *,
const char *q, char **a);
/** DOCDOC */
typedef struct getinfo_item_t {
const char *varname;
getinfo_helper_t fn;
......@@ -1740,6 +1748,7 @@ typedef struct getinfo_item_t {
#define PREFIX(name, fn, desc) { name, getinfo_helper_##fn, desc, 1 }
#define DOC(name, desc) { name, NULL, desc, 0 }
/** DOCDOC */
static const getinfo_item_t getinfo_items[] = {
ITEM("version", misc, "The current version of Tor."),
ITEM("config-file", misc, "Current location of the \"torrc\" file."),
......@@ -2537,6 +2546,7 @@ handle_control_closecircuit(control_connection_t *conn, uint32_t len,
return 0;
}
/** DOCDOC */
static int
handle_control_usefeature(control_connection_t *conn,
uint32_t len,
......@@ -2966,6 +2976,7 @@ connection_control_process_inbuf(control_connection_t *conn)
return connection_control_process_inbuf_v1(conn);
}
/** DOCDOC */
static const char *
circuit_end_reason_to_string(int reason)
{
......@@ -3231,6 +3242,7 @@ control_event_stream_status(edge_connection_t *conn, stream_status_event_t tp,
return 0;