aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--src/common/util.c273
-rw-r--r--src/common/util.h36
-rw-r--r--src/or/buffers.c86
3 files changed, 214 insertions, 181 deletions
diff --git a/src/common/util.c b/src/common/util.c
index 617c4c77a..d41b0e272 100644
--- a/src/common/util.c
+++ b/src/common/util.c
@@ -2,10 +2,12 @@
/* See LICENSE for licensing information */
/* $Id$ */
-/*****
- * util.c: Common functions for strings, IO, network, data structures,
+/**
+ * \file util.c
+ *
+ * \brief Common functions for strings, IO, network, data structures,
* process control, and cross-platform portability.
- *****/
+ **/
#include "orconfig.h"
@@ -99,11 +101,7 @@
#include "strlcat.c"
#endif
-/*****
- * Memory wrappers
- *****/
-
-/* Allocate a chunk of 'size' bytes of memory, and return a pointer to
+/** Allocate a chunk of <b>size</b> bytes of memory, and return a pointer to
* result. On error, log and terminate the process. (Same as malloc(size),
* but never returns NULL.)
*/
@@ -124,7 +122,7 @@ void *tor_malloc(size_t size) {
return result;
}
-/* Allocate a chunk of 'size' 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.)
*/
@@ -134,7 +132,7 @@ void *tor_malloc_zero(size_t size) {
return result;
}
-/* Change the size of the memory block pointed to by 'ptr' to 'size'
+/** Change the size of the memory block pointed to by <b>ptr</b> to <b>size</b>
* bytes long; return the new memory block. On error, log and
* terminate. (Like realloc(ptr,size), but never returns NULL.)
*/
@@ -149,7 +147,7 @@ void *tor_realloc(void *ptr, size_t size) {
return result;
}
-/* Return a newly allocated copy of the NUL-terminated string s. On
+/** Return a newly allocated copy of the NUL-terminated string s. On
* error, log and terminate. (Like strdup(s), but never returns
* NULL.)
*/
@@ -165,10 +163,11 @@ char *tor_strdup(const char *s) {
return dup;
}
-/* Allocate and return a new string containing the first 'n'
- * characters of 's'. If 's' is longer than 'n' characters, only the
- * first 'n' are copied. The result is always NUL-terminated. (Like
- * strndup(s,n), but never returns NULL.)
+/** Allocate and return a new string containing the first <b>n</b>
+ * characters of <b>s</b>. If <b>s</b> is longer than <b>n</b>
+ * characters, only the first <b>n</b> are copied. The result is
+ * always NUL-terminated. (Like strndup(s,n), but never returns
+ * NULL.)
*/
char *tor_strndup(const char *s, size_t n) {
char *dup;
@@ -179,41 +178,50 @@ char *tor_strndup(const char *s, size_t n) {
return dup;
}
-/* Convert all alphabetic characters in the nul-terminated string 's' to
- * lowercase. */
-void tor_strlower(char *s)
-{
- while (*s) {
- *s = tolower(*s);
- ++s;
- }
-}
#ifndef UNALIGNED_INT_ACCESS_OK
+/**
+ * Read a 16-bit value beginning at <b>cp</b>. Equaivalent to
+ * *(uint16_t*)(cp), but will not cause segfaults on platforms that forbid
+ * unaligned memory access.
+ */
uint16_t get_uint16(const char *cp)
{
uint16_t v;
memcpy(&v,cp,2);
return v;
}
+/**
+ * Read a 32-bit value beginning at <b>cp</b>. Equaivalent to
+ * *(uint32_t*)(cp), but will not cause segfaults on platforms that forbid
+ * unaligned memory access.
+ */
uint32_t get_uint32(const char *cp)
{
uint32_t v;
memcpy(&v,cp,4);
return v;
}
+/**
+ * Set a 16-bit value beginning at <b>cp</b> to <b>v</b>. Equivalent to
+ * *(uint16_t)(cp) = v, but will not cause segfaults on platforms that forbid
+ * unaligned memory access. */
void set_uint16(char *cp, uint16_t v)
{
memcpy(cp,&v,2);
}
+/**
+ * Set a 32-bit value beginning at <b>cp</b> to <b>v</b>. Equivalent to
+ * *(uint32_t)(cp) = v, but will not cause segfaults on platforms that forbid
+ * unaligned memory access. */
void set_uint32(char *cp, uint32_t v)
{
memcpy(cp,&v,4);
}
#endif
-/* Encode the first 'fromlen' bytes stored at 'from' in hexidecimal;
- * write the result as a NUL-terminated string to 'to'. 'to' must
+/** Encode the first <b>fromlen</b> bytes stored at <b>from</b> in hexidecimal;
+ * write the result as a NUL-terminated string to <b>to</b>. <b>to</b> must
* have at least (2*fromlen)+1 bytes of free space.
*/
void hex_encode(const char *from, int fromlen, char *to)
@@ -229,8 +237,8 @@ void hex_encode(const char *from, int fromlen, char *to)
*to = '\0';
}
-/* Return a pointer to a NUL-terminated hexidecimal string encoding
- * the first 'fromlen' bytes of 'from'. (fromlen must be <= 32.) The
+/** Return a pointer to a NUL-terminated hexidecimal string encoding
+ * the first <b>fromlen</b> bytes of <b>from</b>. (fromlen must be \<= 32.) The
* result does not need to be deallocated, but repeated calls to
* hex_str will trash old results.
*/
@@ -253,8 +261,8 @@ const char *hex_str(const char *from, int fromlen)
struct smartlist_t {
- /* 'list' has enough capacity to store exactly 'capacity' elements
- * before it needs to be resized. Only the first 'num_used' (<=
+ /** <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> (\<=
* capacity) elements point to valid data.
*/
void **list;
@@ -262,7 +270,7 @@ struct smartlist_t {
int capacity;
};
-/* Allocate and return an empty smartlist.
+/** Allocate and return an empty smartlist.
*/
smartlist_t *smartlist_create() {
smartlist_t *sl = tor_malloc(sizeof(smartlist_t));
@@ -272,7 +280,7 @@ smartlist_t *smartlist_create() {
return sl;
}
-/* Deallocate a smartlist. Does not release storage associated with the
+/** Deallocate a smartlist. Does not release storage associated with the
* list's elements.
*/
void smartlist_free(smartlist_t *sl) {
@@ -280,9 +288,9 @@ void smartlist_free(smartlist_t *sl) {
free(sl);
}
-/* Change the capacity of the smartlist to 'n', so that we can grow
- * the list up to 'n' elements with no further reallocation or wasted
- * space. If 'n' is less than or equal to the number of elements
+/** Change the capacity of the smartlist to <b>n</b>, so that we can grow
+ * the list up to <b>n</b> elements with no further reallocation or wasted
+ * space. If <b>n</b> is less than or equal to the number of elements
* currently in the list, reduce the list's capacity as much as
* possible without losing elements.
*/
@@ -295,13 +303,13 @@ void smartlist_set_capacity(smartlist_t *sl, int n) {
}
}
-/* Remove all elements from the list.
+/** Remove all elements from the list.
*/
void smartlist_clear(smartlist_t *sl) {
sl->num_used = 0;
}
-/* Set the list's new length to 'len' (which must be <= the list's
+/** Set the list's new length to <b>len</b> (which must be \<= the list's
* current size). Remove the last smartlist_len(sl)-len elements from the
* list.
*/
@@ -311,7 +319,7 @@ void smartlist_truncate(smartlist_t *sl, int len)
sl->num_used = len;
}
-/* Append element to the end of the list. */
+/** Append element to the end of the list. */
void smartlist_add(smartlist_t *sl, void *element) {
if (sl->num_used >= sl->capacity) {
sl->capacity *= 2;
@@ -320,13 +328,13 @@ void smartlist_add(smartlist_t *sl, void *element) {
sl->list[sl->num_used++] = element;
}
-/* Append each element from S2 to the end of S1. */
+/** Append each element from S2 to the end of S1. */
void smartlist_add_all(smartlist_t *sl, const smartlist_t *s2)
{
SMARTLIST_FOREACH(s2, void *, element, smartlist_add(sl, element));
}
-/* Remove all elements E from sl such that E==element. Does not preserve
+/** Remove all elements E from sl such that E==element. Does not preserve
* the order of s1.
*/
void smartlist_remove(smartlist_t *sl, void *element) {
@@ -340,7 +348,7 @@ void smartlist_remove(smartlist_t *sl, void *element) {
}
}
-/* Return true iff some element E of sl has E==element.
+/** Return true iff some element E of sl has E==element.
*/
int smartlist_isin(const smartlist_t *sl, void *element) {
int i;
@@ -350,7 +358,7 @@ int smartlist_isin(const smartlist_t *sl, void *element) {
return 0;
}
-/* Return true iff some element E of sl2 has smartlist_isin(sl1,E).
+/** Return true iff some element E of sl2 has smartlist_isin(sl1,E).
*/
int smartlist_overlap(const smartlist_t *sl1, const smartlist_t *sl2) {
int i;
@@ -360,7 +368,7 @@ int smartlist_overlap(const smartlist_t *sl1, const smartlist_t *sl2) {
return 0;
}
-/* Remove every element E of sl1 such that !smartlist_isin(sl2,E).
+/** Remove every element E of sl1 such that !smartlist_isin(sl2,E).
* Does not preserve the order of sl1.
*/
void smartlist_intersect(smartlist_t *sl1, const smartlist_t *sl2) {
@@ -372,7 +380,7 @@ void smartlist_intersect(smartlist_t *sl1, const smartlist_t *sl2) {
}
}
-/* Remove every element E of sl1 such that smartlist_isin(sl2,E).
+/** Remove every element E of sl1 such that smartlist_isin(sl2,E).
* Does not preserve the order of sl1.
*/
void smartlist_subtract(smartlist_t *sl1, const smartlist_t *sl2) {
@@ -381,7 +389,7 @@ void smartlist_subtract(smartlist_t *sl1, const smartlist_t *sl2) {
smartlist_remove(sl1, sl2->list[i]);
}
-/* Return a randomly chosen element of sl; or NULL if sl is empty.
+/** Return a randomly chosen element of sl; or NULL if sl is empty.
*/
void *smartlist_choose(const smartlist_t *sl) {
if(sl->num_used)
@@ -389,15 +397,15 @@ void *smartlist_choose(const smartlist_t *sl) {
return NULL; /* no elements to choose from */
}
-/* Return the 'idx'th element of sl.
+/** Return the <b>idx</b>th element of sl.
*/
void *smartlist_get(const smartlist_t *sl, int idx)
{
tor_assert(sl && idx>=0 && idx < sl->num_used);
return sl->list[idx];
}
-/* Change the value of the 'idx'th element of sl to 'val'; return the old
- * value of the 'idx'th element.
+/** Change the value of the <b>idx</b>th element of sl to <b>val</b>; return the old
+ * value of the <b>idx</b>th element.
*/
void *smartlist_set(smartlist_t *sl, int idx, void *val)
{
@@ -407,9 +415,9 @@ void *smartlist_set(smartlist_t *sl, int idx, void *val)
sl->list[idx] = val;
return old;
}
-/* Remove the 'idx'th element of sl; if idx is not the last element,
- * swap the last element of sl into the 'idx'th space. Return the old value
- * of the 'idx'th element.
+/** Remove the <b>idx</b>th element of sl; if idx is not the last
+ * element, swap the last element of sl into the <b>idx</b>th space.
+ * Return the old value of the <b>idx</b>th element.
*/
void *smartlist_del(smartlist_t *sl, int idx)
{
@@ -419,9 +427,9 @@ void *smartlist_del(smartlist_t *sl, int idx)
sl->list[idx] = sl->list[--sl->num_used];
return old;
}
-/* Remove the 'idx'th element of sl; if idx is not the last element,
+/** Remove the <b>idx</b>th element of sl; if idx is not the last element,
* moving all subsequent elements back one space. Return the old value
- * of the 'idx'th element.
+ * of the <b>idx</b>th element.
*/
void *smartlist_del_keeporder(smartlist_t *sl, int idx)
{
@@ -433,14 +441,15 @@ void *smartlist_del_keeporder(smartlist_t *sl, int idx)
memmove(sl->list+idx, sl->list+idx+1, sizeof(void*)*(sl->num_used-idx));
return old;
}
-/* Return the number of items in sl.
+/** Return the number of items in sl.
*/
int smartlist_len(const smartlist_t *sl)
{
return sl->num_used;
}
-/* Insert the value 'val' as the new 'idx'th element of 'sl', moving all
- * items previously at 'idx' or later forward one space.
+/** Insert the value <b>val</b> as the new <b>idx</b>th element of
+ * <b>sl</b>, moving all items previously at <b>idx</b> or later
+ * forward one space.
*/
void smartlist_insert(smartlist_t *sl, int idx, void *val)
{
@@ -462,9 +471,8 @@ void smartlist_insert(smartlist_t *sl, int idx, void *val)
}
}
-/*****
- * Splay-tree implementation of string-to-void* map
- *****/
+/* Splay-tree implementation of string-to-void* map
+ */
struct strmap_entry_t {
SPLAY_ENTRY(strmap_entry_t) node;
char *key;
@@ -484,7 +492,7 @@ static int compare_strmap_entries(struct strmap_entry_t *a,
SPLAY_PROTOTYPE(strmap_tree, strmap_entry_t, node, compare_strmap_entries);
SPLAY_GENERATE(strmap_tree, strmap_entry_t, node, compare_strmap_entries);
-/* Create a new empty map from strings to void*'s.
+/** Create a new empty map from strings to void*'s.
*/
strmap_t* strmap_new(void)
{
@@ -494,10 +502,10 @@ strmap_t* strmap_new(void)
return result;
}
-/* Set the current value for <key> with <val>. Returns the previous
- * value for <key> if one was set, or NULL if one was not.
+/** Set the current value for <b>key</b> to <b>val</b>. Returns the previous
+ * value for <b>key</b> if one was set, or NULL if one was not.
*
- * This function makes a copy of 'key' if necessary, but not of 'val'.
+ * This function makes a copy of <b>key</b> if necessary, but not of <b>val</b>.
*/
void* strmap_set(strmap_t *map, const char *key, void *val)
{
@@ -520,7 +528,7 @@ void* strmap_set(strmap_t *map, const char *key, void *val)
}
}
-/* Return the current value associated with <key>, or NULL if no
+/** Return the current value associated with <b>key</b>, or NULL if no
* value is set.
*/
void* strmap_get(strmap_t *map, const char *key)
@@ -537,9 +545,9 @@ void* strmap_get(strmap_t *map, const char *key)
}
}
-/* Remove the value currently associated with <key> from the map.
+/** Remove the value currently associated with <b>key</b> from the map.
* Return the value if one was set, or NULL if there was no entry for
- * <key>.
+ * <b>key</b>.
*
* Note: you must free any storage associated with the returned value.
*/
@@ -562,7 +570,7 @@ void* strmap_remove(strmap_t *map, const char *key)
}
}
-/* Same as strmap_set, but first converts <key> to lowercase. */
+/** Same as strmap_set, but first converts <b>key</b> to lowercase. */
void* strmap_set_lc(strmap_t *map, const char *key, void *val)
{
/* We could be a little faster by using strcasecmp instead, and a separate
@@ -574,7 +582,7 @@ void* strmap_set_lc(strmap_t *map, const char *key, void *val)
tor_free(lc_key);
return v;
}
-/* Same as strmap_get, but first converts <key> to lowercase. */
+/** Same as strmap_get, but first converts <b>key</b> to lowercase. */
void* strmap_get_lc(strmap_t *map, const char *key)
{
void *v;
@@ -584,7 +592,7 @@ void* strmap_get_lc(strmap_t *map, const char *key)
tor_free(lc_key);
return v;
}
-/* Same as strmap_remove, but first converts <key> to lowercase */
+/** Same as strmap_remove, but first converts <b>key</b> to lowercase */
void* strmap_remove_lc(strmap_t *map, const char *key)
{
void *v;
@@ -595,14 +603,14 @@ void* strmap_remove_lc(strmap_t *map, const char *key)
return v;
}
-
-/* Invoke fn() on every entry of the map, in order. For every entry,
+/** Invoke fn() on every entry of the map, in order. For every entry,
* fn() is invoked with that entry's key, that entry's value, and the
- * value of <data> supplied to strmap_foreach. fn() must return a new
+ * value of <b>data</b> supplied to strmap_foreach. fn() must return a new
* (possibly unmodified) value for each entry: if fn() returns NULL, the
* entry is removed.
*
* Example:
+ * \code
* static void* upcase_and_remove_empty_vals(const char *key, void *val,
* void* data) {
* char *cp = (char*)val;
@@ -620,6 +628,7 @@ void* strmap_remove_lc(strmap_t *map, const char *key)
* ...
*
* strmap_foreach(map, upcase_and_remove_empty_vals, NULL);
+ * \endcode
*/
void strmap_foreach(strmap_t *map,
void* (*fn)(const char *key, void *val, void *data),
@@ -639,10 +648,11 @@ void strmap_foreach(strmap_t *map,
}
}
-/* return an 'iterator' pointer to the front of a map.
+/** return an <b>iterator</b> pointer to the front of a map.
*
* Iterator example:
*
+ * \code
* // uppercase values in "map", removing empty values.
*
* strmap_iter_t *iter;
@@ -661,6 +671,7 @@ void strmap_foreach(strmap_t *map,
* iter = strmap_iter_next(iter);
* }
* }
+ * \endcode
*
*/
strmap_iter_t *strmap_iter_init(strmap_t *map)
@@ -668,14 +679,14 @@ strmap_iter_t *strmap_iter_init(strmap_t *map)
tor_assert(map);
return SPLAY_MIN(strmap_tree, &map->head);
}
-/* Advance the iterator 'iter' for map a single step to the next entry.
+/** Advance the iterator <b>iter</b> for map a single step to the next entry.
*/
strmap_iter_t *strmap_iter_next(strmap_t *map, strmap_iter_t *iter)
{
tor_assert(map && iter);
return SPLAY_NEXT(strmap_tree, &map->head, iter);
}
-/* Advance the iterator 'iter' a single step to the next entry, removing
+/** Advance the iterator <b>iter</b> a single step to the next entry, removing
* the current entry.
*/
strmap_iter_t *strmap_iter_next_rmv(strmap_t *map, strmap_iter_t *iter)
@@ -688,7 +699,7 @@ strmap_iter_t *strmap_iter_next_rmv(strmap_t *map, strmap_iter_t *iter)
tor_free(iter);
return next;
}
-/* Set *keyp and *valp to the current entry pointed to by iter.
+/** Set *keyp and *valp to the current entry pointed to by iter.
*/
void strmap_iter_get(strmap_iter_t *iter, const char **keyp, void **valp)
{
@@ -696,14 +707,14 @@ void strmap_iter_get(strmap_iter_t *iter, const char **keyp, void **valp)
*keyp = iter->key;
*valp = iter->val;
}
-/* Return true iff iter has advanced past the last entry of map.
+/** Return true iff iter has advanced past the last entry of map.
*/
int strmap_iter_done(strmap_iter_t *iter)
{
return iter == NULL;
}
-/* Remove all entries from <map>, and deallocate storage for those entries.
- * If free_val is provided, it is invoked on every value in <map>.
+/** Remove all entries from <b>map</b>, and deallocate storage for those entries.
+ * If free_val is provided, it is invoked on every value in <b>map</b>.
*/
void strmap_free(strmap_t *map, void (*free_val)(void*))
{
@@ -723,7 +734,18 @@ void strmap_free(strmap_t *map, void (*free_val)(void*))
* String manipulation
*/
-/* Return a pointer to the first char of s that is not whitespace and
+/** Convert all alphabetic characters in the nul-terminated string <b>s</b> to
+ * lowercase. */
+void tor_strlower(char *s)
+{
+ while (*s) {
+ *s = tolower(*s);
+ ++s;
+ }
+}
+
+
+/** Return a pointer to the first char of s that is not whitespace and
* not a comment, or to the terminating NUL if no such character exists.
*/
const char *eat_whitespace(const char *s) {
@@ -742,7 +764,7 @@ const char *eat_whitespace(const char *s) {
return s;
}
-/* Return a pointer to the first char of s that is not a space or a tab,
+/** Return a pointer to the first char of s that is not a space or a tab,
* or to the terminating NUL if no such character exists. */
const char *eat_whitespace_no_nl(const char *s) {
while(*s == ' ' || *s == '\t')
@@ -750,7 +772,7 @@ const char *eat_whitespace_no_nl(const char *s) {
return s;
}
-/* Return a pointer to the first char of s that is whitespace or '#',
+/** Return a pointer to the first char of s that is whitespace or <b>#</b>,
* or to the terminating NUL if no such character exists.
*/
const char *find_whitespace(const char *s) {
@@ -762,11 +784,11 @@ const char *find_whitespace(const char *s) {
return s;
}
-/*****
+/*
* Time
- *****/
+ */
-/* Set *timeval to the current time of day. On error, log and terminate.
+/** Set *timeval to the current time of day. On error, log and terminate.
* (Same as gettimeofday(timeval,NULL), but never returns -1.)
*/
void tor_gettimeofday(struct timeval *timeval) {
@@ -785,7 +807,7 @@ void tor_gettimeofday(struct timeval *timeval) {
return;
}
-/* Return the number of microseconds elapsed between *start and *end.
+/** Return the number of microseconds elapsed between *start and *end.
* If start is after end, return 0.
*/
long
@@ -808,7 +830,7 @@ tv_udiff(struct timeval *start, struct timeval *end)
return udiff;
}
-/* Return -1 if *a<*b, 0 if *a==*b, and 1 if *a>*b.
+/** Return -1 if *a \< *b, 0 if *a==*b, and 1 if *a \> *b.
*/
int tv_cmp(struct timeval *a, struct timeval *b) {
if (a->tv_sec > b->tv_sec)
@@ -822,7 +844,7 @@ int tv_cmp(struct timeval *a, struct timeval *b) {
return 0;
}
-/* Increment *a by the number of seconds and microseconds in *b.
+/** Increment *a by the number of seconds and microseconds in *b.
*/
void tv_add(struct timeval *a, struct timeval *b) {
a->tv_usec += b->tv_usec;
@@ -830,7 +852,7 @@ void tv_add(struct timeval *a, struct timeval *b) {
a->tv_usec %= 1000000;
}
-/* Increment *a by 'ms' milliseconds.
+/** Increment *a by <b>ms</b> milliseconds.
*/
void tv_addms(struct timeval *a, long ms) {
a->tv_usec += (ms * 1000) % 1000000;
@@ -845,10 +867,11 @@ static int n_leapdays(int y1, int y2) {
--y2;
return (y2/4 - y1/4) - (y2/100 - y1/100) + (y2/400 - y1/400);
}
+/** Number of days per month in non-leap year; used by tor_timegm. */
static const int days_per_month[] =
{ 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31};
-/* Return a time_t given a struct tm. The result is given in GMT, and
+/** Return a time_t given a struct tm. The result is given in GMT, and
* does not account for leap seconds.
*/
time_t tor_timegm (struct tm *tm) {
@@ -878,10 +901,10 @@ time_t tor_timegm (struct tm *tm) {
* Low-level I/O.
*/
-/* Write 'count' bytes from 'buf' to 'fd'. isSocket must be 1 if fd
- * was returned by socket() or accept(), and 0 if fd was returned by
- * open(). Return the number of bytes written, or -1 on error. Only
- * use if fd is a blocking fd. */
+/** Write <b>count</b> bytes from <b>buf</b> to <b>fd</b>. <b>isSocket</b>
+ * must be 1 if fd was returned by socket() or accept(), and 0 if fd
+ * was returned by open(). Return the number of bytes written, or -1
+ * on error. Only use if fd is a blocking fd. */
int write_all(int fd, const char *buf, size_t count, int isSocket) {
size_t written = 0;
int result;
@@ -898,7 +921,7 @@ int write_all(int fd, const char *buf, size_t count, int isSocket) {
return count;
}
-/* Read 'count' bytes from 'fd' to 'buf'. isSocket must be 1 if fd
+/** Read <b>count</b> bytes from <b>fd</b> to <b>buf</b>. isSocket must be 1 if fd
* was returned by socket() or accept(), and 0 if fd was returned by
* open(). Return the number of bytes read, or -1 on error. Only use
* if fd is a blocking fd. */
@@ -918,7 +941,7 @@ int read_all(int fd, char *buf, size_t count, int isSocket) {
return count;
}
-/* Turn 'socket' into a nonblocking socket.
+/** Turn <b>socket</b> into a nonblocking socket.
*/
void set_socket_nonblocking(int socket)
{
@@ -935,7 +958,7 @@ void set_socket_nonblocking(int socket)
* Process control
*/
-/* Minimalist interface to run a void function in the background. On
+/** Minimalist interface to run a void function in the background. On
* unix calls fork, on win32 calls beginthread. Returns -1 on failure.
* func should not return, but rather should call spawn_exit.
*/
@@ -964,7 +987,7 @@ int spawn_func(int (*func)(void *), void *data)
#endif
}
-/* End the current thread/process.
+/** End the current thread/process.
*/
void spawn_exit()
{
@@ -1092,7 +1115,8 @@ tor_socketpair(int family, int type, int protocol, int fd[2])
#endif
}
-/* On Windows, WSAEWOULDBLOCK is not always correct: when you see it,
+/**
+ * On Windows, WSAEWOULDBLOCK is not always correct: when you see it,
* you need to ask the socket for its actual errno. Also, you need to
* get your errors from WSAGetLastError, not errno. (If you supply a
* socket of -1, we check WSAGetLastError, but don't correct
@@ -1113,9 +1137,6 @@ int tor_socket_errno(int sock)
}
#endif
-/* There does not seem to be a strerror equivalent for winsock errors.
- * Naturally, we have to roll our own.
- */
#ifdef MS_WINDOWS
#define E(code, s) { code, (s " [" #code " ]") }
struct { int code; const char *msg; } windows_socket_errors[] = {
@@ -1168,7 +1189,7 @@ struct { int code; const char *msg; } windows_socket_errors[] = {
E(WSANO_DATA, "Valid name, no data record of requested type)"),
/* There are some more error codes whose numeric values are marked
- * 'OS dependent'. They start with WSA_, apparently for the same
+ * <b>OS dependent</b>. They start with WSA_, apparently for the same
* reason that practitioners of some craft traditions deliberately
* introduce imperfections into their baskets and rugs "to allow the
* evil spirits to escape." If we catch them, then our binaries
@@ -1177,6 +1198,9 @@ struct { int code; const char *msg; } windows_socket_errors[] = {
*/
{ -1, NULL },
};
+/** There does not seem to be a strerror equivalent for winsock errors.
+ * Naturally, we have to roll our own.
+ */
const char *tor_socket_strerror(int e)
{
int i;
@@ -1192,7 +1216,7 @@ const char *tor_socket_strerror(int e)
* Filesystem operations.
*/
-/* Return FN_ERROR if filename can't be read, FN_NOENT if it doesn't
+/** Return FN_ERROR if filename can't be read, FN_NOENT if it doesn't
* exist, FN_FILE if it is a regular file, or FN_DIR if it's a
* directory. */
file_status_t file_status(const char *fname)
@@ -1212,7 +1236,7 @@ file_status_t file_status(const char *fname)
return FN_ERROR;
}
-/* Check whether dirname exists and is private. If yes return 0. If
+/** Check whether dirname exists and is private. If yes return 0. If
* it does not exist, and create is set, try to create it and return 0
* on success. Else return -1. */
int check_private_dir(const char *dirname, int create)
@@ -1266,8 +1290,8 @@ int check_private_dir(const char *dirname, int create)
return 0;
}
-/* Create a file named 'fname' with the contents 'str'. Overwrite the
- * previous 'fname' if possible. Return 0 on success, -1 on failure.
+/** Create a file named <b>fname</b> with the contents <b>str</b>. Overwrite the
+ * previous <b>fname</b> if possible. Return 0 on success, -1 on failure.
*
* This function replaces the old file atomically, if possible.
*/
@@ -1307,7 +1331,7 @@ write_str_to_file(const char *fname, const char *str)
return 0;
}
-/* Read the contents of 'filename' into a newly allocated string; return the
+/** Read the contents of <b>filename</b> into a newly allocated string; return the
* string on success or NULL on failure.
*/
char *read_file_to_str(const char *filename) {
@@ -1348,7 +1372,7 @@ char *read_file_to_str(const char *filename) {
return string;
}
-/* read lines from f (no more than maxlen-1 bytes each) until we
+/** read lines from f (no more than maxlen-1 bytes each) until we
* get a non-whitespace line. If it isn't of the form "key value"
* (value can have spaces), return -1.
* Point *key to the first word in line, point *value * to the second.
@@ -1400,7 +1424,7 @@ try_next_line:
return 1;
}
-/* Return true iff 'ip' (in host order) is an IP reserved to localhost,
+/** Return true iff <b>ip</b> (in host order) is an IP reserved to localhost,
* or reserved for local networks by RFC 1918.
*/
int is_internal_IP(uint32_t ip) {
@@ -1415,7 +1439,7 @@ int is_internal_IP(uint32_t ip) {
return 0;
}
-/* Hold the result of our call to 'uname'. */
+/* Hold the result of our call to <b>uname</b>. */
static char uname_result[256];
/* True iff uname_result is set. */
static int uname_result_is_set = 0;
@@ -1450,9 +1474,10 @@ get_uname(void)
static int start_daemon_called = 0;
static int finish_daemon_called = 0;
static int daemon_filedes[2];
-/* Begin running this process as a daemon. The child process will return
- * quickly; the parent process will wait around until the child process calls
- * finish_daemon.
+/** Start putting the process into daemon mode: fork and drop all resources
+ * except standard fds. The parent process never returns, but stays around
+ * until finish_daemon is called. (Note: it's safe to call this more
+ * than once: calls after the first are ignored.)
*/
void start_daemon(char *desired_cwd)
{
@@ -1508,8 +1533,10 @@ void start_daemon(char *desired_cwd)
}
}
-/* Tell the parent process that the child has successfully finished setup,
- * and the daemon is now running.
+/** Finish putting the process into daemon mode: drop standard fds, and tell
+ * the parent process to exit. (Note: it's safe to call this more than once:
+ * calls after the first are ignored. Calls start_daemon first if it hasn't
+ * been called already.)
*/
void finish_daemon(void)
{
@@ -1546,7 +1573,7 @@ void start_daemon(char *cp) {}
void finish_daemon(void) {}
#endif
-/* Write the current process ID, followed by NL, into 'filename',
+/** Write the current process ID, followed by NL, into <b>filename</b>.
*/
void write_pidfile(char *filename) {
#ifndef MS_WINDOWS
@@ -1562,7 +1589,7 @@ void write_pidfile(char *filename) {
#endif
}
-/* Call setuid and setgid to run as 'user':'group'. Return 0 on
+/** Call setuid and setgid to run as <b>user</b>:<b>group</b>. Return 0 on
* success. On failure, log and return -1.
*/
int switch_id(char *user, char *group) {
@@ -1615,7 +1642,7 @@ int switch_id(char *user, char *group) {
return -1;
}
-/* Set *addr to the IP address (in dotted-quad notation) stored in c.
+/** Set *addr to the IP address (in dotted-quad notation) stored in c.
* Return 1 on success, 0 if c is badly formatted. (Like inet_aton(c,addr),
* but works on Windows and Solaris.)
*/
@@ -1638,18 +1665,18 @@ int tor_inet_aton(const char *c, struct in_addr* addr)
#endif
}
-/* Similar behavior to Unix gethostbyname: resolve 'name', and set
+/** Similar behavior to Unix gethostbyname: resolve <b>name</b>, and set
* *addr to the proper IP address, in network byte order. Returns 0
* on success, -1 on failure; 1 on transient failure.
*
* (This function exists because standard windows gethostbyname
* doesn't treat raw IP addresses properly.)
*/
-/* Perhaps eventually this should be replaced by a tor_getaddrinfo or
- * something.
- */
int tor_lookup_hostname(const char *name, uint32_t *addr)
{
+ /* Perhaps eventually this should be replaced by a tor_getaddrinfo or
+ * something.
+ */
struct in_addr iaddr;
struct hostent *ent;
tor_assert(addr);
diff --git a/src/common/util.h b/src/common/util.h
index 465078aac..ed01e6573 100644
--- a/src/common/util.h
+++ b/src/common/util.h
@@ -2,6 +2,11 @@
/* See LICENSE for licensing information */
/* $Id$ */
+/**
+ * \file util.h
+ * \brief Headers for util.c
+ */
+
#ifndef __UTIL_H
#define __UTIL_H
@@ -45,7 +50,7 @@
#define INLINE inline
#endif
-/* Replace assert() with a variant that sends failures to the log before
+/** Replace assert() with a variant that sends failures to the log before
* calling assert() normally.
*/
#ifdef NDEBUG
@@ -60,20 +65,21 @@
} } while (0)
#endif
-/* On windows, you have to call close() on fds returned by open(), and
- * closesocket() on fds returned by socket(). On Unix, everything
- * gets close()'d. We abstract this difference by always using the
- * following macro to close sockets, and always using close() on
+#ifdef MS_WINDOWS
+/** On windows, you have to call close() on fds returned by open(),
+ * and closesocket() on fds returned by socket(). On Unix, everything
+ * gets close()'d. We abstract this difference by always using
+ * tor_close_socket to close sockets, and always using close() on
* files.
*/
-#ifdef MS_WINDOWS
#define tor_close_socket(s) closesocket(s)
#else
#define tor_close_socket(s) close(s)
#endif
-/* legal characters in a filename */
+
/* XXXX This isn't so on windows. */
+/** Legal characters in a filename */
#define CONFIG_LEGAL_FILENAME_CHARACTERS "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789.-_/"
size_t strlcat(char *dst, const char *src, size_t siz);
@@ -131,7 +137,7 @@ void set_uint32(char *cp, uint32_t v);
void hex_encode(const char *from, int fromlen, char *to);
const char *hex_str(const char *from, int fromlen);
-/* Resizeable array. */
+/** Generic resizeable array. */
typedef struct smartlist_t smartlist_t;
smartlist_t *smartlist_create();
@@ -219,17 +225,7 @@ int is_internal_IP(uint32_t ip);
const char *get_uname(void);
-/* Start putting the process into daemon mode: fork and drop all resources
- * except standard fds. The parent process never returns, but stays around
- * until finish_daemon is called. (Note: it's safe to call this more
- * than once: calls after the first are ignored.)
- */
void start_daemon(char *desired_cwd);
-/* Finish putting the process into daemon mode: drop standard fds, and tell
- * the parent process to exit. (Note: it's safe to call this more than once:
- * calls after the first are ignored. Calls start_daemon first if it hasn't
- * been called already.)
- */
void finish_daemon(void);
void write_pidfile(char *filename);
@@ -246,8 +242,12 @@ int tor_lookup_hostname(const char *name, uint32_t *addr);
* the actual errno after a socket operation fails.
*/
#ifdef MS_WINDOWS
+/** Return true if e is EAGAIN or the local equivalent. */
#define ERRNO_IS_EAGAIN(e) ((e) == EAGAIN || (e) == WSAEWOULDBLOCK)
+/** Return true if e is EINPROGRESS or the local equivalent. */
#define ERRNO_IS_EINPROGRESS(e) ((e) == WSAEINPROGRESS)
+/** Return true if e is EINPROGRESS or the local equivalent as returned by
+ * a call to connect(). */
#define ERRNO_IS_CONN_EINPROGRESS(e) ((e) == WSAEINPROGRESS || (e)== WSAEINVAL)
int tor_socket_errno(int sock);
const char *tor_socket_strerror(int e);
diff --git a/src/or/buffers.c b/src/or/buffers.c
index 089b6dc45..880703d10 100644
--- a/src/or/buffers.c
+++ b/src/or/buffers.c
@@ -2,30 +2,31 @@
/* See LICENSE for licensing information */
/* $Id$ */
-/*****
- * buffers.c: Abstractions for buffered IO.
- *****/
+/**
+ * \file buffers.c
+ * \brief Abstractions for buffered IO.
+ **/
#include "or.h"
#define BUFFER_MAGIC 0xB0FFF312u
struct buf_t {
- uint32_t magic; /* Magic cookie for debugging: Must be set to BUFFER_MAGIC */
- char *mem; /* Storage for data in the buffer */
- size_t len; /* Maximum amount of data that 'mem' can hold. */
- size_t datalen; /* Number of bytes currently in 'mem'. */
+ uint32_t magic; /**< Magic cookie for debugging: Must be set to BUFFER_MAGIC */
+ char *mem; /**< Storage for data in the buffer */
+ size_t len; /**< Maximum amount of data that 'mem' can hold. */
+ size_t datalen; /**< Number of bytes currently in 'mem'. */
};
-/* Size, in bytes, for newly allocated buffers. Should be a power of 2. */
+/** Size, in bytes, for newly allocated buffers. Should be a power of 2. */
#define INITIAL_BUF_SIZE (4*1024)
-/* Maximum size, in bytes, for resized buffers. */
+/** Maximum size, in bytes, for resized buffers. */
#define MAX_BUF_SIZE (1024*1024*10)
-/* Size, in bytes, for minimum 'shrink' size for buffers. Buffers may start
+/** Size, in bytes, for minimum 'shrink' size for buffers. Buffers may start
* out smaller than this, but they will never autoshrink to less
* than this size. */
#define MIN_BUF_SHRINK_SIZE (16*1024)
-/* Change a buffer's capacity. new_capacity must be <= buf->datalen. */
+/** Change a buffer's capacity. new_capacity must be \<= buf->datalen. */
static INLINE void buf_resize(buf_t *buf, size_t new_capacity)
{
tor_assert(buf->datalen <= new_capacity);
@@ -34,7 +35,7 @@ static INLINE void buf_resize(buf_t *buf, size_t new_capacity)
buf->len = new_capacity;
}
-/* If the buffer is not large enough to hold "capacity" bytes, resize
+/** If the buffer is not large enough to hold "capacity" bytes, resize
* it so that it can. (The new size will be a power of 2 times the old
* size.)
*/
@@ -58,7 +59,7 @@ static INLINE int buf_ensure_capacity(buf_t *buf, size_t capacity)
return 0;
}
-/* If the buffer is at least 2*MIN_BUF_SHRINK_SIZE bytes in capacity,
+/** If the buffer is at least 2*MIN_BUF_SHRINK_SIZE bytes in capacity,
* and if the buffer is less than 1/4 full, shrink the buffer until
* one of the above no longer holds. (We shrink the buffer by
* dividing by powers of 2.)
@@ -81,7 +82,7 @@ static INLINE void buf_shrink_if_underfull(buf_t *buf) {
buf_resize(buf, new_len);
}
-/* Remove the first 'n' bytes from buf.
+/** Remove the first 'n' bytes from buf.
*/
static INLINE void buf_remove_from_front(buf_t *buf, size_t n) {
tor_assert(buf->datalen >= n);
@@ -90,7 +91,7 @@ static INLINE void buf_remove_from_front(buf_t *buf, size_t n) {
buf_shrink_if_underfull(buf);
}
-/* Find the first instance of the str_len byte string 'sr' on the
+/** Find the first instance of the str_len byte string 'sr' on the
* buf_len byte string 'bufstr'. Strings are not necessary
* NUL-terminated. If none exists, return -1. Otherwise, return index
* of the first character in bufstr _after_ the first instance of str.
@@ -115,7 +116,7 @@ static int find_mem_in_mem(const char *str, int str_len,
return -1;
}
-/* Create and return a new buf with capacity 'size'.
+/** Create and return a new buf with capacity 'size'.
*/
buf_t *buf_new_with_capacity(size_t size) {
buf_t *buf;
@@ -130,39 +131,39 @@ buf_t *buf_new_with_capacity(size_t size) {
return buf;
}
-/* Allocate and return a new buffer with default capacity. */
+/** Allocate and return a new buffer with default capacity. */
buf_t *buf_new()
{
return buf_new_with_capacity(INITIAL_BUF_SIZE);
}
-/* Remove all data from 'buf' */
+/** Remove all data from 'buf' */
void buf_clear(buf_t *buf)
{
buf->datalen = 0;
}
-/* Return the number of bytes stored in 'buf' */
+/** Return the number of bytes stored in 'buf' */
size_t buf_datalen(const buf_t *buf)
{
return buf->datalen;
}
-/* Return the maximum bytes that can be stored in 'buf' before buf
+/** Return the maximum bytes that can be stored in 'buf' before buf
* needs to resize. */
size_t buf_capacity(const buf_t *buf)
{
return buf->len;
}
-/* For testing only: Return a pointer to the raw memory stored in 'buf'.
+/** For testing only: Return a pointer to the raw memory stored in 'buf'.
*/
const char *_buf_peek_raw_buffer(const buf_t *buf)
{
return buf->mem;
}
-/* Release storage held by 'buf'.
+/** Release storage held by 'buf'.
*/
void buf_free(buf_t *buf) {
assert_buf_ok(buf);
@@ -171,7 +172,7 @@ void buf_free(buf_t *buf) {
tor_free(buf);
}
-/* Read from socket s, writing onto end of buf. Read at most
+/** Read from socket s, writing onto end of buf. Read at most
* 'at_most' bytes, resizing the buffer as necessary. If read()
* returns 0, set *reached_eof to 1 and return 0. Return -1 on error;
* else return the number of bytes read. Return 0 if read() would
@@ -212,7 +213,7 @@ int read_to_buf(int s, size_t at_most, buf_t *buf, int *reached_eof) {
}
}
-/* As read_to_buf, but reads from a TLS connection.
+/** As read_to_buf, but reads from a TLS connection.
*/
int read_to_buf_tls(tor_tls *tls, size_t at_most, buf_t *buf) {
int r;
@@ -246,7 +247,7 @@ int read_to_buf_tls(tor_tls *tls, size_t at_most, buf_t *buf) {
return r;
}
-/* Write data from 'buf' to the socket 's'. Write at most
+/** Write data from 'buf' to the socket 's'. Write at most
* *buf_flushlen bytes, and decrement *buf_flushlen by the number of
* bytes actually written. Return the number of bytes written on
* success, -1 on failure. Return 0 if write() would block.
@@ -284,7 +285,7 @@ int flush_buf(int s, buf_t *buf, int *buf_flushlen)
}
}
-/* As flush_buf, but writes data to a TLS connection.
+/** As flush_buf, but writes data to a TLS connection.
*/
int flush_buf_tls(tor_tls *tls, buf_t *buf, int *buf_flushlen)
{
@@ -305,7 +306,7 @@ int flush_buf_tls(tor_tls *tls, buf_t *buf, int *buf_flushlen)
return r;
}
-/* Append string_len bytes from 'string' to the end of 'buf'.
+/** Append string_len bytes from 'string' to the end of 'buf'.
* Return the new length of the buffer on success, -1 on failure.
*/
int write_to_buf(const char *string, int string_len, buf_t *buf) {
@@ -349,17 +350,18 @@ int fetch_from_buf(char *string, size_t string_len, buf_t *buf) {
return buf->datalen;
}
-/* There is a (possibly incomplete) http statement on *buf, of the
- * form "%s\r\n\r\n%s", headers, body. (body may contain nuls.)
+/** There is a (possibly incomplete) http statement on *buf, of the
+ * form "\%s\\r\\n\\r\\n\%s", headers, body. (body may contain nuls.)
* If a) the headers include a Content-Length field and all bytes in
* the body are present, or b) there's no Content-Length field and
* all headers are present, then:
- * strdup headers into *headers_out, and nul-terminate it.
- * memdup body into *body_out, and nul-terminate it.
- * Then remove them from buf, and return 1.
*
- * If headers or body is NULL, discard that part of the buf.
- * If a headers or body doesn't fit in the arg, return -1.
+ * - strdup headers into *headers_out, and nul-terminate it.
+ * - memdup body into *body_out, and nul-terminate it.
+ * - Then remove them from buf, and return 1.
+ *
+ * - If headers or body is NULL, discard that part of the buf.
+ * - If a headers or body doesn't fit in the arg, return -1.
*
* Else, change nothing and return 0.
*/
@@ -425,19 +427,23 @@ int fetch_from_buf_http(buf_t *buf,
return 1;
}
-/* There is a (possibly incomplete) socks handshake on buf, of one
+/** There is a (possibly incomplete) socks handshake on buf, of one
* of the forms
- * socks4: "socksheader username\0"
- * socks4a: "socksheader username\0 destaddr\0"
- * socks5 phase one: "version #methods methods"
- * socks5 phase two: "version command 0 addresstype..."
+ * - socks4: "socksheader username\\0"
+ * - socks4a: "socksheader username\\0 destaddr\\0"
+ * - socks5 phase one: "version #methods methods"
+ * - socks5 phase two: "version command 0 addresstype..."
* If it's a complete and valid handshake, and destaddr fits in
* MAX_SOCKS_ADDR_LEN bytes, then pull the handshake off the buf,
* assign to req, and return 1.
+ *
* If it's invalid or too big, return -1.
+ *
* Else it's not all there yet, leave buf alone and return 0.
+ *
* If you want to specify the socks reply, write it into req->reply
* and set req->replylen, else leave req->replylen alone.
+ *
* If returning 0 or -1, req->address and req->port are undefined.
*/
int fetch_from_buf_socks(buf_t *buf, socks_request_t *req) {
@@ -612,7 +618,7 @@ int fetch_from_buf_socks(buf_t *buf, socks_request_t *req) {
}
}
-/* Log an error and exit if 'buf' is corrupted.
+/** Log an error and exit if 'buf' is corrupted.
*/
void assert_buf_ok(buf_t *buf)
{