From: Richard Kettlewell Date: Fri, 21 Sep 2007 23:29:09 +0000 (+0100) Subject: doxygen X-Git-Tag: debian-1_5_99dev8~243^2~42 X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~mdw/git/disorder/commitdiff_plain/14ad73b94d56fb8558eabfef431c34e12de00478?ds=inline doxygen --- diff --git a/lib/addr.c b/lib/addr.c index 0787663..579fd0f 100644 --- a/lib/addr.c +++ b/lib/addr.c @@ -17,6 +17,7 @@ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 * USA */ +/** @file lib/addr.c Socket address support */ #include #include "types.h" diff --git a/lib/asprintf.c b/lib/asprintf.c index d467874..304304a 100644 --- a/lib/asprintf.c +++ b/lib/asprintf.c @@ -17,6 +17,7 @@ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 * USA */ +/** @file lib/asprintf.c @brief printf() workalikes */ #include #include "types.h" diff --git a/lib/authhash.c b/lib/authhash.c index 5c66c01..b97204d 100644 --- a/lib/authhash.c +++ b/lib/authhash.c @@ -17,6 +17,7 @@ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 * USA */ +/** @file lib/authhash.c @brief The authorization hash */ #include #include "types.h" diff --git a/lib/basen.c b/lib/basen.c index 362ab58..c5644b4 100644 --- a/lib/basen.c +++ b/lib/basen.c @@ -17,6 +17,12 @@ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 * USA */ +/** @file lib/basen.c @brief Arbitrary base conversion + * + * The functions in this file handle arbitrary-size non-negative integers, + * represented as a bigendian (MSW first) sequence of @c unsigned @c long + * words. The words themselves use the native byte order. + */ #include #include "types.h" diff --git a/lib/cache.c b/lib/cache.c index 368ec37..bc6bc81 100644 --- a/lib/cache.c +++ b/lib/cache.c @@ -17,6 +17,7 @@ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 * USA */ +/** @file lib/cache.c @brief Object caching */ #include #include "types.h" diff --git a/lib/charset.c b/lib/charset.c index f101ec2..2a38fbf 100644 --- a/lib/charset.c +++ b/lib/charset.c @@ -17,6 +17,7 @@ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 * USA */ +/** @file lib/charset.c @brief Character set conversion */ #include #include "types.h" @@ -33,6 +34,13 @@ #include "utf8.h" #include "vector.h" +/** @brief Low-level converstion routine + * @param from Source encoding + * @param to Destination encoding + * @param ptr First byte to convert + * @param n Number of bytes to convert + * @return Converted text, 0-terminated; or NULL on error. + */ static void *convert(const char *from, const char *to, const void *ptr, size_t n) { iconv_t i; @@ -61,8 +69,14 @@ static void *convert(const char *from, const char *to, return buf; } -/* not everybody's iconv supports UCS-4, and it's inconvenient to have to know - * our endianness, and it's easy to convert it ourselves, so we do */ +/** @brief Convert UTF-8 to UCS-4 + * @param mb Pointer to 0-terminated UTF-8 string + * @return Pointer to 0-terminated UCS-4 string + * + * Not everybody's iconv supports UCS-4, and it's inconvenient to have to know + * our endianness, and it's easy to convert it ourselves, so we do. See also + * @ref ucs42utf8(). + */ uint32_t *utf82ucs4(const char *mb) { struct dynstr_ucs4 d; uint32_t c; @@ -77,6 +91,12 @@ uint32_t *utf82ucs4(const char *mb) { return d.vec; } +/** @brief Convert UCS-4 to UTF-8 + * @param u Pointer to 0-terminated UCS-4 string + * @return Pointer to 0-terminated UTF-8 string + * + * See @ref utf82ucs4(). + */ char *ucs42utf8(const uint32_t *u) { struct dynstr d; uint32_t c; @@ -106,23 +126,28 @@ char *ucs42utf8(const uint32_t *u) { return d.vec; } +/** @brief Convert from the local multibyte encoding to UTF-8 */ char *mb2utf8(const char *mb) { return convert(nl_langinfo(CODESET), "UTF-8", mb, strlen(mb) + 1); } +/** @brief Convert from UTF-8 to the local multibyte encoding */ char *utf82mb(const char *utf8) { return convert("UTF-8", nl_langinfo(CODESET), utf8, strlen(utf8) + 1); } +/** @brief Convert from encoding @p from to UTF-8 */ char *any2utf8(const char *from, const char *any) { return convert(from, "UTF-8", any, strlen(any) + 1); } +/** @brief Convert from encoding @p from to the local multibyte encoding */ char *any2mb(const char *from, const char *any) { if(from) return convert(from, nl_langinfo(CODESET), any, strlen(any) + 1); else return xstrdup(any); } +/** @brief Convert from encoding @p from to encoding @p to */ char *any2any(const char *from, const char *to, const char *any) { @@ -130,6 +155,10 @@ char *any2any(const char *from, else return xstrdup(any); } +/** @brief strlen workalike for UCS-4 strings + * + * We don't rely on the local @c wchar_t being UCS-4. + */ int ucs4cmp(const uint32_t *a, const uint32_t *b) { while(*a && *b && *a == *b) ++a, ++b; if(*a > *b) return 1; diff --git a/lib/defs.c b/lib/defs.c index 7a11ebd..494597e 100644 --- a/lib/defs.c +++ b/lib/defs.c @@ -17,6 +17,11 @@ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 * USA */ +/** @file lib/defs.c @brief Definitions chosen by configure + * + * The binary directories are included so that they can be appended to the path + * (see fix_path()), not so that the path can be ignored. + */ #include #include "types.h" @@ -24,13 +29,28 @@ #include "defs.h" #include "definitions.h" +/** @brief Software version number */ const char disorder_version_string[] = VERSION; + +/** @brief Package library directory */ const char pkglibdir[] = PKGLIBDIR; + +/** @brief Package configuration directory */ const char pkgconfdir[] = PKGCONFDIR; + +/** @brief Package variable state directory */ const char pkgstatedir[] = PKGSTATEDIR; + +/** @brief Package fixed data directory */ const char pkgdatadir[] = PKGDATADIR; + +/** @brief Binary directory */ const char bindir[] = BINDIR; + +/** @brief System binary directory */ const char sbindir[] = SBINDIR; + +/** @brief Fink binary directory */ const char finkbindir[] = FINKBINDIR; /* diff --git a/lib/log-impl.h b/lib/log-impl.h index 51577df..b0147a6 100644 --- a/lib/log-impl.h +++ b/lib/log-impl.h @@ -17,7 +17,13 @@ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 * USA */ +/** @file lib/log-impl.h @brief Errors and logging */ +/** @brief Log an error and quit + * + * If @c ${DISORDER_FATAL_ABORT} is defined (as anything) then the process + * is aborted, so you can get a backtrace. + */ void disorder_fatal(int errno_value, const char *msg, ...) { va_list ap; @@ -28,6 +34,7 @@ void disorder_fatal(int errno_value, const char *msg, ...) { exitfn(EXIT_FAILURE); } +/** @brief Log an error */ void disorder_error(int errno_value, const char *msg, ...) { va_list ap; @@ -36,6 +43,7 @@ void disorder_error(int errno_value, const char *msg, ...) { va_end(ap); } +/** @brief Log an informational message */ void disorder_info(const char *msg, ...) { va_list ap; diff --git a/lib/log.c b/lib/log.c index 1705642..0ebda63 100644 --- a/lib/log.c +++ b/lib/log.c @@ -17,6 +17,20 @@ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 * USA */ +/** @file lib/log.c @brief Errors and logging + * + * All messages are initially emitted by one of the four functions below. + * debug() is generally invoked via D() so that mostly you just do a test + * rather than a complete subroutine call. + * + * Messages are dispatched via @ref log_default. This defaults to @ref + * log_stderr. daemonize() will turn off @ref log_stderr and use @ref + * log_syslog instead. + * + * fatal() will call exitfn() with a nonzero status. The default value is + * exit(), but it should be set to _exit() anywhere but the 'main line' of the + * program, to guarantee that exit() gets called at most once. + */ #define NO_MEMORY_ALLOCATION /* because the memory allocation functions report errors */ @@ -34,22 +48,44 @@ #include "disorder.h" #include "printf.h" +/** @brief Definition of a log output */ struct log_output { + /** @brief Function to call */ void (*fn)(int pri, const char *msg, void *user); + /** @brief User data */ void *user; }; +/** @brief Function to call on a fatal error + * + * This is normally @c exit() but in the presence of @c fork() it + * sometimes gets set to @c _exit(). */ void (*exitfn)(int) attribute((noreturn)) = exit; + +/** @brief Debug flag */ int debugging; + +/** @brief Program name */ const char *progname; + +/** @brief Filename for debug messages */ const char *debug_filename; + +/** @brief Line number for debug messages */ int debug_lineno; + +/** @brief Pointer to chosen log output structure */ struct log_output *log_default = &log_stderr; +/** @brief Filename to debug for */ static const char *debug_only; -/* we might be receiving things in any old encoding, or binary rubbish in no - * encoding at all, so escape anything we don't like the look of */ +/** @brief Construct log line, encoding special characters + * + * We might be receiving things in any old encoding, or binary rubbish + * in no encoding at all, so escape anything we don't like the look + * of. We limit the log message to a kilobyte. + */ static void format(char buffer[], size_t bufsize, const char *fmt, va_list ap) { char t[1024]; const char *p; @@ -74,7 +110,9 @@ static void format(char buffer[], size_t bufsize, const char *fmt, va_list ap) { buffer[n] = 0; } -/* log to a file */ +/** @brief Log to a file + * @param user The @c FILE @c * to log to or NULL for @c stderr + */ static void logfp(int pri, const char *msg, void *user) { struct timeval tv; FILE *fp = user ? user : stderr; @@ -106,7 +144,7 @@ static void logfp(int pri, const char *msg, void *user) { fputc('\n', fp); } -/* log to syslog */ +/** @brief Log to syslog */ static void logsyslog(int pri, const char *msg, void attribute((unused)) *user) { if(pri < LOG_DEBUG) @@ -115,10 +153,13 @@ static void logsyslog(int pri, const char *msg, syslog(pri, "%s:%d: %s", debug_filename, debug_lineno, msg); } +/** @brief Log output that writes to @c stderr */ struct log_output log_stderr = { logfp, 0 }; + +/** @brief Log output that sends to syslog */ struct log_output log_syslog = { logsyslog, 0 }; -/* log to all log outputs */ +/** @brief Format and log a message */ static void vlogger(int pri, const char *fmt, va_list ap) { char buffer[1024]; @@ -126,7 +167,7 @@ static void vlogger(int pri, const char *fmt, va_list ap) { log_default->fn(pri, buffer, log_default->user); } -/* wrapper for vlogger */ +/** @brief Format and log a message */ static void logger(int pri, const char *fmt, ...) { va_list ap; @@ -135,7 +176,9 @@ static void logger(int pri, const char *fmt, ...) { va_end(ap); } -/* internals of fatal/error/info */ +/** @brief Format and log a message + * @param errno_value Errno value to include as a string, or 0 + */ void elog(int pri, int errno_value, const char *fmt, va_list ap) { char buffer[1024]; @@ -156,6 +199,7 @@ void elog(int pri, int errno_value, const char *fmt, va_list ap) { /* shared implementation of vararg functions */ #include "log-impl.h" +/** @brief Log a debug message */ void debug(const char *msg, ...) { va_list ap; @@ -164,6 +208,7 @@ void debug(const char *msg, ...) { va_end(ap); } +/** @brief Set the program name from @c argc */ void set_progname(char **argv) { if((progname = strrchr(argv[0], '/'))) ++progname; diff --git a/lib/log.h b/lib/log.h index f23dcd7..85a6e05 100644 --- a/lib/log.h +++ b/lib/log.h @@ -21,27 +21,13 @@ #ifndef LOG_H #define LOG_H -/* All messages are initially emitted by one of the four functions below. - * debug() is generally invoked via D() so that mostly you just do a test - * rather than a complete subroutine call. - * - * Messages are dispatched via log_default. This defaults to log_stderr. - * daemonize() will turn off log_stderr and use log_syslog instead. - * - * fatal() will call exitfn() with a nonzero status. The default value is - * exit(), but it should be set to _exit() anywhere but the 'main line' of the - * program, to guarantee that exit() gets called at most once. - */ - #include struct log_output; void set_progname(char **argv); -/* set progname from argv[0] */ void elog(int pri, int errno_value, const char *fmt, va_list ap); -/* internals of fatal/error/info/debug */ void fatal(int errno_value, const char *msg, ...) attribute((noreturn)) attribute((format (printf, 2, 3)));