From d7b6f0d1cda54fe872145ab6ee20bf5bc131be8d Mon Sep 17 00:00:00 2001 Message-Id: From: Mark Wooding Date: Sun, 16 Sep 2007 20:41:47 +0100 Subject: [PATCH] a bit more doxygen Organization: Straylight/Edgeware From: rjk@greenend.org.uk <> --- lib/addr.c | 4 ++++ lib/asprintf.c | 26 ++++++++++++++++++++++++++ lib/authhash.c | 10 ++++++++++ lib/basen.c | 26 ++++++++++++++++++++++++-- lib/cache.c | 30 ++++++++++++++++++++++++++++++ 5 files changed, 94 insertions(+), 2 deletions(-) diff --git a/lib/addr.c b/lib/addr.c index 153130b..0787663 100644 --- a/lib/addr.c +++ b/lib/addr.c @@ -88,6 +88,10 @@ struct addrinfo *get_address(const struct stringlist *a, return res; } +/** @brief Comparison function for address information + * + * Suitable for qsort(). + */ int addrinfocmp(const struct addrinfo *a, const struct addrinfo *b) { const struct sockaddr_in *ina, *inb; diff --git a/lib/asprintf.c b/lib/asprintf.c index f590c0a..d467874 100644 --- a/lib/asprintf.c +++ b/lib/asprintf.c @@ -33,6 +33,12 @@ #include "vector.h" #include "log.h" +/** @brief vasprintf() workalike without encoding errors + * + * This acts like vasprintf() except that it does not throw an error + * if you use a string outside the current locale's encoding rules, + * and it uses the memory allocation calls from @ref mem.h. + */ int byte_vasprintf(char **ptrp, const char *fmt, va_list ap) { @@ -47,6 +53,12 @@ int byte_vasprintf(char **ptrp, return n; } +/** @brief asprintf() workalike without encoding errors + * + * This acts like asprintf() except that it does not throw an error + * if you use a string outside the current locale's encoding rules, + * and it uses the memory allocation calls from @ref mem.h. + */ int byte_asprintf(char **ptrp, const char *fmt, ...) { @@ -59,6 +71,13 @@ int byte_asprintf(char **ptrp, return n; } +/** @brief asprintf() workalike without encoding errors + * + * This acts like asprintf() except that it does not throw an error if + * you use a string outside the current locale's encoding rules; it + * uses the memory allocation calls from @ref mem.h; and it terminates + * the program on error. + */ int byte_xasprintf(char **ptrp, const char *fmt, ...) { @@ -71,6 +90,13 @@ int byte_xasprintf(char **ptrp, return n; } +/** @brief vasprintf() workalike without encoding errors + * + * This acts like vasprintf() except that it does not throw an error + * if you use a string outside the current locale's encoding rules; it + * uses the memory allocation calls from @ref mem.h; and it terminates + * the program on error. + */ int byte_xvasprintf(char **ptrp, const char *fmt, va_list ap) { diff --git a/lib/authhash.c b/lib/authhash.c index a1012ba..5c66c01 100644 --- a/lib/authhash.c +++ b/lib/authhash.c @@ -30,9 +30,19 @@ #include "authhash.h" #ifndef AUTHHASH +/** @brief Which hash function to use */ # define AUTHHASH GCRY_MD_SHA1 #endif +/** @brief Perform the authorization hash function + * @param challenge Pointer to challange + * @param nchallenge Size of challenge + * @param password Password + * + * Computes H(challenge|password) and returns it as a newly allocated hex + * string. Currently the hash function is SHA-1, but this may be changed in + * future versions; see @ref AUTHHASH. + */ const char *authhash(const void *challenge, size_t nchallenge, const char *password) { gcrypt_hash_handle h; diff --git a/lib/basen.c b/lib/basen.c index 69ab273..362ab58 100644 --- a/lib/basen.c +++ b/lib/basen.c @@ -25,7 +25,11 @@ #include "basen.h" -/* test whether v is 0 */ +/** @brief Test whether v is 0 + * @param v Pointer to bigendian bignum + * @param nwords Length of bignum + * @return !v + */ static int zero(const unsigned long *v, int nwords) { int n; @@ -34,7 +38,14 @@ static int zero(const unsigned long *v, int nwords) { return n == nwords; } -/* divide v by m returning the remainder */ +/** @brief Divide v by m returning the remainder. + * @param v Pointer to bigendian bignum + * @param nwords Length of bignum + * @param m Divisor (must not be 0) + * @return Remainder + * + * The quotient is stored in @p v. + */ static unsigned divide(unsigned long *v, int nwords, unsigned long m) { unsigned long r = 0, a, b; int n; @@ -54,6 +65,17 @@ static unsigned divide(unsigned long *v, int nwords, unsigned long m) { return r; } +/** @brief Convert v to a chosen base + * @param v Pointer to bigendian bignum + * @param nwords Length of bignum + * @param buffer Output buffer + * @param bufsize Size of output buffer + * @param base Number base (2..62) + * @return 0 on success, -1 if the buffer is too small + * + * Converts @p v to a string in the given base using decimal digits, lower case + * letter sand upper case letters as digits. + */ int basen(unsigned long *v, int nwords, char buffer[], diff --git a/lib/cache.c b/lib/cache.c index c6624e8..368ec37 100644 --- a/lib/cache.c +++ b/lib/cache.c @@ -28,18 +28,31 @@ #include "log.h" #include "cache.h" +/** @brief The global cache */ static hash *h; +/** @brief One cache entry */ struct cache_entry { + /** @brief What type of object this is */ const struct cache_type *type; + + /** @brief Pointer to object value */ const void *value; + + /** @brief Time that object was inserted into cache */ time_t birth; }; +/** @brief Return true if object @p c has expired */ static int expired(const struct cache_entry *c, time_t now) { return now - c->birth > c->type->lifetime; } +/** @brief Insert an object into the cache + * @param type Pointer to object type + * @param key Unique key + * @param value Pointer to value + */ void cache_put(const struct cache_type *type, const char *key, const void *value) { struct cache_entry *c; @@ -53,6 +66,11 @@ void cache_put(const struct cache_type *type, hash_add(h, key, c, HASH_INSERT_OR_REPLACE); } +/** @brief Look up an object in the cache + * @param type Pointer to object type + * @param key Unique key + * @return Pointer to object value or NULL if not found + */ const void *cache_get(const struct cache_type *type, const char *key) { const struct cache_entry *c; @@ -74,6 +92,9 @@ static int expiry_callback(const char *key, void *value, void *u) { return 0; } +/** @brief Expire the cache + * + * Called from time to time to expire cache entries. */ void cache_expire(void) { time_t now; @@ -92,11 +113,20 @@ static int clean_callback(const char *key, void *value, void *u) { return 0; } +/** @brief Clean the cache + * @param type Pointer to type to clean + * + * Removes all entries of type @p type from the cache. + */ void cache_clean(const struct cache_type *type) { if(h) hash_foreach(h, clean_callback, (void *)type); } +/** @brief Report cache size + * + * Returns the number of objects in the cache + */ size_t cache_count(void) { return h ? hash_count(h) : 0; } -- [mdw]