Add doxygen markup for util and buffers

/* 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"

#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.)

 */

  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.)

 */

  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.)

 */

  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.)

 */

  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;

  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)

  *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.

 */

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;

  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));

  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) {

  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.

 */

  }

}

/* 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.

 */

  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;

  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) {

    }

}

/* 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;

  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;

  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) {

    }

}

/* 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) {

    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)

  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)

{

  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)

{

  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)

{

    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)

{

  }

}

/*****

 * 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;

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)

{

  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)

{

  }

}

/* 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)

  }

}

/* 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.

 */

  }

}

/* 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

  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;

  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;

  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;

 *   ...

 *

 *   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),

  }

}

/* 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;

 *       iter = strmap_iter_next(iter);

 *    }

 * }

 * \endcode

 *

 */

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)

  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)

{

  *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*))

{

 *    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) {

  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')

  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) {

  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) {

  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

  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)

  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;

  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;

  --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) {

 *   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;

  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. */

  return count;

}

/* Turn 'socket' into a nonblocking socket.

/** Turn <b>socket</b> into a nonblocking socket.

 */

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.

 */

#endif

}

/* End the current thread/process.

/** End the current thread/process.

 */

void spawn_exit()

{

#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

}

#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[] = {

  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

   */

  { -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;

 *    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)

    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)

  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.

 */

  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) {

  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"