aniani/elinks
1
0
Fork 0
mirror of https://github.com/rkd77/elinks.git synced 2024-12-04 14:46:47 -05:00
Code

Doxygenate src/util/

Browse Source
This commit is contained in:
Kalle Olavi Niemitalo 2007-07-27 12:35:13 +03:00 committed by Kalle Olavi Niemitalo
parent 364485f6bb
commit e530fbe8e2
34 changed files with 529 additions and 437 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
src/osdep/os2/os2.c
View File

@ -436,9 +436,9 @@ resize_window(int x, int y, int old_width, int old_height)
#if 0
unsigned char cmdline[16];
sprintf(cmdline, "mode ");
snprint(cmdline + 5, 5, x);
ulongcat(cmdline + 5, NULL, x, 5, 0);
strcat(cmdline, ",");
snprint(cmdline + strlen(cmdline), 5, y);
ulongcat(cmdline + strlen(cmdline), NULL, y, 5, 0);
#endif
return 0;
}

12
src/util/base64.c
View File

@ -1,4 +1,5 @@
/* Base64 encode/decode implementation. */
/** Base64 encode/decode implementation.
* @file */
#ifdef HAVE_CONFIG_H
#include "config.h"
@ -75,8 +76,13 @@ base64_decode(register unsigned char *in)
return base64_decode_bin(in, strlen(in), NULL);
}
/* base64_decode: @in string to decode
* returns the string decoded (must be freed by the caller) */
/** Decode a Base64 string.
* @param in Input Base64 string
* @param inlen Length of @a in, in bytes
* @param[out] outlen Length of decoded string
*
* @returns the string decoded (must be freed by the caller)
* or NULL if an error occurred (syntax error or out of memory) */
unsigned char *
base64_decode_bin(register unsigned char *in, int inlen, int *outlen)
{

19
src/util/bitfield.h
View File

@ -7,9 +7,10 @@
/* Bitfield operations: */
/** A vector of bits. The size is fixed at initialization time. */
struct bitfield {
unsigned int bitsize; /* Number of bits in the bitfield. */
unsigned char bits[1]; /* Strawberry bitfields forever. */
unsigned int bitsize; /**< Number of bits in the bitfield. */
unsigned char bits[1]; /**< Strawberry bitfields forever. */
};
#define foreach_bitfield_set(bit, bitfield) \
@ -31,7 +32,7 @@ struct bitfield {
/* +7 to round up to nearest byte. */
#define get_bitfield_byte_size(bits) ((size_t) (((bits) + 7) / 8))
/* Allocate a bitfield containing @bits number of bits. */
/** Allocate a bitfield containing @a bits number of bits. */
static inline struct bitfield *
init_bitfield(size_t bits)
{
@ -44,7 +45,7 @@ init_bitfield(size_t bits)
return bitfield;
}
/* Update @bitfield with the @size bytes from the @bits string in @bits. */
/** Update @a bitfield with the @a bytesize bytes from the bit string in @a bits. */
static inline void
copy_bitfield(struct bitfield *bitfield,
const unsigned char *bits, unsigned int bytesize)
@ -54,7 +55,7 @@ copy_bitfield(struct bitfield *bitfield,
memcpy(bitfield->bits, bits, bytesize);
}
/* Test whether @bit is set in the bitfield. */
/** Test whether @a bit is set in the @a bitfield. */
static inline int
test_bitfield_bit(struct bitfield *bitfield, unsigned int bit)
{
@ -69,7 +70,7 @@ test_bitfield_bit(struct bitfield *bitfield, unsigned int bit)
return !!(bitfield->bits[byte_offset] & bit_offset);
}
/* Set @bit in the bitfield. */
/** Set @a bit in the @a bitfield. */
static inline void
set_bitfield_bit(struct bitfield *bitfield, unsigned int bit)
{
@ -84,7 +85,7 @@ set_bitfield_bit(struct bitfield *bitfield, unsigned int bit)
bitfield->bits[byte_offset] |= bit_offset;
}
/* Unset @bit in the bitfield. */
/** Unset @a bit in the @a bitfield. */
static inline void
clear_bitfield_bit(struct bitfield *bitfield, unsigned int bit)
{
@ -99,6 +100,7 @@ clear_bitfield_bit(struct bitfield *bitfield, unsigned int bit)
bitfield->bits[byte_offset] &= ~bit_offset;
}
/** Count the set bits in @a bitfield. */
static inline unsigned int
get_bitfield_set_count(struct bitfield *bitfield)
{
@ -110,6 +112,7 @@ get_bitfield_set_count(struct bitfield *bitfield)
return count;
}
/** Count the unset bits in @a bitfield. */
static inline unsigned int
get_bitfield_cleared_count(struct bitfield *bitfield)
{
@ -121,6 +124,7 @@ get_bitfield_cleared_count(struct bitfield *bitfield)
return count;
}
/** Check whether all bits of @a bitfield are set. */
static inline unsigned int
bitfield_is_set(struct bitfield *bitfield)
{
@ -132,6 +136,7 @@ bitfield_is_set(struct bitfield *bitfield)
return 1;
}
/** Check whether all bits of @a bitfield are unset. */
static inline unsigned int
bitfield_is_cleared(struct bitfield *bitfield)
{

4
src/util/box.h
View File

@ -1,6 +1,7 @@
#ifndef EL__UTIL_BOX_H
#define EL__UTIL_BOX_H
/** A rectangular part of a drawing surface, such as the screen. */
struct box {
int x;
int y;
@ -28,7 +29,8 @@ col_is_in_box(struct box *box, int x)
return (x >= box->x && x < box->x + box->width);
}
/* Mainly intended for use with double-width characters. */
/** Check whether a span of columns is in @a box.
* Mainly intended for use with double-width characters. */
static inline int
colspan_is_in_box(struct box *box, int x, int span)
{

5
src/util/color.c
View File

@ -1,4 +1,5 @@
/* Color parser */
/** Color parser
* @file */
#ifdef HAVE_CONFIG_H
#include "config.h"
@ -40,7 +41,7 @@ colors_list_reset(void)
internal_pointer = color_specs;
}
/* Returns a pointer to a struct that contains
/** Returns a pointer to a struct that contains
* current key and data pointers and increment
* internal pointer.
* It returns NULL when key is NULL. */

16
src/util/color.h
View File

@ -10,21 +10,23 @@ struct color_pair {
#define INIT_COLOR_PAIR(bg, fg) { bg, fg }
/* Decode the color string. */
/* The color string can either contain '#FF0044' style declarations or
/** Decode the color string.
* The color string can either contain '@#FF0044' style declarations or
* color names. */
int decode_color(unsigned char *str, int slen, color_T *color);
/* Returns a string containing the color info. If no ``English'' name can be
* found the hex color (#rrggbb) is returned in the given buffer. */
/** Returns a string containing the color info. If no 'English' name can be
* found the hex color (@#rrggbb) is returned in the given buffer. */
const unsigned char *get_color_string(color_T color, unsigned char hexcolor[8]);
/* Translate rgb color to string in #rrggbb format. str should be a pointer to
* a 8 bytes memory space. */
/** Translate rgb color to string in @#rrggbb format.
* @a str should be a pointer to an 8 bytes memory space. */
void color_to_string(color_T color, unsigned char str[8]);
/* Fastfind lookup management. */
/** @name Fastfind lookup management.
* @{ */
void init_colors_lookup(void);
void free_colors_lookup(void);
/** @} */
#endif

40
src/util/conv.c
View File

@ -1,4 +1,5 @@
/* Conversion functions */
/** Conversion functions
* @file */
#ifdef HAVE_CONFIG_H
#include "config.h"
@ -22,30 +23,33 @@
/* This function takes string @s and stores the @number (of a result width
* @width) in string format there, starting at position [*@slen]. If the number
* would take more space than @width, it is truncated and only the _last_
* digits of it are inserted to the string. If the number takes less space than
* @width, it is padded by @fillchar from left.
* @base defined which base should be used (10, 16, 8, 2, ...)
* @upper selects either hexa uppercased chars or lowercased chars.
/** This function takes string @a s and stores the @a number (of a
* result width @a width) in string format there, starting at position
* [*@a slen]. If the number would take more space than @a width, it
* is truncated and only the _last_ digits of it are inserted to the
* string. If the number takes less space than @a width, it is padded
* by @a fillchar from left.
* @a base defined which base should be used (10, 16, 8, 2, ...)
* @a upper selects either hexa uppercased chars or lowercased chars.
*
* A NUL char is always added at the end of the string. @s must point to a
* sufficiently large memory space, at least *@slen + @width + 1.
* A NUL char is always added at the end of the string. @a s must point
* to a sufficiently large memory space, at least *@a slen + @a width + 1.
*
* Examples:
*
* @code
* elinks_ulongcat(s, NULL, 12345, 4, 0, 10, 0) : s = "2345"
* elinks_ulongcat(s, NULL, 255, 4, '*', 16, 1) : s = "**FF"
* elinks_ulongcat(s, NULL, 123, 5, '0', 10, 0) : s = "00123"
* @endcode
*
* Note that this function exists to provide a fast and efficient, however
* still quite powerful alternative to sprintf(). It is optimized for speed and
* is *MUCH* faster than sprintf(). If you can use it, use it ;-). But do not
* get too enthusiastic, do not use it in cases where it would break i18n.
*/
/* The function returns 0 if OK or width needed for the whole number to fit
* there, if it had to be truncated. A negative value signs an error. */
*
* @returns 0 if OK or width needed for the whole number to fit there,
* if it had to be truncated. A negative value signs an error. */
int inline
elinks_ulongcat(unsigned char *s, unsigned int *slen,
unsigned long number, unsigned int width,
@ -103,7 +107,7 @@ elinks_ulongcat(unsigned char *s, unsigned int *slen,
return ret;
}
/* Similar to elinks_ulongcat() but for long number. */
/** Similar to elinks_ulongcat() but for @c long number. */
int inline
elinks_longcat(unsigned char *s, unsigned int *slen,
long number, unsigned int width,
@ -469,8 +473,8 @@ month2num(const unsigned char *str)
}
}
/* This function drops control chars, nbsp char and limit the number of consecutive
* space chars to one. It modifies its argument. */
/** This function drops control chars, nbsp char and limit the number
* of consecutive space chars to one. It modifies its argument. */
void
clr_spaces(unsigned char *str)
{
@ -492,7 +496,7 @@ clr_spaces(unsigned char *str)
*dest = '\0';
}
/* Replace invalid chars in @title with ' ' and trim all starting/ending
/** Replace invalid chars in @a title with ' ' and trim all starting/ending
* spaces. */
void
sanitize_title(unsigned char *title)
@ -508,7 +512,7 @@ sanitize_title(unsigned char *title)
trim_chars(title, ' ', NULL);
}
/* Returns 0 if @url contains invalid chars, 1 if ok.
/** Returns 0 if @a url contains invalid chars, 1 if ok.
* It trims starting/ending spaces. */
int
sanitize_url(unsigned char *url)

74
src/util/conv.h
View File

@ -17,23 +17,23 @@ is_safe_in_shell(unsigned char c)
long strtolx(unsigned char *, unsigned char **);
/* Convert a decimal number to hexadecimal (lowercase) (0 <= a <= 15). */
/** Convert a decimal number to hexadecimal (lowercase) (0 <= @a a <= 15). */
static inline unsigned char
hx(register int a)
{
return a >= 10 ? a + 'a' - 10 : a + '0';
}
/* Convert a decimal number to hexadecimal (uppercase) (0 <= a <= 15). */
/** Convert a decimal number to hexadecimal (uppercase) (0 <= @a a <= 15). */
static inline unsigned char
Hx(register int a)
{
return a >= 10 ? a + 'A' - 10 : a + '0';
}
/* Convert an hexadecimal char ([0-9][a-z][A-Z]) to
* its decimal value (0 <= result <= 15)
* returns -1 if parameter is not an hexadecimal char. */
/** Convert an hexadecimal char ([0-9][a-z][A-Z]) to
* its decimal value (0 <= result <= 15).
* Returns -1 if parameter is not an hexadecimal char. */
static inline int
unhx(register unsigned char a)
{
@ -51,21 +51,23 @@ struct string *add_duration_to_string(struct string *string, long seconds);
struct string *add_timeval_to_string(struct string *string, timeval_T *timeval);
#ifdef HAVE_STRFTIME
/* Uses strftime() to add @fmt time format to @string. If @time is NULL
* time(NULL) will be used. */
/** Uses strftime() to format @a time according to @a format and adds
* the result to @a string. If @a time is NULL, time(NULL) will be
* used. */
struct string *add_date_to_string(struct string *string,
const unsigned char *format,
const time_t *time);
#endif
/* Encoders: */
/* They encode and add to the string. This way we don't need to first allocate
/** @name Encoders:
* They encode and add to the string. This way we don't need to first allocate
* and encode a temporary string, add it and then free it. Can be used as
* backends for encoder. */
* backends for encoder.
* @{ */
/* A simple generic encoder. Should maybe take @replaceable as a string so we
* could also use it for adding shell safe strings. */
/** A simple generic encoder. Should maybe take @a replaceable as a
* string so we could also use it for adding shell safe strings. */
struct string *
add_string_replace(struct string *string, unsigned char *src, int len,
unsigned char replaceable, unsigned char replacement);
@ -73,36 +75,37 @@ add_string_replace(struct string *string, unsigned char *src, int len,
#define add_optname_to_string(str, src, len) \
add_string_replace(str, src, len, '.', '*')
/* Maybe a bad name but it is actually the real name, but you may also think of
* it as adding the decoded option name. */
/** Maybe a bad name but it is actually the real name, but you may
* also think of it as adding the decoded option name. */
#define add_real_optname_to_string(str, src, len) \
add_string_replace(str, src, len, '*', '.')
/* Convert reserved chars to html &#xx;. This function copies bytes
/** Convert reserved chars to html @&@#xx;. This function copies bytes
* 0x80...0xFF unchanged, so the caller should ensure that the
* resulting HTML will be parsed with the same charset as the original
* string. (This function cannot use the &#160; syntax for non-ASCII,
* string. (This function cannot use the @&@#160; syntax for non-ASCII,
* because HTML wants Unicode numbers there and this function does not
* know the charset of the input data.) */
struct string *add_html_to_string(struct string *string, const unsigned char *html, int htmllen);
/* Convert reserved or non-ASCII chars to html &#xx;. The resulting
/** Convert reserved or non-ASCII chars to html @&@#xx;. The resulting
* string can be correctly parsed in any charset where bytes
* 0x20...0x7E match ASCII. */
struct string *add_cp_html_to_string(struct string *string, int src_codepage,
const unsigned char *html, int htmllen);
/* Escapes \ and " with a \ */
/** Escapes @\ and " with a @\ */
struct string *add_quoted_to_string(struct string *string, const unsigned char *q, int qlen);
/* Adds ', |len| bytes of |src| with all single-quotes converted to '\'',
* and ' to |string|. */
/** Adds ', @a len bytes of @a src with all single-quotes converted to '\'',
* and ' to @a string. */
struct string *add_shell_quoted_to_string(struct string *string,
unsigned char *src, int len);
/* Escapes non shell safe chars with '_'. */
struct string *add_shell_safe_to_string(struct string *string, unsigned char *cmd, int cmdlen);
/** @} */
/* These are fast functions to convert integers to string, or to hexadecimal string. */
@ -115,7 +118,7 @@ int elinks_longcat(unsigned char *s, unsigned int *slen, long number,
unsigned int upper);
/* Type casting is enforced, to shorten calls. --Zas */
/* unsigned long to decimal string */
/** unsigned long to decimal string */
#define ulongcat(s, slen, number, width, fillchar) \
elinks_ulongcat((unsigned char *) (s), \
(unsigned int *) (slen), \
@ -125,7 +128,7 @@ int elinks_longcat(unsigned char *s, unsigned int *slen, long number,
(unsigned int) 10, \
(unsigned int) 0)
/* signed long to decimal string */
/** signed long to decimal string */
#define longcat(s, slen, number, width, fillchar) \
elinks_longcat((unsigned char *) (s), \
(unsigned int *) (slen), \
@ -135,7 +138,7 @@ int elinks_longcat(unsigned char *s, unsigned int *slen, long number,
(unsigned int) 10, \
(unsigned int) 0)
/* unsigned long to hexadecimal string */
/** unsigned long to hexadecimal string */
#define ulonghexcat(s, slen, number, width, fillchar, upper) \
elinks_ulongcat((unsigned char *) (s), \
(unsigned int *) (slen), \
@ -146,19 +149,15 @@ int elinks_longcat(unsigned char *s, unsigned int *slen, long number,
(unsigned int) (upper))
/* XXX: Compatibility only. Remove these at some time. --Zas */
#define snprint(str, len, num) ulongcat(str, NULL, num, len, 0);
#define snzprint(str, len, num) longcat(str, NULL, num, len, 0);
/* Return 0 if starting with jan, 11 for dec, -1 for failure.
* @month must be a lowercased string. */
/** Return 0 if starting with jan, 11 for dec, -1 for failure.
* @a month must be a lowercased string. */
int month2num(const unsigned char *month);
#include <string.h>
/* Trim starting and ending chars equal to @c in string @s.
* If @len != NULL, it stores new string length in pointed integer.
* It returns @s for convenience. */
/** Trim starting and ending chars equal to @a c in string @a s.
* If @a len != NULL, it stores new string length in pointed integer.
* It returns @a s for convenience. */
static inline unsigned char *
trim_chars(unsigned char *s, unsigned char c, int *len)
{
@ -174,7 +173,8 @@ trim_chars(unsigned char *s, unsigned char c, int *len)
return s;
}
/* Convert uppercase letters in @string with the given @length to lowercase. */
/** Convert uppercase letters in @a string with the given @a length to
* lowercase. */
static inline void
convert_to_lowercase(unsigned char *string, int length)
{
@ -183,15 +183,15 @@ convert_to_lowercase(unsigned char *string, int length)
string[length] = tolower(string[length]);
}
/* This function drops control chars, nbsp char and limit the number of consecutive
* space chars to one. It modifies its argument. */
/** This function drops control chars, nbsp char and limit the number
* of consecutive space chars to one. It modifies its argument. */
void clr_spaces(unsigned char *str);
/* Replace invalid chars in @title with ' ' and trim all starting/ending
/** Replace invalid chars in @a title with ' ' and trim all starting/ending
* spaces. */
void sanitize_title(unsigned char *title);
/* Returns 0 if @url contains invalid chars, 1 if ok.
/** Returns 0 if @a url contains invalid chars, 1 if ok.
* It trims starting/ending spaces. */
int sanitize_url(unsigned char *url);

11
src/util/env.c
View File

@ -1,4 +1,5 @@
/* Environment variables handling */
/** Environment variables handling
* @file */
#ifdef HAVE_CONFIG_H
#include "config.h"
@ -16,11 +17,11 @@
#include "util/memory.h"
#include "util/string.h"
/* Set @name environment variable to @value or a substring of it:
/** Set @a name environment variable to @a value or a substring of it:
* On success, it returns 0.
* If @value is NULL and on error, it returns -1.
* If @length >= 0 and smaller than true @value length, it will
* set @name to specified substring of @value.
* If @a value is NULL and on error, it returns -1.
* If @a length >= 0 and smaller than true @a value length, it will
* set @a name to specified substring of @a value.
*/
int
env_set(unsigned char *name, unsigned char *value, int length)

3
src/util/error.c
View File

@ -1,4 +1,5 @@
/* Error handling and debugging stuff */
/** Error handling and debugging stuff
* @file */
#ifndef _GNU_SOURCE
#define _GNU_SOURCE /* Needed for vasprintf() */

81
src/util/error.h
View File

@ -1,26 +1,27 @@
#ifndef EL__UTIL_ERROR_H
#define EL__UTIL_ERROR_H
/* Here you will found a chunk of functions useful for error states --- from
/** Error handling and debugging stuff
* @file
*
* Here you will found a chunk of functions useful for error states --- from
* reporting of various problems to generic error tests/workarounds to some
* tools to be used when you got into an error state already. Some of the
* functions are also useful for debugging. */
#ifndef EL__UTIL_ERROR_H
#define EL__UTIL_ERROR_H
/* This errfile thing is needed, as we don't have var-arg macros in standart,
* only as gcc extension :(. */
extern int errline;
extern const unsigned char *errfile;
/* @DBG(format_string) is used for printing of debugging information. It
/** @c DBG(format_string) is used for printing of debugging information. It
* should not be used anywhere in the official codebase (although it is often
* lying there commented out, as it may get handy). */
#undef DBG
#define DBG errfile = __FILE__, errline = __LINE__, elinks_debug
void elinks_debug(unsigned char *fmt, ...);
/* @WDBG(format_string) is used for printing of debugging information, akin
/** @c WDBG(format_string) is used for printing of debugging information, akin
* to DBG(). However, it sleep(1)s, therefore being useful when it is going
* to be overdrawn or so. It should not be used anywhere in the official
* codebase (although it is often lying there commented out, as it may get
@ -29,7 +30,7 @@ void elinks_debug(unsigned char *fmt, ...);
#define WDBG errfile = __FILE__, errline = __LINE__, elinks_wdebug
void elinks_wdebug(unsigned char *fmt, ...);
/* @ERROR(format_string) is used to report non-fatal unexpected errors during
/** @c ERROR(format_string) is used to report non-fatal unexpected errors during
* the ELinks run. It tries to (not that agressively) draw user's attention to
* the error, but never dumps core or so. Note that this should be used only in
* cases of non-severe internal inconsistences etc, never as an indication of
@ -39,7 +40,7 @@ void elinks_wdebug(unsigned char *fmt, ...);
#define ERROR errfile = __FILE__, errline = __LINE__, elinks_error
void elinks_error(unsigned char *fmt, ...);
/* @INTERNAL(format_string) is used to report fatal errors during the ELinks
/** @c INTERNAL(format_string) is used to report fatal errors during the ELinks
* run. It tries to draw user's attention to the error and dumps core if ELinks
* is running in the CONFIG_DEBUG mode. */
#undef INTERNAL
@ -47,7 +48,7 @@ void elinks_error(unsigned char *fmt, ...);
void elinks_internal(unsigned char *fmt, ...);
/* @usrerror(format_string) is used to report user errors during a peaceful
/** @c usrerror(format_string) is used to report user errors during a peaceful
* ELinks run. It does not belong to the family above - it doesn't print code
* location, beep nor sleep, it just wraps around fprintf(stderr, "...\n");. */
void usrerror(unsigned char *fmt, ...);
@ -55,16 +56,18 @@ void usrerror(unsigned char *fmt, ...);
#ifdef HAVE_VARIADIC_MACROS
#ifdef CONFIG_DEBUG
/* The LOG_*() macros can be used to log to a file, however, by default log
/** The @c LOG_*() macros can be used to log to a file, however, by default log
* messages are written to stderr. Set the following environment variables
* to configure the log behavior:
*
* ELINKS_LOG - The path to the log file, it is opened for appending
* ELINKS_MSG - A comma separated list containing "error", "warn",
* <dl>
* <dt>ELINKS_LOG <dd>The path to the log file, it is opened for appending
* <dt>ELINKS_MSG <dd>A comma separated list containing "error", "warn",
* "info" and/or "debug" which can be used to limit
* what messages to emit to the log.
* ELINKS_FILES - A comma separated list of which files names to
* <dt>ELINKS_FILES <dd>A comma separated list of which files names to
* emit log messages from.
* </dl>
*/
void
elinks_log(unsigned char *msg, unsigned char *file, int line,
@ -91,10 +94,10 @@ elinks_log(unsigned char *msg, unsigned char *file, int line,
/* This is our smart assert(). It is basically equivalent to if (x) INTERNAL(),
/** This is our smart assert(). It is basically equivalent to if (x) INTERNAL(),
* but it generates a uniform message and mainly does not do the test if we are
* supposed to be lightning fast. Use it, use it a lot! And never forget the
* recovery path, see below if_assert_failed. */
* recovery path, see below ::if_assert_failed. */
#undef assert
#ifdef CONFIG_FASTMEM
@ -107,7 +110,7 @@ do { if (!assert_failed && (assert_failed = !(x))) { \
#endif
/* This is extended assert() version, it can print additional user-specified
/** This is extended assert() version, it can print additional user-specified
* message. Quite useful not only to detect that _something_ is wrong, but also
* _how_ wrong is it ;-). Note that the format string must always be a regular
* string, not a variable reference. Also, be careful _what_ will you attempt
@ -152,29 +155,31 @@ void elinks_assertm(int x, unsigned char *fmt, ...)
#endif /* HAVE_VARIADIC_MACROS */
/* To make recovery path possible (assertion failed may not mean end of the
/** Whether an assertion has failed and the failure has not yet been handled.
* To make recovery path possible (assertion failed may not mean end of the
* world, the execution goes on if we're outside of CONFIG_DEBUG and CONFIG_FASTMEM),
* @assert_failed is set to true if the last assert() failed, otherwise it's
* @c assert_failed is set to true if the last assert() failed, otherwise it's
* zero. Note that you must never change assert_failed value, sorry guys.
*
* You should never test assert_failed directly anyway. Use if_assert_failed
* You should never test @c assert_failed directly anyway. Use ::if_assert_failed
* instead, it will attempt to hint compiler to optimize out the recovery path
* if we're CONFIG_FASTMEM. So it should go like:
*
* @code
* assertm(1 == 1, "The world's gonna blow up!");
* if_assert_failed { schedule_time_machine(); return; } */
/* In-depth explanation: this restriction is here because in the CONFIG_FASTMEM mode,
* assert_failed is initially initialized to zero and then not ever touched
* if_assert_failed { schedule_time_machine(); return; }
* @endcode
*
* In-depth explanation: this restriction is here because in the CONFIG_FASTMEM mode,
* @c assert_failed is initially initialized to zero and then not ever touched
* anymore. So if you change it to non-zero failure, your all further recovery
* paths will get hit (and since developers usually don't test CONFIG_FASTMEM mode
* extensively...). So better don't mess with it, even if you would do that
* with awareness of this fact. We don't want to iterate over tens of spots all
* over the code when we change one detail regarding CONFIG_FASTMEM operation.
*
* This is not that actual after introduction of if_assert_failed, but it's
* This is not that actual after introduction of ::if_assert_failed, but it's
* a safe recommendation anyway, so... ;-) */
extern int assert_failed;
#undef if_assert_failed
@ -186,17 +191,18 @@ extern int assert_failed;
/* This will print some fancy message, version string and possibly do something
* else useful. Then, it will dump core. */
/** This will print some fancy message, version string and possibly do
* something else useful. Then, it will dump core. */
#ifdef CONFIG_DEBUG
void force_dump(void);
#endif
/* This function does nothing, except making compiler not to optimize certains
/** This function does nothing, except making compiler not to optimize certains
* spots of code --- this is useful when that particular optimization is buggy.
* So we are just workarounding buggy compilers. */
/* This function should be always used only in context of compiler version
* So we are just workarounding buggy compilers.
*
* This function should be always used only in context of compiler version
* specific macros. */
void do_not_optimize_here(void *x);
@ -219,11 +225,12 @@ void do_not_optimize_here(void *x);
#endif
/* This function dumps backtrace (or whatever similiar it founds on the stack)
* nicely formatted and with symbols resolved to @f. When @trouble is set, it
* tells it to be extremely careful and not use dynamic memory allocation
* functions etc (useful in SIGSEGV handler etc). */
/* Note that this function just calls system-specific backend provided by the
/** This function dumps backtrace (or whatever similar it founds on the stack)
* nicely formatted and with symbols resolved to @a f. When @a trouble is set,
* it tells it to be extremely careful and not use dynamic memory allocation
* functions etc (useful in SIGSEGV handler etc).
*
* Note that this function just calls system-specific backend provided by the
* libc, so it is available only on some systems. CONFIG_BACKTRACE is defined
* if it is available on yours. */
#ifdef CONFIG_BACKTRACE
@ -231,7 +238,7 @@ void do_not_optimize_here(void *x);
void dump_backtrace(FILE *f, int trouble);
#endif
/* This is needed for providing info about features when dumping core */
/** This is needed for providing info about features when dumping core */
extern unsigned char full_static_version[1024];
#endif

134
src/util/fastfind.c
View File

@ -1,4 +1,57 @@
/* Very fast search_keyword_in_list. */
/** Very fast search_keyword_in_list.
* @file
*
*
* It replaces bsearch() + strcasecmp() + callback + ...
*
* Following conditions should be met:
*
* - list keys are C strings.
* - keys should not be greater than 255 characters, and optimally < 20
* characters. It can work with greater keys but then memory usage will
* grow a lot.
* - each key must be unique and non empty.
* - list do not have to be ordered.
* - total number of unique characters used in all keys should be <= 128
* - idealy total number of keys should be <= 512 (but see below)
*
* (c) 2003 Laurent MONIN (aka Zas)
* Feel free to do whatever you want with that code.
*
*
* These routines use a tree search. First, a big tree is composed from the
* keys on input. Then, when searching we just go through the tree. If we will
* end up on an 'ending' node, we've got it.
*
* Hm, okay. For keys { 'head', 'h1', 'body', 'bodyrock', 'bodyground' }, it
* would look like:
*
* @verbatim
* [root]
* b h
* o e 1
* d a
* Y D
* g r
* r o
* o c
* u K
* D
* @endverbatim
*
* (the ending nodes are upcased just for this drawing, not in real)
*
* To optimize this for speed, leafs of nodes are organized in per-node arrays
* (so-called 'leafsets'), indexed by symbol value of the key's next character.
* But to optimize that for memory, we first compose own alphabet consisting
* only from the chars we ever use in the key strings. fastfind_info.uniq_chars
* holds that alphabet and fastfind_info.idxtab is used to translate between it
* and ASCII.
*
* Tree building: O((L+M)*N)
* (L: mean key length, M: alphabet size,
* N: number of items).
* String lookup: O(N) (N: string length). */
#ifdef HAVE_CONFIG_H
#include "config.h"
@ -17,61 +70,12 @@
#ifdef USE_FASTFIND
/* It replaces bsearch() + strcasecmp() + callback + ...
*
* Following conditions should be met:
*
* - list keys are C strings.
* - keys should not be greater than 255 characters, and optimally < 20
* characters. It can work with greater keys but then memory usage will
* grow a lot.
* - each key must be unique and non empty.
* - list do not have to be ordered.
* - total number of unique characters used in all keys should be <= 128
* - idealy total number of keys should be <= 512 (but see below)
*
* (c) 2003 Laurent MONIN (aka Zas)
* Feel free to do whatever you want with that code. */
/* These routines use a tree search. First, a big tree is composed from the
* keys on input. Then, when searching we just go through the tree. If we will
* end up on an 'ending' node, we've got it.
*
* Hm, okay. For keys { 'head', 'h1', 'body', 'bodyrock', 'bodyground' }, it
* would look like:
*
* [root]
* b h
* o e 1
* d a
* Y D
* g r
* r o
* o c
* u K
* D
*
* (the ending nodes are upcased just for this drawing, not in real)
*
* To optimize this for speed, leafs of nodes are organized in per-node arrays
* (so-called 'leafsets'), indexed by symbol value of the key's next character.
* But to optimize that for memory, we first compose own alphabet consisting
* only from the chars we ever use in the key strings. @uniq_chars holds that
* alphabet and @idxtab is used to translate between it and ASCII.
*
* Tree building: O((L+M)*N)
* (L: mean key length, M: alphabet size,
* N: number of items).
* String lookup: O(N) (N: string length). */
/* Define it to generate performance and memory usage statistics to stderr. */
/** Define it to generate performance and memory usage statistics to stderr. */
#if 0
#define DEBUG_FASTFIND
#endif
/* Define whether to use 32 or 64 bits per compressed element. */
/** Define whether to use 32 or 64 bits per compressed element. */
#if 1
#define USE_32_BITS
#endif
@ -114,16 +118,16 @@
#endif
struct ff_node {
/* End leaf -> p is significant */
/** End leaf -> p is significant */
unsigned int e:END_LEAF_BITS;
/* Compressed */
/** Compressed */
unsigned int c:COMPRESSED_BITS;
/* Index in pointers */
/** Index in pointers */
unsigned int p:POINTER_INDEX_BITS;
/* Index in leafsets */
/** Index in leafsets */
unsigned int l:LEAFSET_INDEX_BITS;
};
@ -141,7 +145,7 @@ struct ff_node_c {
unsigned int p:POINTER_INDEX_BITS;
unsigned int l:LEAFSET_INDEX_BITS;
/* Index of char when compressed. */
/** Index of char when compressed. */
unsigned int ch:COMP_CHAR_INDEX_BITS;
};
@ -212,7 +216,7 @@ struct fastfind_info {
} while (0)
#define FF_DBG_comment(x, str) do { (x)->debug.comment = empty_string_or_(str); } while (0)
/* Update search stats. */
/** Update search stats. */
static void
FF_DBG_search_stats(struct fastfind_info *info, int key_len)
{
@ -222,7 +226,7 @@ FF_DBG_search_stats(struct fastfind_info *info, int key_len)
info->debug.itertmp = info->debug.iterations;
}
/* Dump all stats. */
/** Dump all stats. */
static void
FF_DBG_dump_stats(struct fastfind_info *info)
{
@ -296,7 +300,7 @@ init_fastfind(struct fastfind_index *index, enum fastfind_flags flags)
return info;
}
/* Return 1 on success, 0 on allocation failure */
/** @returns 1 on success, 0 on allocation failure */
static int
alloc_ff_data(struct fastfind_info *info)
{
@ -315,7 +319,7 @@ alloc_ff_data(struct fastfind_info *info)
return 1;
}
/* Add pointer and its key length to correspondant arrays, incrementing
/** Add pointer and its key length to correspondant arrays, incrementing
* internal counter. */
static void
add_to_ff_data(void *p, int key_len, struct fastfind_info *info)
@ -327,7 +331,7 @@ add_to_ff_data(void *p, int key_len, struct fastfind_info *info)
data->keylen = key_len;
}
/* Return 1 on success, 0 on allocation failure */
/** @returns 1 on success, 0 on allocation failure */
static int
alloc_leafset(struct fastfind_info *info)
{
@ -542,7 +546,7 @@ return_error:
#undef ifcase
/* This macro searchs for the key in indexed list */
/** This macro searchs for the key in indexed list */
#define FF_SEARCH(what) do { \
int i; \
\
@ -729,14 +733,14 @@ struct list list[] = {
struct list *internal_pointer;
/* Reset internal list pointer */
/** Reset internal list pointer */
void
reset_list(void)
{
internal_pointer = list;
}
/* Returns a pointer to a struct that contains
/** Returns a pointer to a struct that contains
* current key and data pointers and increment
* internal pointer.
* It returns NULL when key is NULL. */

35
src/util/fastfind.h
View File

@ -1,7 +1,7 @@
#ifndef EL__UTIL_FASTFIND_H
#define EL__UTIL_FASTFIND_H
/* Whether to use these routines or not. */
/** Whether to use these routines or not. */
#ifndef CONFIG_SMALL
#define USE_FASTFIND 1
#else
@ -17,39 +17,40 @@ struct fastfind_key_value {
enum fastfind_flags {
FF_NONE = 0,
FF_CASE_AWARE = 1, /* honour case when comparing */
FF_COMPRESS = 2, /* compress nodes if possible */
FF_CASE_AWARE = 1, /**< honour case when comparing */
FF_COMPRESS = 2, /**< compress nodes if possible */
};
struct fastfind_index {
/* Description useful for debugging mode. */
/** Description useful for debugging mode. */
unsigned char *comment;
/* Start over. */
/** Start over. */
void (*reset)(void);
/* Get next struct fastfind_key_value in line. */
/** Get next struct fastfind_key_value in line. */
struct fastfind_key_value *(*next)(void);
/* Internal reference */
/** Internal reference */
void *handle;
};
#define INIT_FASTFIND_INDEX(comment, reset, next) \
{ (comment), (reset), (next) }
/* Initialize and index a list of keys. */
/* Keys are iterated using:
* @index index info
* @flags control case sensitivity, compression */
/* This function must be called once and only once per list. */
/* Failure is not an option, so call it at startup. */
/** Initialize and index a list of keys.
* Keys are iterated using:
* @param index index info
* @param flags control case sensitivity, compression
*
* This function must be called once and only once per list.
* Failure is not an option, so call it at startup. */
struct fastfind_index *fastfind_index(struct fastfind_index *index, enum fastfind_flags flags);
/* The main reason of all that stuff is here. */
/* Search the index for @key with length @key_len using the
* @index' handle created with fastfind_index(). */
/** Search the index for @a key with length @a key_len using the
* @a index' handle created with fastfind_index(). */
void *fastfind_search(struct fastfind_index *index, unsigned char *key, int key_len);
/* Fastfind cleanup. It frees the index given by the @fastfind_handle. */
/* Must be called once per list. */
/** Fastfind cleanup. It frees the given @a index.
* Must be called once per list. */
void fastfind_done(struct fastfind_index *index);
#endif

19
src/util/file.c
View File

@ -1,4 +1,5 @@
/* File utilities */
/** File utilities
* @file */
#ifdef HAVE_CONFIG_H
#include "config.h"
@ -283,7 +284,8 @@ safe_mkstemp(unsigned char *template)
}
/* The stat_* functions set the various attributes for directory entries. */
/** @name The stat_* functions set the various attributes for directory entries.
* @{ */
static inline void
stat_type(struct string *string, struct stat *stp)
@ -476,6 +478,8 @@ stat_date(struct string *string, struct stat *stp)
add_to_string(string, " ");
}
/** @} */
static int
compare_dir_entries(struct directory_entry *d1, struct directory_entry *d2)
@ -488,8 +492,8 @@ compare_dir_entries(struct directory_entry *d1, struct directory_entry *d2)
}
/* This function decides whether a file should be shown in directory listing or
* not. Returns according boolean value. */
/** This function decides whether a file should be shown in directory
* listing or not. @returns according boolean value. */
static inline int
file_visible(unsigned char *name, int get_hidden_files, int is_root_directory)
{
@ -510,9 +514,8 @@ file_visible(unsigned char *name, int get_hidden_files, int is_root_directory)
return get_hidden_files;
}
/* First information such as permissions is gathered for each directory entry.
* All entries are then sorted and finally the sorted entries are added to the
* @data->fragment one by one. */
/** First information such as permissions is gathered for each directory entry.
* All entries are then sorted. */
struct directory_entry *
get_directory_entries(unsigned char *dirname, int get_hidden)
{
@ -585,7 +588,7 @@ get_directory_entries(unsigned char *dirname, int get_hidden)
return entries;
}
/* Recursively create directories in a path. The last element in the path is
/** Recursively create directories in @a path. The last element in the path is
* taken to be a filename, and simply ignored */
int
mkalldirs(const unsigned char *path)

41
src/util/file.h
View File

@ -4,18 +4,18 @@
#include <stdio.h>
/** Data read about an entry in a directory.
* The strings pointed to by this structure are in the system
* charset (i.e. LC_CTYPE) and must be freed with mem_free(). */
struct directory_entry {
/* The strings pointed to by this structure are in the system
* charset (i.e. LC_CTYPE) and must be freed with mem_free. */
/* The various attribute info collected with the stat_* functions. */
/** The various attribute info collected with the @c stat_* functions. */
unsigned char *attrib;
/* The full path of the dir entry. */
/** The full path of the dir entry. */
unsigned char *name;
};
/* First information such as permissions is gathered for each directory entry.
/** First information such as permissions is gathered for each directory entry.
* All entries are then sorted. */
struct directory_entry *
get_directory_entries(unsigned char *dirname, int get_hidden_files);
@ -24,37 +24,38 @@ int file_exists(const unsigned char *filename);
int file_can_read(const unsigned char *filename);
int file_is_dir(const unsigned char *filename);
/* Strips all directory stuff from @filename and returns the
/** Strips all directory stuff from @a filename and returns the
* position of where the actual filename starts */
unsigned char *get_filename_position(unsigned char *filename);
/* Tilde is only expanded for the current users homedir (~/). */
/* The returned file name is allocated. */
/** Tilde is only expanded for the current users homedir (~/).
* The returned file name is allocated. */
unsigned char *expand_tilde(unsigned char *filename);
/* Generate a unique file name by trial and error based on the @fileprefix by
* adding suffix counter (e.g. '.42'). */
/* The returned file name is allocated if @fileprefix is not unique. */
/*! \brief Generate a unique file name by trial and error based on the
* @a fileprefix by adding suffix counter (e.g. '.42').
*
* The returned file name is allocated if @a fileprefix is not unique. */
unsigned char *get_unique_name(unsigned char *fileprefix);
/* Checks various environment variables to get the name of the temp dir.
/** Checks various environment variables to get the name of the temp dir.
* Returns a filename by concatenating "<tmpdir>/<name>". */
unsigned char *get_tempdir_filename(unsigned char *name);
/* Read a line from @file into the dynamically allocated @line, increasing
* @line if necessary. Ending whitespace is trimmed. If a line ends
* with "\" the next line is read too. */
/* If @line is NULL the returned line is allocated and if file reading fails
* @line is free()d. */
/** Read a line from @a file into the dynamically allocated @a line,
* increasing @a line if necessary. Ending whitespace is trimmed.
* If a line ends with "\" the next line is read too.
* If @a line is NULL the returned line is allocated and if file
* reading fails @a line is free()d. */
unsigned char *file_read_line(unsigned char *line, size_t *linesize,
FILE *file, int *linenumber);
/* Safe wrapper for mkstemp().
/** Safe wrapper for mkstemp().
* It enforces permissions by calling umask(0177), call mkstemp(), then
* restore previous umask(). */
int safe_mkstemp(unsigned char *template);
/* Recursively create directories in a path. The last element in the path is
/** Recursively create directories in @a path. The last element in the path is
* taken to be a filename, and simply ignored */
int mkalldirs(const unsigned char *path);

32
src/util/hash.c
View File

@ -1,4 +1,5 @@
/* Hashing infrastructure */
/** Hashing infrastructure
* @file */
#ifdef HAVE_CONFIG_H
#include "config.h"
@ -71,11 +72,12 @@ free_hash(struct hash **hashp)
}
/* I've no much idea about what to set here.. I think it doesn't matter much
/** Initialization vector for the hash function.
* I've no much idea about what to set here.. I think it doesn't matter much
* anyway.. ;) --pasky */
#define HASH_MAGIC 0xdeadbeef
/* Returns hash_item if ok, NULL if error. */
/** @returns hash_item if ok, NULL if error. */
struct hash_item *
add_hash_item(struct hash *hash, unsigned char *key, unsigned int keylen,
void *value)
@ -123,7 +125,8 @@ get_hash_item(struct hash *hash, unsigned char *key, unsigned int keylen)
#undef HASH_MAGIC
/* If key and/or value were dynamically allocated, think about freeing them.
/** Delete @a item from @a hash.
* If key and/or value were dynamically allocated, think about freeing them.
* This function doesn't do that. */
void
del_hash_item(struct hash *hash, struct hash_item *item)
@ -138,11 +141,14 @@ del_hash_item(struct hash *hash, struct hash_item *item)
#ifdef X31_HASH
/* Fast string hashing. */
/** Fast string hashing.
* @param k the key
* @param length the length of the key
* @param initval the previous hash, or an arbitrary value */
static hash_value_T
strhash(unsigned char *k, /* the key */
unsigned int length, /* the length of the key */
hash_value_T initval /* the previous hash, or an arbitrary value */)
strhash(unsigned char *k,
unsigned int length,
hash_value_T initval)
{
const unsigned char *p = (const unsigned char *) k;
hash_value_T h = initval;
@ -260,10 +266,14 @@ strhash(unsigned char *k, /* the key */
+ ((hash_value_T) (k[(a)+2])<<16) \
+ ((hash_value_T) (k[(a)+3])<<24))
/** Hash an array of bytes.
* @param k the key
* @param length the length of the key
* @param initval the previous hash, or an arbitrary value */
static hash_value_T
strhash(unsigned char *k, /* the key */
unsigned int length, /* the length of the key */
hash_value_T initval /* the previous hash, or an arbitrary value */)
strhash(unsigned char *k,
unsigned int length,
hash_value_T initval)
{
int len;
hash_value_T a, b, c;

6
src/util/hash.h
View File

@ -3,7 +3,7 @@
#include "util/lists.h"
/* This should be hopefully always 32bit at least. I'm not sure what will
/** This should be hopefully always 32bit at least. I'm not sure what will
* happen when this will be of other length, but it should still work ok.
* --pasky */
typedef unsigned long hash_value_T;
@ -18,9 +18,9 @@ struct hash_item {
};
struct hash {
unsigned int width; /* Number of bits - hash array must be 2^width long. */
unsigned int width; /**< Number of bits - hash array must be 2^width long. */
hash_func_T func;
struct list_head hash[1]; /* Must be at end ! */
struct list_head hash[1]; /**< Must be at end ! */
};
struct hash *init_hash8(void);

4
src/util/lists.h
View File

@ -14,7 +14,7 @@
*
* Fixing this would be a nice and needed janitorial project. */
/* Lists debugging
/** Lists debugging.
* Two unsigned int magic number will be put before and after the next and
* prev pointers, these will be check on list operations.
* Some pointers are set to specific values after action. */
@ -81,7 +81,7 @@ do { \
} while (0)
/* Backend for list_magic_check() and list_magic_chkbool(). */
/** Backend for list_magic_check() and list_magic_chkbool(). */
#define list_magic_correct(x) ((x).magic1 == LISTMAGIC1 && (x).magic2 == LISTMAGIC2)
#define list_magic_check(x, where) \

11
src/util/math.h
View File

@ -38,22 +38,22 @@ int_max(register int x, register int y)
}
/* Limit @what pointed value to upper bound @limit. */
/** Limit @a what pointed value to upper bound @a limit. */
static inline void
int_upper_bound(register int *what, register int limit)
{
if (*what > limit) *what = limit;
}
/* Limit @what pointed value to lower bound @limit. */
/** Limit @a what pointed value to lower bound @a limit. */
static inline void
int_lower_bound(register int *what, register int limit)
{
if (*what < limit) *what = limit;
}
/* Limit @what pointed value to lower bound @lower_limit and to upper bound
* @upper_limit. */
/** Limit @a what pointed value to lower bound @a lower_limit and to
* upper bound @a upper_limit. */
static inline void
int_bounds(register int *what, register int lower_limit,
register int upper_limit)
@ -65,7 +65,8 @@ int_bounds(register int *what, register int lower_limit,
}
/* This is supposed to evaluate at compile time, giving no performance hit. */
/** Swap values @a a and @a b, both of type @a type.
* This is supposed to evaluate at compile time, giving no performance hit. */
#define swap_values(type, a, b) \
do { \
type swap_register_ = (a); \

26
src/util/md5.c
View File

@ -1,6 +1,7 @@
/* MD5 implementation (RFC 1321) */
/* This code implements the MD5 message-digest algorithm. The algorithm is due
/** MD5 implementation (RFC 1321)
* @file
*
* This code implements the MD5 message-digest algorithm. The algorithm is due
* to Ron Rivest.
*
* This code was written by Colin Plumb in 1993, no copyright is claimed. This
@ -26,8 +27,9 @@
static void transform_md5(uint32_t buf[4], uint32_t const in[16]);
/* This code is harmless on little-endian machines. */
/* FIXME: Optimize it away on little-endian machines. */
/** Swap the bytes of each uint32_t, if necessary.
* This code is harmless on little-endian machines.
* \todo FIXME: Optimize it away on little-endian machines. */
static void
reverse_md5_bytes(unsigned char *buf, unsigned int longs)
{
@ -41,7 +43,7 @@ reverse_md5_bytes(unsigned char *buf, unsigned int longs)
} while (--longs);
}
/* Start MD5 accumulation. Set bit count to 0 and buffer to mysterious
/** Start MD5 accumulation. Set bit count to 0 and buffer to mysterious
* initialization constants. */
void
init_md5(struct md5_context *ctx)
@ -55,7 +57,7 @@ init_md5(struct md5_context *ctx)
ctx->bits[1] = 0;
}
/* Update context to reflect the concatenation of another buffer full
/** Update context to reflect the concatenation of another buffer full
* of bytes. */
void
update_md5(struct md5_context *ctx, const unsigned char *buf, unsigned long len)
@ -103,10 +105,10 @@ update_md5(struct md5_context *ctx, const unsigned char *buf, unsigned long len)
memmove(ctx->in, buf, len);
}
/* Final wrapup - pad to 64-byte boundary with the bit pattern 1 0* (64-bit
/** Final wrapup - pad to 64-byte boundary with the bit pattern 1 0* (64-bit
* count of bits processed, MSB-first) */
void
done_md5(struct md5_context *ctx, unsigned char digest[16])
done_md5(struct md5_context *ctx, md5_digest_bin_T digest)
{
unsigned int count;
unsigned char *p;
@ -150,7 +152,7 @@ done_md5(struct md5_context *ctx, unsigned char digest[16])
unsigned char *
digest_md5(const unsigned char *data, unsigned long length,
unsigned char digest[16])
md5_digest_bin_T digest)
{
struct md5_context ctx;
@ -172,11 +174,11 @@ digest_md5(const unsigned char *data, unsigned long length,
#define F3(x, y, z) (x ^ y ^ z)
#define F4(x, y, z) (y ^ (x | ~z))
/* This is the central step in the MD5 algorithm. */
/** This is the central step in the MD5 algorithm. */
#define MD5STEP(f, w, x, y, z, data, s) \
( w += f(x, y, z) + data, w = w<<s | w>>(32-s), w += x )
/* The core of the MD5 algorithm, this alters an existing MD5 hash to reflect
/** The core of the MD5 algorithm, this alters an existing MD5 hash to reflect
* the addition of 16 longwords of new data. md5_update() blocks the data and
* converts bytes into longwords for this routine. */
static void

8
src/util/md5.h
View File

@ -37,13 +37,14 @@ void init_md5(struct md5_context *context);
void update_md5(struct md5_context *context, const unsigned char *data, unsigned long length);
void done_md5(struct md5_context *context, md5_digest_bin_T digest);
/* Digest the passed @data with the given length and stores the MD5 digest in
* the @digest parameter. */
/** Digest the passed @a data with the given length and stores the MD5
* digest in the @a digest parameter. */
unsigned char *
digest_md5(const unsigned char *data, unsigned long length, md5_digest_bin_T digest);
#ifdef CONFIG_MD5
/* Provide compatibility with the OpenSSL interface: */
/** @name Provide compatibility with the OpenSSL interface:
* @{ */
typedef struct md5_context MD5_CTX;
#define MD5_Init(context) init_md5(context)
@ -51,6 +52,7 @@ typedef struct md5_context MD5_CTX;
#define MD5_Final(md5, context) done_md5(context, md5)
#define MD5(data, len, md5) digest_md5(data, len, md5)
/** @} */
#endif /* CONFIG_MD5 */
#endif

27
src/util/memdebug.c
View File

@ -1,6 +1,7 @@
/* Memory debugging (leaks, overflows & co) */
/* Wrappers for libc memory managment providing protection against common
/** Memory debugging (leaks, overflows & co)
* @file
*
* Wrappers for libc memory managment providing protection against common
* pointers manipulation mistakes - bad realloc()/free() pointers, double
* free() problem, using uninitialized/freed memory, underflow/overflow
* protection, leaks tracking...
@ -52,49 +53,49 @@
#ifdef DEBUG_MEMLEAK
/* Eat less memory, but sacrifice speed?
/** Eat less memory, but sacrifice speed?
* Default is defined. */
#define LESS_MEMORY_SPEED
/* Fill memory on alloc() ?
/** Fill memory on alloc() ?
* Default is defined. */
#define FILL_ON_ALLOC
#define FILL_ON_ALLOC_VALUE 'X'
/* Fill memory on realloc() ?
/** Fill memory on realloc() ?
* Default is defined. */
#define FILL_ON_REALLOC
#define FILL_ON_REALLOC_VALUE 'Y'
/* Fill memory before free() ?
/** Fill memory before free() ?
* Default is undef. */
#undef FILL_ON_FREE
#define FILL_ON_FREE_VALUE 'Z'
/* Check alloc_header block sanity ?
/** Check alloc_header block sanity ?
* Default is defined. */
#define CHECK_AH_SANITY
#define AH_SANITY_MAGIC 0xD3BA110C
/* Check for useless reallocation ?
/** Check for useless reallocation ?
* If oldsize is equal to newsize, print a message to stderr.
* It may help to find inefficient code.
* Default is undefined.
*/
#undef CHECK_USELESS_REALLOC
/* Check for validity of address passed to free() ?
/** Check for validity of address passed to free() ?
* Note that this is VERY slow, as we iterate through whole memory_list each
* time. We can't check magics etc, as it would break double free() check.
* Default is undef. */
#undef CHECK_INVALID_FREE
/* Check for double free ?
/** Check for double free ?
* Default is defined. */
#define CHECK_DOUBLE_FREE
#define AH_FREE_MAGIC 0xD3BF110C
/* Check for overflows and underflows ?
/** Check for overflows and underflows ?
* Default is defined. */
#define CHECK_XFLOWS
#define XFLOW_MAGIC (char) 0xFA
@ -118,7 +119,7 @@ struct alloc_header {
unsigned char *comment;
#ifdef CHECK_XFLOWS
/* This is a little magic. We want to keep the main pointer aligned,
/** This is a little magic. We want to keep the main pointer aligned,
* that means we want to have the xflow underflow mark in the
* alloc_header space, but at the _end_ of the aligned reserved space.
* This means we in fact live at [SIZE_AH_ALIGNED - 1], not here. (Of

14
src/util/memlist.c
View File

@ -1,4 +1,5 @@
/* These routines represent handling of struct memory_list. */
/** These routines represent handling of struct memory_list.
* @file */
#ifdef HAVE_CONFIG_H
#include "config.h"
@ -14,7 +15,8 @@
#include "util/memory.h"
/*
/**
* \struct memory_list
* memory_list is used to track information about all allocated memory
* belonging to something. Then we can free it when we won't need it
* anymore, but the one who allocated it won't be able to get control
@ -23,8 +25,8 @@
#define ML_SIZE(n) (sizeof(struct memory_list) + (n) * sizeof(void *))
/* Create a memory list. If p is NULL or allocation fails, it will
* returns NULL.
/** Create a memory list. If @a p is NULL or allocation fails, it will
* return NULL.
* It always stops at first NULL element. */
#if defined(DEBUG_MEMLIST) && defined(HAVE_VARIADIC_MACROS)
struct memory_list *
@ -65,7 +67,7 @@ getml(void *p, ...)
return ml;
}
/* Add elements to a memory list.
/** Add elements to a memory list.
* If memory list exists, it enlarges it, else it creates it.
* if there's no elements or first element is NULL, it does nothing.
* It always stops at first NULL element. */
@ -161,7 +163,7 @@ add_one_to_ml(struct memory_list **ml, void *p)
}
/* Free elements and memory list.
/** Free elements and memory list.
* It returns safely if passed a NULL pointer. */
void
freeml(struct memory_list *ml)

10
src/util/memory.c
View File

@ -1,4 +1,5 @@
/* Memory allocation manager */
/** Memory allocation manager
* @file */
#ifndef _GNU_SOURCE
#define _GNU_SOURCE /* MREMAP_MAYMOVE */
@ -128,8 +129,9 @@ mem_realloc(void *p, size_t size)
static int page_size;
/* This tries to prevent useless reallocations, especially since they are quite
* expensive in the mremap()-less case. */
/** Round up to a full page.
* This tries to prevent useless reallocations, especially since they
* are quite expensive in the mremap()-less case. */
static size_t
round_size(size_t size)
{
@ -140,7 +142,7 @@ round_size(size_t size)
return (size / page_size + 1) * page_size;
}
/* Some systems may not have MAP_ANON but MAP_ANONYMOUS instead. */
/** Some systems may not have MAP_ANON but MAP_ANONYMOUS instead. */
#if defined(MAP_ANONYMOUS) && !defined(MAP_ANON)
#define MAP_ANON MAP_ANONYMOUS
#endif

29
src/util/memory.h
View File

@ -5,17 +5,17 @@
* if not defined, we'll try to continue. */
/* #define CRASH_IF_ALLOC_MAXTRIES */
/* Max. number of retry in case of memory allocation failure. */
/** Max. number of retry in case of memory allocation failure. */
#define ALLOC_MAXTRIES 3
/* Delay in seconds between each alloc try. */
/** Delay in seconds between each alloc try. */
#define ALLOC_DELAY 3
#define fmem_alloc(x) mem_alloc(x)
#define fmem_free(x) mem_free(x)
/* Cygwin wants some size_t definition here... let's try to make it happy
/** Cygwin wants some size_t definition here... let's try to make it happy
* then. Hrmpf. */
#include <sys/types.h>
#include <stddef.h>
@ -108,17 +108,17 @@ void *mem_realloc(void *, size_t);
#endif /* DEBUG_MEMLEAK */
/* Granular memory allocation. */
/** @name Granular memory allocation.
* The granularity used by the aligned memory functions below must be a mask
* with all bits set from but not including the most significant bit and down.
* So if an alignment of 256 is wanted use 0xFF.
* @{ */
/* The ``old'' style granularity. XXX: Must be power of 2 */
/** The 'old' style granularity. XXX: Must be power of 2 */
#define ALLOC_GR 0x100
#include <string.h> /* for memset() */
/* The granularity used by the aligned memory functions below must be a mask
* with all bits set from but not including the most significant bit and down.
* So if an alignment of 256 is wanted use 0xFF. */
#define ALIGN_MEMORY_SIZE(x, gr) (((x) + (gr)) & ~(gr))
static inline void *
@ -159,10 +159,14 @@ mem_align_alloc__(
mem_align_alloc__((void **) ptr, old, new, sizeof(**ptr), mask)
#endif
/** @} */
/* Maybe-free macros */
/* TODO: Think about making what they do more obvious in their identifier, they
* could be obfuscating their users a little for the newcomers otherwise. */
/** @name Maybe-free macros
* \todo TODO: Think about making what they do more obvious in their
* identifier, they could be obfuscating their users a little for the
* newcomers otherwise.
* @{ */
#define mem_free_set(x, v) do { if (*(x)) mem_free(*(x)); *(x) = (v); } while (0)
#define mem_free_if(x) do { register void *p = (x); if (p) mem_free(p); } while (0)
@ -172,6 +176,7 @@ mem_align_alloc__(
#undef mem_free_if
#define mem_free_if(x) mem_free_set(&x, NULL)
#endif
/** @} */
/* This is out of place, but there is no better place. */

18
src/util/profile.h
View File

@ -1,3 +1,6 @@
/** Process' CPU time utilities
* @file*/
#ifndef EL__UTIL_PROFILE_H
#define EL__UTIL_PROFILE_H
@ -5,31 +8,30 @@
#include "config.h"
#endif
/* Process' CPU time utilities */
#ifdef CONFIG_DEBUG
#include <time.h>
/* CLK_DECL(n) declares an array of @n clock_t to be used by CLK_* macros.
* Must occur before any CLK_* macros call. */
/** @c CLK_DECL(n) declares an array of @a n clock_t to be used by
* CLK_* macros. Must occur before any CLK_* macros call. */
#define CLK_DECL(n) clock_t clk_start[n], clk_end[n], clk_diff[n]; int clk_start_line[n], clk_stop_line[n]
/* CLK_START(n) starts clock @n.
/** @c CLK_START(n) starts clock @a n.
* Must occur after CLK_DECL() and before CLK_STOP(). */
#define CLK_START(n) do { clk_start_line[n] = __LINE__; clk_start[n] = clock(); } while (0)
/* CLK_STOP(n) stops clock @n.
/* @c CLK_STOP(n) stops clock @a n.
* Must occur after CLK_START() and before CLK_DUMP(). */
#define CLK_STOP(n) do { clk_end[n] = clock(); clk_diff[n] = clk_end[n] - clk_start[n]; clk_stop_line[n] = __LINE__; } while (0)
/* CLK_DUMP(n) echoes cpu time spent between CLK_START(@n) and CLK_STOP(@n).
* Must occur after CLK_START() and CLK_STOP(). */
/* @c CLK_DUMP(n) echoes cpu time spent between CLK_START(@a n) and
* CLK_STOP(@a n). Must occur after CLK_START() and CLK_STOP(). */
#define CLK_DUMP(n) do { \
fprintf(stderr, "%s:%d->%d CLK[%d]= %.16f sec.\n", \
__FILE__, clk_start_line[n], clk_stop_line[n], \
n, (double) clk_diff[n] / (double) CLOCKS_PER_SEC);\
} while (0)
/* Shortcuts for function profiling.
/** Shortcuts for function profiling.
* CLK_STA() must be at end of local declarations.
* CLK_STO() must be just before end of function. */
#define CLK_STA() CLK_DECL(1); CLK_START(0)

8
src/util/scanner.c
View File

@ -1,4 +1,5 @@
/* A pretty generic scanner */
/** A pretty generic scanner
* @file */
#ifdef HAVE_CONFIG_H
#include "config.h"
@ -116,7 +117,8 @@ get_scanner_token_debug(struct scanner *scanner)
#endif
/* Initializers */
/** @name Initializers
* @{ */
static inline void
init_scanner_info(struct scanner_info *scanner_info)
@ -170,3 +172,5 @@ init_scanner(struct scanner *scanner, struct scanner_info *scanner_info,
scanner->info = scanner_info;
scanner->info->scan(scanner);
}
/** @} */

92
src/util/scanner.h
View File

@ -6,19 +6,19 @@
/* Define if you want a talking scanner */
/* #define DEBUG_SCANNER */
/* The {struct scanner_token} describes one scanner state. There are two kinds
/** The struct scanner_token describes one scanner state. There are two kinds
* of tokens: char and non-char tokens. Char tokens contains only one char and
* simply have their char value as type. They are tokens having special control
* meaning in the code, like ':', ';', '{', '}' and '*'. Non char tokens has
* one or more chars and contain stuff like number or indentifier strings. */
struct scanner_token {
/* The type the token */
/** The type of the token */
int type;
/* Some precedence value */
/** Some precedence value */
int precedence;
/* The start of the token string and the token length */
/** The start of the token string and the token length */
unsigned char *string;
int length;
};
@ -27,11 +27,11 @@ struct scanner_token {
* "static" strings (I don't have a better word) so the macro name should
* be short. --jonas */
/* Compare the string of @token with @string */
/** Compare the string of @a token with @a str */
#define scanner_token_strlcasecmp(token, str, len) \
((token) && !strlcasecmp((token)->string, (token)->length, str, len))
/* Also compares the token string but using a "static" string */
/** Also compares the token string but using a "static" string */
#define scanner_token_contains(token, str) \
scanner_token_strlcasecmp(token, str, sizeof(str) - 1)
@ -63,65 +63,66 @@ struct scanner_string_mapping {
struct scanner;
struct scanner_info {
/* Table containing how to map strings to token types */
/** Table containing how to map strings to token types */
const struct scanner_string_mapping *mappings;
/* Information for how to initialize the scanner table */
/** Information for how to initialize the scanner table */
const struct scan_table_info *scan_table_info;
/* Fills the scanner with tokens. Already scanned tokens which have not
* been requested remain and are moved to the start of the scanners
* token table. */
/* Returns the current token or NULL if there are none. */
/** Fills the scanner with tokens. Already scanned tokens
* which have not been requested remain and are moved to the
* start of the scanners token table.
* @returns the current token or NULL if there are none. */
struct scanner_token *(*scan)(struct scanner *scanner);
/* The scanner table */
/* Contains bitmaps for the various characters groups.
* Idea sync'ed from mozilla browser. */
/** The scanner table. Contains bitmaps for the various
* characters groups. Idea sync'ed from mozilla browser. */
int scan_table[SCAN_TABLE_SIZE];
/* Has the scanner info been initialized? */
/** Has the scanner info been initialized? */
unsigned int initialized:1;
};
/* Initializes the scanner. */
/** Initializes the scanner. */
void init_scanner(struct scanner *scanner, struct scanner_info *scanner_info,
unsigned char *string, unsigned char *end);
/* The number of tokens in the scanners token table:
/** The number of tokens in the scanners token table:
* At best it should be big enough to contain properties with space separated
* values and function calls with up to 3 variables like rgb(). At worst it
* should be no less than 2 in order to be able to peek at the next token in
* the scanner. */
#define SCANNER_TOKENS 10
/* The {struct scanner} describes the current state of the scanner. */
/** The struct scanner describes the current state of the scanner. */
struct scanner {
/* The very start of the scanned string, the position in the string
* where to scan next and the end of the string. If position is NULL it
* means that no more tokens can be retrieved from the string. */
/** The very start of the scanned string, the position in the string
* where to scan next and the end of the string. If #position is NULL
* it means that no more tokens can be retrieved from the string. */
unsigned char *string, *position, *end;
/* The current token and number of scanned tokens in the table.
* If the number of scanned tokens is less than SCANNER_TOKENS
/** The current token and number of scanned tokens in the table.
* If the number of scanned tokens is less than ::SCANNER_TOKENS
* it is because there are no more tokens in the string. */
struct scanner_token *current;
int tokens;
/* The 'meta' scanner information */
/** The 'meta' scanner information */
struct scanner_info *info;
#ifdef DEBUG_SCANNER
/* Debug info about the caller. */
/** @name Debug info about the caller.
* @{ */
unsigned char *file;
int line;
/** @} */
#endif
/* Some state indicator only meaningful to the scanner internals */
/** Some state indicator only meaningful to the scanner internals */
int state;
/* The table contain already scanned tokens. It is maintained in
/** The table contain already scanned tokens. It is maintained in
* order to optimize the scanning a bit and make it possible to look
* ahead at the next token. You should always use the accessors
* (defined below) for getting tokens from the scanner. */
@ -131,7 +132,7 @@ struct scanner {
#define scanner_has_tokens(scanner) \
((scanner)->tokens > 0 && (scanner)->current < (scanner)->table + (scanner)->tokens)
/* This macro checks if the current scanner state is valid. Meaning if the
/** This macro checks if the current scanner state is valid. Meaning if the
* scanners table is full the last token skipping or get_next_scanner_token()
* call made it possible to get the type of the next token. */
#define check_scanner(scanner) \
@ -139,15 +140,16 @@ struct scanner {
|| scanner->current + 1 < scanner->table + scanner->tokens)
/* Scanner table accessors and mutators */
/** @name Scanner table accessors and mutators
* @{ */
/* Checks the type of the next token */
/** Checks the type of the next token */
#define check_next_scanner_token(scanner, token_type) \
(scanner_has_tokens(scanner) \
&& ((scanner)->current + 1 < (scanner)->table + (scanner)->tokens) \
&& (scanner)->current[1].type == (token_type))
/* Access current and next token. Getting the next token might cause
/** Access current and next token. Getting the next token might cause
* a rescan so any token pointers that has been stored in a local variable
* might not be valid after the call. */
static inline struct scanner_token *
@ -156,7 +158,7 @@ get_scanner_token(struct scanner *scanner)
return scanner_has_tokens(scanner) ? scanner->current : NULL;
}
/* Do a scanning if we do not have also have access to next token. */
/** Do a scanning if we do not have also have access to next token. */
static inline struct scanner_token *
get_next_scanner_token(struct scanner *scanner)
{
@ -165,16 +167,18 @@ get_next_scanner_token(struct scanner *scanner)
? scanner->info->scan(scanner) : get_scanner_token(scanner));
}
/* This should just make the code more understandable .. hopefully */
/** This should just make the code more understandable .. hopefully */
#define skip_scanner_token(scanner) get_next_scanner_token(scanner)
/* Removes tokens from the scanner until it meets a token of the given type.
/** Removes tokens from the scanner until it meets a token of the given type.
* This token will then also be skipped. */
struct scanner_token *
skip_scanner_tokens(struct scanner *scanner, int skipto, int precedence);
/* Looks up the string from @ident to @end to in the scanners string mapping
* table */
/** @} */
/** Looks up the string from @a ident to @a end to in the scanners
* string mapping table */
int
map_scanner_string(struct scanner *scanner,
unsigned char *ident, unsigned char *end, int base_type);
@ -185,9 +189,8 @@ void dump_scanner(struct scanner *scanner);
/* The begin_token_scanning() and end_token_scanning() functions provide the
* basic setup and teardown for the rescan function made public via the
* scanner_info->scan member. */
/* Returns NULL if it is not necessary to try to scan for more tokens */
* scanner_info->scan member.
* @returns NULL if it is not necessary to try to scan for more tokens */
static inline struct scanner_token *
begin_token_scanning(struct scanner *scanner)
{
@ -221,10 +224,11 @@ begin_token_scanning(struct scanner *scanner)
return table;
}
/* Updates the @scanner struct after scanning has been done. The position
* _after_ the last valid token is taken as the @end argument. */
/* It is ok for @end to be < scanner->table since scanner->tokens will become
* <= 0 anyway. */
/* Updates the @a scanner struct after scanning has been done. The position
* _after_ the last valid token is taken as the @a end argument.
*
* It is ok for @a end to be < scanner->table since scanner->tokens
* will become <= 0 anyway. */
static inline struct scanner_token *
end_token_scanning(struct scanner *scanner, struct scanner_token *end)
{

17
src/util/secsave.c
View File

@ -1,4 +1,5 @@
/* Secure file saving handling */
/** Secure file saving handling
* @file */
#ifdef HAVE_CONFIG_H
#include "config.h"
@ -67,8 +68,8 @@
enum secsave_errno secsave_errno = SS_ERR_NONE;
/* Open a file for writing in a secure way. It returns a pointer to a structure
* secure_save_info on success, or NULL on failure. */
/** Open a file for writing in a secure way. @returns a pointer to a
* structure secure_save_info on success, or NULL on failure. */
static struct secure_save_info *
secure_open_umask(unsigned char *file_name)
{
@ -219,8 +220,8 @@ secure_open(unsigned char *file_name)
return ssi;
}
/* Close a file opened with secure_open, and return 0 on success, errno
* or -1 on failure. */
/** Close a file opened with secure_open(). @returns 0 on success,
* errno or -1 on failure. */
int
secure_close(struct secure_save_info *ssi)
{
@ -298,7 +299,7 @@ free:
}
/* fputs() wrapper, set ssi->err to errno on error. If ssi->err is set when
/** fputs() wrapper, set ssi->err to errno on error. If ssi->err is set when
* called, it immediatly returns EOF. */
int
secure_fputs(struct secure_save_info *ssi, const char *s)
@ -317,7 +318,7 @@ secure_fputs(struct secure_save_info *ssi, const char *s)
}
/* fputc() wrapper, set ssi->err to errno on error. If ssi->err is set when
/** fputc() wrapper, set ssi->err to errno on error. If ssi->err is set when
* called, it immediatly returns EOF. */
int
secure_fputc(struct secure_save_info *ssi, int c)
@ -335,7 +336,7 @@ secure_fputc(struct secure_save_info *ssi, int c)
return ret;
}
/* fprintf() wrapper, set ssi->err to errno on error and return a negative
/** fprintf() wrapper, set ssi->err to errno on error and return a negative
* value. If ssi->err is set when called, it immediatly returns -1. */
int
secure_fprintf(struct secure_save_info *ssi, const char *format, ...)

19
src/util/secsave.h
View File

@ -1,4 +1,5 @@
/* Secure file saving handling */
/** Secure file saving handling
* @file */
#ifndef EL__UTIL_SECSAVE_H
#define EL__UTIL_SECSAVE_H
@ -10,8 +11,8 @@ struct terminal;
enum secsave_errno {
SS_ERR_NONE = 0,
SS_ERR_DISABLED, /* secsave is disabled. */
SS_ERR_OUT_OF_MEM, /* memory allocation failure */
SS_ERR_DISABLED, /**< secsave is disabled. */
SS_ERR_OUT_OF_MEM, /**< memory allocation failure */
/* see err field in struct secure_save_info */
SS_ERR_OPEN_READ,
@ -23,14 +24,14 @@ enum secsave_errno {
SS_ERR_OTHER,
};
extern enum secsave_errno secsave_errno; /* internal secsave error number */
extern enum secsave_errno secsave_errno; /**< internal secsave error number */
struct secure_save_info {
FILE *fp; /* file stream pointer */
unsigned char *file_name; /* final file name */
unsigned char *tmp_file_name; /* temporary file name */
int err; /* set to non-zero value in case of error */
int secure_save; /* use secure save for this file */
FILE *fp; /**< file stream pointer */
unsigned char *file_name; /**< final file name */
unsigned char *tmp_file_name; /**< temporary file name */
int err; /**< set to non-zero value in case of error */
int secure_save; /**< use secure save for this file */
};
struct secure_save_info *secure_open(unsigned char *);

5
src/util/string.c
View File

@ -1,4 +1,5 @@
/* String handling functions */
/** String handling functions
* @file */
#ifdef HAVE_CONFIG_H
#include "config.h"
@ -432,7 +433,7 @@ add_xchar_to_string(struct string *string, unsigned char character, int times)
return string;
}
/* Add printf-like format string to @string. */
/** Add printf()-style format string to @a string. */
struct string *
add_format_to_string(struct string *string, const unsigned char *format, ...)
{

100
src/util/string.h
View File

@ -16,20 +16,22 @@
#ifndef DEBUG_MEMLEAK
/* Autoallocation string constructors: */
/* Note that, contrary to the utilities using the string struct, these
/** @name Autoallocation string constructors:
* Note that, contrary to the utilities using the string struct, these
* functions are NOT granular, thus you can't simply reuse strings allocated by
* these in add_to_string()-style functions. */
* these in add_to_string()-style functions.
* @{ */
/* Allocates NUL terminated string with @len bytes from @src.
* If @src == NULL or @len < 0 only one byte is allocated and set it to 0. */
/* Returns the string or NULL on allocation failure. */
/** Allocates NUL terminated string with @a len bytes from @a src.
* If @a src == NULL or @a len < 0 only one byte is allocated and set it to 0.
* @returns the string or NULL on allocation failure. */
unsigned char *memacpy(const unsigned char *src, int len);
/* Allocated NUL terminated string with the content of @src. */
/** Allocated NUL terminated string with the content of @a src. */
unsigned char *stracpy(const unsigned char *src);
/** @} */
#else /* DEBUG_MEMLEAK */
unsigned char *debug_memacpy(const unsigned char *, int, const unsigned char *, int);
@ -41,60 +43,69 @@ unsigned char *debug_stracpy(const unsigned char *, int, const unsigned char *);
#endif /* DEBUG_MEMLEAK */
/* Concatenates @src to @str. */
/* If reallocation of @str fails @str is not touched. */
/** Concatenates @a src to @a str.
* If reallocation of @a str fails @a str is not touched. */
void add_to_strn(unsigned char **str, const unsigned char *src);
/* Inserts @seqlen chars from @seq at position @pos in the @dst string. */
/* If reallocation of @dst fails it is not touched and NULL is returned. */
/** Inserts @a seqlen chars from @a seq at position @a pos in the @a
* dst string.
* If reallocation of @a dst fails it is not touched and NULL is returned. */
unsigned char *insert_in_string(unsigned char **dst, int pos,
const unsigned char *seq, int seqlen);
/* Takes a list of strings where the last parameter _must_ be
* (unsigned char *) NULL and concatenates them. */
/* Returns the allocated string or NULL on allocation failure. */
/* Example:
/** Takes a list of strings where the last parameter _must_ be
* (unsigned char *) NULL and concatenates them.
*
* @returns the allocated string or NULL on allocation failure.
*
* Example: @code
* unsigned char *abc = straconcat("A", "B", "C", (unsigned char *) NULL);
* if (abc) return;
* printf("%s", abc); -> print "ABC"
* mem_free(abc); -> free memory used by @abc */
* mem_free(abc); -> free memory used by @abc
* @endcode */
unsigned char *straconcat(const unsigned char *str, ...);
/* Misc. utility string functions. */
/** @name Misc. utility string functions.
* @{ */
/* Compare two strings, handling correctly @s1 or @s2 being NULL. */
/** Compare two strings, handling correctly @a s1 or @a s2 being NULL. */
int xstrcmp(const unsigned char *s1, const unsigned char *s2);
/* Copies at most @len chars into @dst. Ensures null termination of @dst. */
/** Copies at most @a len chars into @a dst. Ensures null termination of @a dst. */
unsigned char *safe_strncpy(unsigned char *dst, const unsigned char *src, size_t len);
/* strlcmp() is the middle child of history, everyone is using it differently.
* On some weird *systems* it seems to be defined (equivalent to strcasecmp()),
* so we'll better use our #define redir. */
/* This routine compares string @s1 of length @n1 with string @s2 of length
* @n2.
/** This routine compares string @a s1 of length @a n1 with string @a s2
* of length @a n2.
*
* This acts identically to strcmp() but for non-zero-terminated strings,
* rather than being similiar to strncmp(). That means, it fails if @n1 != @n2,
* thus you may use it for testing whether @s2 matches *full* @s1, not only its
* start (which can be a security hole, ie. in the cookies domain checking).
* rather than being similiar to strncmp(). That means, it fails if @a n1
* != @a n2, thus you may use it for testing whether @a s2 matches *full*
* @a s1, not only its start (which can be a security hole, e.g. in the
* cookies domain checking).
*
* @n1 or @n2 may be -1, which is same as strlen(@s[12]) but possibly more
* effective (in the future ;-). */
/* Returns zero if the strings match or undefined non-zero value if they
* @a n1 or @a n2 may be -1, which is same as strlen(@a s1 or @a s2) but
* possibly more effective (in the future ;-).
*
* @returns zero if the strings match or undefined non-zero value if they
* differ. (The non-zero return value is _not_ same as for the standard
* strcmp() family.) */
#define strlcmp(a,b,c,d) (errfile = __FILE__, errline = __LINE__, elinks_strlcmp(a,b,c,d))
int elinks_strlcmp(const unsigned char *s1, size_t n1,
const unsigned char *s2, size_t n2);
/* Acts identically to strlcmp(), except for being case insensitive. */
/** Acts identically to strlcmp(), except for being case insensitive. */
#define strlcasecmp(a,b,c,d) (errfile = __FILE__, errline = __LINE__, elinks_strlcasecmp(a,b,c,d))
int elinks_strlcasecmp(const unsigned char *s1, size_t n1,
const unsigned char *s2, size_t n2);
/** @} */
#define skip_space(S) \
do { while (isspace(*(S))) (S)++; } while (0)
@ -109,16 +120,16 @@ int elinks_strlcasecmp(const unsigned char *s1, size_t n1,
#define isasciialnum(c) (isasciialpha(c) || isdigit(c))
#define isident(c) (isasciialnum(c) || (c) == '_' || (c) == '-')
/* Char is safe to write to the terminal screen. Cannot test for C1
/** Char is safe to write to the terminal screen. Cannot test for C1
* control characters (0x80 to 0x9F) because this is also used for
* non-ISO-8859 charsets. */
#define isscreensafe(c) ((c) >= ' ' && (c) != ASCII_DEL)
/* Like isscreensafe but takes Unicode values and so can check for C1. */
/** Like isscreensafe() but takes Unicode values and so can check for C1. */
#define isscreensafe_ucs(c) (((c) >= 0x20 && (c) <= 0x7E) || (c) >= 0xA0)
/* String debugging using magic number, it may catch some errors. */
/** String debugging using magic number, it may catch some errors. */
#ifdef CONFIG_DEBUG
#define DEBUG_STRING
#endif
@ -132,7 +143,7 @@ struct string {
};
/* The granularity used for the struct string based utilities. */
/** The granularity used for the struct string based utilities. */
#define STRING_GRANULARITY 0xFF
#ifdef DEBUG_STRING
@ -148,7 +159,10 @@ struct string {
#define INIT_STRING(s, l) { s, l }
#endif
/* Initializes the passed string struct by preallocating the @source member. */
/** Initializes the passed string struct by preallocating the
* string.source member.
* @returns @a string if successful, or NULL if out of memory.
* @post done_string(@a string) is safe, even if this returned NULL. */
#ifdef DEBUG_MEMLEAK
struct string *init_string__(const unsigned char *file, int line, struct string *string);
#define init_string(string) init_string__(__FILE__, __LINE__, string)
@ -156,7 +170,7 @@ struct string *init_string__(const unsigned char *file, int line, struct string
struct string *init_string(struct string *string);
#endif
/* Resets @string and free()s the @source member. */
/** Resets @a string and free()s the string.source member. */
void done_string(struct string *string);
@ -167,17 +181,17 @@ struct string *add_string_to_string(struct string *to, const struct string *from
struct string *add_file_to_string(struct string *string, const unsigned char *filename);
struct string *add_crlf_to_string(struct string *string);
/* Adds each C string to @string until a terminating
/** Adds each C string to @a string until a terminating
* (unsigned char *) NULL is met. */
struct string *string_concat(struct string *string, ...);
/* Extends the string with @times number of @character. */
/** Extends the string with @a times number of @a character. */
struct string *add_xchar_to_string(struct string *string, unsigned char character, int times);
/* Add printf-style format string to @string. */
/** Add printf()-style format string to @a string. */
struct string *add_format_to_string(struct string *string, const unsigned char *format, ...);
/* Get a regular newly allocated stream of bytes from @string. */
/** Get a regular newly allocated stream of bytes from @a string. */
static unsigned char *squeezastring(struct string *string);
@ -247,8 +261,8 @@ struct string_list_item {
struct string string;
};
/* Adds @string with @length chars to the list. If length is -1 it will be set
* to the return value of strlen(). */
/** Adds @a string with @a length chars to the list. If @a length is -1
* it will be set to the return value of strlen(). */
struct string *
add_to_string_list(LIST_OF(struct string_list_item) *list,
const unsigned char *string, int length);
@ -256,10 +270,10 @@ add_to_string_list(LIST_OF(struct string_list_item) *list,
void free_string_list(LIST_OF(struct string_list_item) *list);
/* Returns an empty C string or @str if different from NULL. */
/** Returns an empty C string or @a str if different from NULL. */
#define empty_string_or_(str) ((str) ? (unsigned char *) (str) : (unsigned char *) "")
/* Allocated copy if not NULL or returns NULL. */
/** Allocated copy if not NULL or returns NULL. */
#define null_or_stracpy(str) ((str) ? stracpy(str) : NULL)
#endif /* EL__UTIL_STRING_H */

20
src/util/time.c
View File

@ -1,4 +1,5 @@
/* Time operations */
/** Time operations
* @file */
#ifdef HAVE_CONFIG_H
#include "config.h"
@ -17,7 +18,7 @@
#include "util/error.h"
#include "util/time.h"
/* Get the current time.
/** Get the current time.
* It attempts to use available functions, granularity
* may be as worse as 1 second if time() is used. */
timeval_T *
@ -45,7 +46,7 @@ timeval_now(timeval_T *t)
return t;
}
/* Subtract an interval to a timeval, it ensures that
/** Subtract an interval to a timeval, it ensures that
* result is never negative. */
timeval_T *
timeval_sub_interval(timeval_T *t, timeval_T *interval)
@ -134,7 +135,7 @@ timeval_from_milliseconds(timeval_T *t, milliseconds_T milliseconds)
return t;
}
/* Bug 923: Assumes time_t values fit in long. (This function is used
/** @bug 923: Assumes time_t values fit in long. (This function is used
* for both timestamps and durations.) */
timeval_T *
timeval_from_seconds(timeval_T *t, long seconds)
@ -186,7 +187,7 @@ timeval_to_milliseconds(timeval_T *t)
return add_ms_to_ms(a, b);
}
/* Bug 923: Assumes time_t values fit in long. (This function is used
/** @bug 923: Assumes time_t values fit in long. (This function is used
* for both timestamps and durations.) */
long
timeval_to_seconds(timeval_T *t)
@ -200,7 +201,7 @@ timeval_is_positive(timeval_T *t)
return (t->sec > 0 || (t->sec == 0 && t->usec > 0));
}
/* Be sure timeval is not negative. */
/** Be sure timeval is not negative. */
void
timeval_limit_to_zero_or_one(timeval_T *t)
{
@ -212,9 +213,10 @@ timeval_limit_to_zero_or_one(timeval_T *t)
#endif
}
/* Returns 1 if t1 > t2
* -1 if t1 < t2
* 0 if t1 == t2 */
/** Compare time values.
* @returns 1 if t1 > t2;
* -1 if t1 < t2;
* 0 if t1 == t2. */
int
timeval_cmp(timeval_T *t1, timeval_T *t2)
{

16
src/util/time.h
View File

@ -16,19 +16,19 @@ typedef long milliseconds_T;
#define ms_max(a, b) ((a) < (b) ? (b) : (a))
#define ms_min(a, b) ((a) < (b) ? (a) : (b))
/* Bug 923: Assumes time_t values fit in long. */
/** @bug 923: Assumes time_t values fit in @c long. */
#define str_to_time_t(s) ((time_t) atol(s))
/* When formatting time_t values to be parsed with str_to_time_t,
* we first cast to time_print_T and then printf the result with
* TIME_PRINT_FORMAT.
* Bug 923: Assumes time_t values fit in long. */
/** When formatting time_t values to be parsed with str_to_time_t(),
* we first cast to @c time_print_T and then printf() the result with
* ::TIME_PRINT_FORMAT.
* @bug 923: Assumes time_t values fit in @c long. */
typedef long time_print_T;
#define TIME_PRINT_FORMAT "ld"
#define TIME_PRINT_FORMAT "ld" /**< @see time_print_T */
/* Redefine a timeval that has all fields signed so calculations
/** Redefine a timeval that has all fields signed so calculations
* will be simplified on rare systems that define timeval with
* unsigned fields.
* Bug 923: Assumes time_t values fit in long. (This structure is
* @bug 923: Assumes time_t values fit in long. (This structure is
* used for both timestamps and durations.) */
typedef struct { long sec; long usec; } timeval_T;