struct Client;
-/* structure passed as argument for %v conversion */
+/** structure passed as argument for %v conversion */
struct VarData {
- size_t vd_chars; /* number of characters inserted */
- size_t vd_overflow; /* number of characters that couldn't be */
- const char *vd_format; /* format string */
- va_list vd_args; /* arguments for %v */
+ size_t vd_chars; /**< number of characters inserted */
+ size_t vd_overflow; /**< number of characters that couldn't be */
+ const char *vd_format; /**< format string */
+ va_list vd_args; /**< arguments for %v */
};
#ifndef HAVE_VA_COPY
#if HAVE___VA_COPY
#define va_copy(DEST, SRC) __va_copy(DEST, SRC)
#else
+/** Fallback macro to copy to \a DEST from \a SRC. */
#define va_copy(DEST, SRC) memcpy(&(DEST), &(SRC), sizeof(DEST))
#endif
#endif
extern int ircd_vsnprintf(struct Client *dest, char *buf, size_t buf_len,
const char *format, va_list args);
-/*
-** ircd_(v)snprintf
+/** @fn int ircd_snprintf(struct Client *dest, char *buf, size_t
+ buf_len, const char *format, ...)
**
** These functions are intended to be a complete replacement for
** sprintf and sprintf_irc. They are a (nearly) complete
** instance; %qu and %hhu are also supported. The extensions added
** for use in ircu are %Tu, which takes a time_t, and the new %C
** conversion, which inserts either a numeric or a nick, dependant on
-** the <dest> parameter. The GNU %m extension, which inserts the
+** the <dest> parameter. The GNU %m extension, which inserts the
** strerror() string corresponding to the current value of errno, is
** also supported, as is a special %v extension, which essentially
** does a recursive call to ircd_snprintf.
** correspond properly (after type promotion) with the conversion
** specifier. After the %, the following appear in sequence:
**
-** * Zero or more of the following flags:
+** <ul><li>Zero or more of the following flags:<dl>
**
-** # specifying that the value should be converted to an
+** <dt>#</dt>
+** <dd>specifying that the value should be converted to an
** "alternate form." For c, d, i, n, p, s, and u conversions,
** this option has no effect. For o conversions, the precision
** of the number is increased to force the first character of the
** conversions, trailing zeros are not removed from the result as
** they would otherwise be. For C conversions, if the
** destination is local and the origin is a user, the
-** nick!user@host form is used.
+** nick!user\@host form is used.</dd>
**
-** 0 specifying zero padding. For all conversions except n, the
+** <dt>0</dt>
+** <dd> specifying zero padding. For all conversions except n, the
** converted value is padded on the left with zeros rather than
** blanks. If a precision is given with a numeric conversion (d,
-** i, o, u, i, x, and X), the 0 flag is ignored.
+** i, o, u, i, x, and X), the 0 flag is ignored.</dd>
**
-** - (a negative field width flag) indicates the converted value is
+** <dt>-</dt>
+** <dd>(a negative field width flag) indicates the converted value is
** to be left adjusted on the field boundary. Except for n
** conversions, the converted value is padded on the right with
** blanks, rather than on the left with blanks or zeros. A -
-** overrides a 0 if both are given.
+** overrides a 0 if both are given.</dd>
**
-** ' ' (a space) specifying that a blank should be left before a
+** <dt>' ' (a space)</dt>
+** <dd>specifying that a blank should be left before a
** positive number produced by a signed conversion (d, e, E, f,
-** g, G, or i).
+** g, G, or i).</dd>
**
-** + specifying that a sign always be placed before a number
+** <dt>+</dt>
+** <dd>specifying that a sign always be placed before a number
** produced by a signed conversion. A + overrides a space if
-** both are used.
+** both are used.</dd>
**
-** : specifying that a struct Client name should be preceded by a
-** ':' character if the destination is a user
+** <dt>:</dt>
+** <dd>specifying that a struct Client name should be preceded by a
+** ':' character if the destination is a user.</dd>
+** </dl></li>
**
-** * An optional decimal digit string specifying a minimum field
+** <li>An optional decimal digit string specifying a minimum field
** width. If the converted value has fewer characters than the
** field width, it will be padded with spaces on the left (or right,
** if the left-adjustment flag has been given) to fill out the field
-** width.
+** width.</li>
**
-** * An optional precision, in the form of a period (`.') followed by
+** <li>An optional precision, in the form of a period (`.') followed by
** an optional digit string. If the digit string is omitted, the
** precision is taken as zero. This gives the minimum number of
** digits to appear for d, i, o, u, x, and X conversions, the number
** of digits to appear after the decimal-point for e, E, and f
** conversions, the maximum number of significant digits for g and G
** conversions, or the maximum number of characters to be printed
-** from a string for s conversions.
+** from a string for s conversions.</li>
**
-** * The optional character h, specifying that a following d, i, o, u,
+** <li>The optional character h, specifying that a following d, i, o, u,
** x, or X conversion corresponds to a short int or unsigned short
** int argument, or that a following n conversion corresponds to a
** pointer to a short int argument. If the h character is given
-** again, char is used instead of short int.
+** again, char is used instead of short int.</li>
**
-** * The optional character l (ell) specifying that a following d, i,
+** <li>The optional character l (ell) specifying that a following d, i,
** o, u, x, or X conversion applies to a pointer to a long int or
** unsigned long int argument, or that a following n conversion
-** corresponds to a pointer to a long int argument.
+** corresponds to a pointer to a long int argument.</li>
**
-** * The character L specifying that a following e, E, f, g, or G
+** <li>The character L specifying that a following e, E, f, g, or G
** conversion corresponds to a long double argument, or a following
** d, i, o, u, x, or X conversion corresponds to a long long
** argument. Note that long long is not specified in ANSI C and
-** therefore not portable to all architectures.
+** therefore not portable to all architectures.</li>
**
-** * The optional character q. This is equivalent to L.
+** <li>The optional character q. This is equivalent to L.</li>
**
-** * A j character specifying that the following integer (d, i, o, u,
-** x, or X) conversion corresponds to an intmax_t argument.
+** <li>A j character specifying that the following integer (d, i, o, u,
+** x, or X) conversion corresponds to an intmax_t argument.</li>
**
-** * A t character specifying that the following integer (d, i, o, u,
-** x, or X) conversion corresponds to a ptrdiff_t argument.
+** <li>A t character specifying that the following integer (d, i, o, u,
+** x, or X) conversion corresponds to a ptrdiff_t argument.</li>
**
-** * A z character specifying that the following integer (d, i, o, u,
-** x, or X) conversion corresponds to a size_t argument.
+** <li>A z character specifying that the following integer (d, i, o, u,
+** x, or X) conversion corresponds to a size_t argument.</li>
**
-** * A T character specifying that the following integer (d, i, o, u,
-** x, or X) conversion corresponds to a time_t argument.
+** <li>A T character specifying that the following integer (d, i, o, u,
+** x, or X) conversion corresponds to a time_t argument.</li>
**
-** * A character that specifies the type of conversion to be applied.
+** <li>A character that specifies the type of conversion to be applied.</li>
+** </ul>
**
** A field width or precision, or both, may be indicated by an
** asterisk `*' instead of a digit string. In this case, an int
**
** The conversion specifiers and their meanings are:
**
-** diouxX The int (or appropriate variant) argument is converted
+** <dl>
+** <dt>diouxX</dt>
+** <dd>The int (or appropriate variant) argument is converted
** to signed decimal (d and i), unsigned octal (o),
** unsigned decimal (u), or unsigned hexadecimal (x and
** X) notation. The letters abcdef are used for x
** conversions. The precision, if any, gives the minimum
** number of digits that must appear; if the converted
** value requires fewer digits, it is padded on the left
-** with zeros.
+** with zeros.</dd>
**
-** eE [NOT IMPLEMENTED] The double argument is rounded and
+** <dt>eE [NOT IMPLEMENTED]</dt>
+** <dd>The double argument is rounded and
** converted in the style [-]d.dddedd where there is one
** digit before the decimal-point character and the
** number of digits after it is equal to the precision;
** An E conversion uses the letter E (rather than e) to
** introduce the exponent. The exponent always contains
** at least two digits; if the value is zero, the
-** exponent is 00.
+** exponent is 00.</dd>
**
-** f [NOT IMPLEMENTED] The double argument is rounded and
+** <dt>f [NOT IMPLEMENTED]</dt>
+** <dd>The double argument is rounded and
** converted to decimal notation in the style
** [-]ddd.ddd, where the number of digits after the
** decimal-point character is equal to the precision
** specification. If the precision is missing, it is
** taken as 6; if the precision is explicitly zero, no
** decimal-point character appears. If a decimal point
-** appears, at least one digit appears before it.
+** appears, at least one digit appears before it.</dd>
**
-** g [NOT IMPLEMENTED] The double argument is converted in
+** <dt>g [NOT IMPLEMENTED]</dt>
+** <dd>The double argument is converted in
** style f or e (or E for G conversions). The precision
** specifies the number of significant digits. If the
** precision is missing, 6 digits are given; if the
** -4 or greater than or equal to the precision.
** Trailing zeros are removed from the fractional part of
** the result; a decimal point appears only if it is
-** followed by at least one digit.
+** followed by at least one digit.</dd>
**
-** c The int argument is converted to an unsigned char, and
-** the resulting character is written.
+** <dt>c</dt>
+** <dd>The int argument is converted to an unsigned char, and
+** the resulting character is written.</dd>
**
-** s The "char *" argument is expected to be a pointer to
+** <dt>s</dt>
+** <dd>The "char *" argument is expected to be a pointer to
** an array of character type (pointer to a string).
** Characters from the array are written up to (but not
** including) a terminating NUL character; if a precision
** written. If a precision is given, no null character
** need be present; if the precision is not specified, or
** is greater than the size of the array, the array must
-** contain a terminating NUL character.
+** contain a terminating NUL character.</dd>
**
-** p The "void *" pointer argument is printed in
-** hexadecimal (as if by %#x or %#lx).
+** <dt>p</dt>
+** <dd>The "void *" pointer argument is printed in
+** hexadecimal (as if by %#x or %#lx).</dd>
**
-** n The number of characters written so far is stored into
+** <dt>n</dt>
+** <dd>The number of characters written so far is stored into
** the integer indicated by the ``int *'' (or variant)
-** pointer argument. No argument is converted.
+** pointer argument. No argument is converted.</dd>
**
-** m The error message associated with the current value of
-** errno is printed as if by %s.
+** <dt>m</dt>
+** <dd>The error message associated with the current value of
+** errno is printed as if by %s.</dd>
**
-** C The client argument identifier is printed under the
-** control of the <dest> argument; if <dest> is NULL or
+** <dt>C</dt>
+** <dd>The client argument identifier is printed under the
+** control of the <dest> argument; if <dest> is NULL or
** is a user, the client's name (nickname or server name)
** is printed; otherwise, the client's network numeric is
-** printed.
+** printed.</dd>
**
-** H The channel argument identifier (channel name) is
-** printed.
+** <dt>H</dt>
+** <dd>The channel argument identifier (channel name) is
+** printed.</dd>
**
-** v The argument given must be a pointer to a struct
+** <dt>v</dt>
+** <dd>The argument given must be a pointer to a struct
** VarData with vd_format and vd_args must be initialized
** appropriately. On return, vd_chars will contain the
** number of characters added to the buffer, and
** vd_overflow will contain the number of characters that
** could not be added due to buffer overflow or due to a
-** precision.
+** precision.</dd>
**
-** % A `%' is written. No argument is converted. The
-** complete conversion specification is `%%'.
+** <dt>%<dt>
+** <dd>A `%' is written. No argument is converted. The
+** complete conversion specification is `%%'.</dd>
+** </dl>
**
** In no case does a non-existent or small field width cause
** truncation of a field; if the result of a conversion is wider than
** the field width, the field is expanded to contain the conversion
** result.
+**
+** @param[in] dest Client receiving of message.
+** @param[out] buf Output buffer for formatted message.
+** @param[in] buf_len Number of bytes that can be written to \a buf.
+** @param[in] format Format string for message.
+** @return Number of bytes that would be written to \a buf without truncation.
*/
#endif /* INCLUDED_ircd_snprintf_h */
#if defined(__GNUC__) && defined(HAVE_LONG_LONG)
# define EXTENSION __extension__
#else
+/** Fallback (empty) definition of EXTENSION. */
# define EXTENSION
#endif
# define HAVE_POINTER_T
# endif
#else
+/** Fallback definition of the largest integer type. */
typedef long _large_t;
+/** Fallback definition of the largest unsigned integer type. */
typedef unsigned long _ularge_t;
+/** Fallback definition of SIZEOF__LARGE_T. */
# define SIZEOF__LARGE_T SIZEOF_LONG
#endif
/* Select something for _pointer_t */
#ifndef HAVE_POINTER_T
# if SIZEOF_LONG == SIZEOF_VOID_P
+/** Unsigned integer type large enough to hold a pointer. */
typedef unsigned long _pointer_t;
# elif SIZEOF_INT == SIZEOF_VOID_P
typedef unsigned int _pointer_t;
# endif
#endif /* HAVE_POINTER_T */
-/* rough length sufficient to hold an octal number, since those can be large */
+/** rough length sufficient to hold an octal number, since those can be large */
#define INTBUF_LEN (SIZEOF__LARGE_T * 3)
+/** Return minimum of \a i1 and \a i2. */
#define SNP_MIN(i1, i2) ((i1) < (i2) ? (i1) : (i2))
+/** Return maximum of \a i1 and \a i2. */
#define SNP_MAX(i1, i2) ((i1) > (i2) ? (i1) : (i2))
+/** Indicate total number of bytes "pseudo-output" in buffer. */
#define TOTAL(buf_p) ((buf_p)->buf_loc + \
SNP_MAX((buf_p)->buf_overflow, (buf_p)->overflow))
-#define WIDTH_MAX 999 /* keep from overflowing width */
+#define WIDTH_MAX 999 /**< keep from overflowing width */
-/* data about the buffer */
+/** data about the output buffer */
struct BufData {
- char *buf; /* pointer to buffer */
- size_t buf_size; /* maximum size of buffer */
- size_t buf_overflow; /* how much buffer has been overflowed */
- size_t buf_loc; /* where we are in the buffer */
- short limit; /* max # of chars to convert */
- size_t overflow; /* how much we overflowed the limit */
+ char *buf; /**< pointer to buffer */
+ size_t buf_size; /**< maximum size of buffer */
+ size_t buf_overflow; /**< how much buffer has been overflowed */
+ size_t buf_loc; /**< where we are in the buffer */
+ short limit; /**< max # of chars to convert */
+ size_t overflow; /**< how much we overflowed the limit */
};
+/** initializer for BufData */
#define BUFDATA_INIT { 0, 0, 0, 0, 0, 0 }
-/* data about the fields */
+/** data about format fields */
struct FieldData {
- unsigned int flags; /* flags describing argument */
- short base; /* base for integer conversions */
- short width; /* width of field */
- short prec; /* precision of field */
+ unsigned int flags; /**< flags describing argument */
+ short base; /**< base for integer conversions */
+ short width; /**< width of field */
+ short prec; /**< precision of field */
union {
- _ularge_t v_int; /* an integer value */
- long double v_float; /* a floating point value -- NOT SUPPORTED */
- void *v_ptr; /* a pointer value */
- } value; /* value of a field */
+ _ularge_t v_int; /**< an integer value */
+ long double v_float; /**< a floating point value -- NOT SUPPORTED */
+ void *v_ptr; /**< a pointer value */
+ } value; /**< value of a field */
};
+/** initializer for FieldData */
#define FIELDDATA_INIT { 0, 0, 0, 0, { 0 } }
/* Specifier flags */
-#define FLAG_MINUS 0x00000001 /* found a '-' flag */
-#define FLAG_PLUS 0x00000002 /* found a '+' flag */
-#define FLAG_SPACE 0x00000004 /* found a ' ' flag */
-#define FLAG_ALT 0x00000008 /* found a '#' flag */
-#define FLAG_ZERO 0x00000010 /* found a '0' flag */
-#define FLAG_COLON 0x00000020 /* found a ':' flag */
+#define FLAG_MINUS 0x00000001 /**< found a '-' flag */
+#define FLAG_PLUS 0x00000002 /**< found a '+' flag */
+#define FLAG_SPACE 0x00000004 /**< found a ' ' flag */
+#define FLAG_ALT 0x00000008 /**< found a '#' flag */
+#define FLAG_ZERO 0x00000010 /**< found a '0' flag */
+#define FLAG_COLON 0x00000020 /**< found a ':' flag */
-#define FLAG_RESERVED1 0x00000040 /* reserved for future expansion */
-#define FLAG_RESERVED0 0x00000080
+#define FLAG_RESERVED1 0x00000040 /**< reserved for future expansion */
+#define FLAG_RESERVED0 0x00000080 /**< reserved for future expansion */
/* integer types */
-#define TYPE_CHAR 0x00000100 /* number is a char */
-#define TYPE_SHORT 0x00000200 /* number is a short */
-#define TYPE_LONG 0x00000400 /* number is a long */
-#define TYPE_QUAD 0x00000800 /* number is a quad */
+#define TYPE_CHAR 0x00000100 /**< number is a char */
+#define TYPE_SHORT 0x00000200 /**< number is a short */
+#define TYPE_LONG 0x00000400 /**< number is a long */
+#define TYPE_QUAD 0x00000800 /**< number is a quad */
/* special integer types */
-#define TYPE_INTMAX 0x00001000 /* number is an intmax_t */
-#define TYPE_PTRDIFF 0x00002000 /* number is a ptrdiff_t */
-#define TYPE_SIZE 0x00004000 /* number is a size_t */
-#define TYPE_TIME 0x00008000 /* number is a time_t */
-#define TYPE_POINTER 0x00010000 /* number is a pointer_t */
+#define TYPE_INTMAX 0x00001000 /**< number is an intmax_t */
+#define TYPE_PTRDIFF 0x00002000 /**< number is a ptrdiff_t */
+#define TYPE_SIZE 0x00004000 /**< number is a size_t */
+#define TYPE_TIME 0x00008000 /**< number is a time_t */
+#define TYPE_POINTER 0x00010000 /**< number is a pointer_t */
/* floating point types */
-#define TYPE_LONGDOUBLE 0x00020000 /* number is a long double */
+#define TYPE_LONGDOUBLE 0x00020000 /**< number is a long double */
-#define TYPE_RESERVED1 0x00040000 /* reserved for future expansion */
-#define TYPE_RESERVED0 0x00080000
+#define TYPE_RESERVED1 0x00040000 /**< reserved for future expansion */
+#define TYPE_RESERVED0 0x00080000 /**< reserved for future expansion */
-/* Mask to get just the type data */
+/** Mask to get just the type data */
#define TYPE_MASK (TYPE_CHAR | TYPE_SHORT | TYPE_LONG | TYPE_QUAD | \
TYPE_INTMAX | TYPE_PTRDIFF | TYPE_SIZE | TYPE_TIME | \
TYPE_POINTER | TYPE_LONGDOUBLE)
/* type of argument to extract */
-#define ARG_INT 0x00100000 /* argument is an integer */
-#define ARG_FLOAT 0x00200000 /* argument is a float */
-#define ARG_PTR 0x00300000 /* argument is a pointer */
-
-#define ARG_RESERVED11 0x00400000 /* reserved for future expansion */
-#define ARG_RESERVED10 0x00500000
-#define ARG_RESERVED9 0x00600000
-#define ARG_RESERVED8 0x00700000
-#define ARG_RESERVED7 0x00800000
-#define ARG_RESERVED6 0x00900000
-#define ARG_RESERVED5 0x00a00000
-#define ARG_RESERVED4 0x00b00000
-#define ARG_RESERVED3 0x00c00000
-#define ARG_RESERVED2 0x00d00000
-#define ARG_RESERVED1 0x00e00000
-#define ARG_RESERVED0 0x00f00000
+#define ARG_INT 0x00100000 /**< argument is an integer */
+#define ARG_FLOAT 0x00200000 /**< argument is a float */
+#define ARG_PTR 0x00300000 /**< argument is a pointer */
+
+#define ARG_RESERVED11 0x00400000 /**< reserved for future expansion */
+#define ARG_RESERVED10 0x00500000 /**< reserved for future expansion */
+#define ARG_RESERVED9 0x00600000 /**< reserved for future expansion */
+#define ARG_RESERVED8 0x00700000 /**< reserved for future expansion */
+#define ARG_RESERVED7 0x00800000 /**< reserved for future expansion */
+#define ARG_RESERVED6 0x00900000 /**< reserved for future expansion */
+#define ARG_RESERVED5 0x00a00000 /**< reserved for future expansion */
+#define ARG_RESERVED4 0x00b00000 /**< reserved for future expansion */
+#define ARG_RESERVED3 0x00c00000 /**< reserved for future expansion */
+#define ARG_RESERVED2 0x00d00000 /**< reserved for future expansion */
+#define ARG_RESERVED1 0x00e00000 /**< reserved for future expansion */
+#define ARG_RESERVED0 0x00f00000 /**< reserved for future expansion */
/* Mask to get just the argument data */
-#define ARG_MASK 0x00f00000
+#define ARG_MASK 0x00f00000 /**< masks off non-argument bits */
/* type of conversion to perform */
-#define CONV_INT 0x01000000 /* convert integers */
-#define CONV_FLOAT 0x02000000 /* convert floats */
-#define CONV_CHAR 0x03000000 /* convert chars */
-#define CONV_STRING 0x04000000 /* convert strings */
-#define CONV_VARARGS 0x05000000 /* convert a %v */
-#define CONV_CLIENT 0x06000000 /* convert a struct Client */
-#define CONV_CHANNEL 0x07000000 /* convert a struct Channel */
-
-#define CONV_RESERVED7 0x08000000 /* reserved for future expansion */
-#define CONV_RESERVED6 0x09000000
-#define CONV_RESERVED5 0x0a000000
-#define CONV_RESERVED4 0x0b000000
-#define CONV_RESERVED3 0x0c000000
-#define CONV_RESERVED2 0x0d000000
-#define CONV_RESERVED1 0x0e000000
-#define CONV_RESERVED0 0x0f000000
+#define CONV_INT 0x01000000 /**< convert integers */
+#define CONV_FLOAT 0x02000000 /**< convert floats */
+#define CONV_CHAR 0x03000000 /**< convert chars */
+#define CONV_STRING 0x04000000 /**< convert strings */
+#define CONV_VARARGS 0x05000000 /**< convert a %v */
+#define CONV_CLIENT 0x06000000 /**< convert a struct Client */
+#define CONV_CHANNEL 0x07000000 /**< convert a struct Channel */
+
+#define CONV_RESERVED7 0x08000000 /**< reserved for future expansion */
+#define CONV_RESERVED6 0x09000000 /**< reserved for future expansion */
+#define CONV_RESERVED5 0x0a000000 /**< reserved for future expansion */
+#define CONV_RESERVED4 0x0b000000 /**< reserved for future expansion */
+#define CONV_RESERVED3 0x0c000000 /**< reserved for future expansion */
+#define CONV_RESERVED2 0x0d000000 /**< reserved for future expansion */
+#define CONV_RESERVED1 0x0e000000 /**< reserved for future expansion */
+#define CONV_RESERVED0 0x0f000000 /**< reserved for future expansion */
/* Mask to get just the conversion data */
-#define CONV_MASK 0x0f000000
+#define CONV_MASK 0x0f000000 /**< masks off non-conversion bits */
/* Value information flags */
-#define INFO_RESERVED0 0x10000000 /* reserved for future expansion */
-#define INFO_UPPERCASE 0x20000000 /* use uppercase characters */
-#define INFO_UNSIGNED 0x40000000 /* number is unsigned */
-#define INFO_NEGATIVE 0x80000000 /* number is negative */
+#define INFO_RESERVED0 0x10000000 /**< reserved for future expansion */
+#define INFO_UPPERCASE 0x20000000 /**< use uppercase characters */
+#define INFO_UNSIGNED 0x40000000 /**< number is unsigned */
+#define INFO_NEGATIVE 0x80000000 /**< number is negative */
-#define BASE_OCTAL 9 /* octal base; bits-per-char * 3 */
-#define BASE_DECIMAL -1000 /* decimal base; 10 ** 3 */
-#define BASE_HEX 12 /* hexadecimal base; bits-per-char * 3 */
+#define BASE_OCTAL 9 /**< octal base; bits-per-char * 3 */
+#define BASE_DECIMAL -1000 /**< decimal base; 10 ** 3 */
+#define BASE_HEX 12 /**< hexadecimal base; bits-per-char * 3 */
/* padding... 1 2 3 4 5 */
/* 12345678901234567890123456789012345678901234567890 */
+/** Predefined space padding. */
static char spaces[] = " ";
+/** Predefined zero padding. */
static char zeros[] = "00000000000000000000000000000000000000000000000000";
+/** Length of predefined padding strings. */
#define PAD_LENGTH (sizeof(spaces) - 1)
/*
* course, a reason for this; check out how they're built in doprintf.
*/
-/* string table for octal values */
+/** string table for octal values */
static char *octal[] = {
"", "1", "2", "3", "4", "5", "6", "7",
"01", "11", "21", "31", "41", "51", "61", "71",
"077", "177", "277", "377", "477", "577", "677", "777"
};
-/* string table for decimal values */
+/** string table for decimal values */
static char *decimal[] = {
"", "1", "2", "3", "4", "5", "6", "7", "8", "9",
"01", "11", "21", "31", "41", "51", "61", "71", "81", "91",
"099", "199", "299", "399", "499", "599", "699", "799", "899", "999"
};
-/* string table for lower-case hexadecimal values */
+/** string table for lower-case hexadecimal values */
static char *hex[] = {
"", "1", "2", "3", "4", "5", "6", "7",
"8", "9", "a", "b", "c", "d", "e", "f",
"8ff", "9ff", "aff", "bff", "cff", "dff", "eff", "fff"
};
-/* string table for upper-case hexadecimal values */
+/** string table for upper-case hexadecimal values */
static char *HEX[] = {
"", "1", "2", "3", "4", "5", "6", "7",
"8", "9", "A", "B", "C", "D", "E", "F",
"8FF", "9FF", "AFF", "BFF", "CFF", "DFF", "EFF", "FFF"
};
-/* Add a character to the buffer */
+/** Append a single character to an output buffer.
+ * @param[in,out] buf_p Buffer to append to.
+ * @param[in] c Character to append.
+ */
static void
addc(struct BufData *buf_p, int c)
{
buf_p->buf[buf_p->buf_loc++] = c;
}
-/* Add a string to the buffer */
+/** Append a string to an output buffer.
+ * @param[in,out] buf_p Buffer to append to.
+ * @param[in] s_len Length of string to append.
+ * @param[in] s String to append.
+ */
static void
adds(struct BufData *buf_p, int s_len, const char *s)
{
}
}
-/* Add padding */
+/** Add certain padding to an output buffer.
+ * @param[in,out] buf_p Buffer to append to.
+ * @param[in] padlen Length of padding to add.
+ * @param[in] pad Padding string (at least PAD_LENGTH bytes long).
+ */
static void
do_pad(struct BufData *buf_p, int padlen, char *pad)
{
adds(buf_p, padlen, pad);
}
-/* Find string length up to maxlen */
+/** Return length of string, up to a maximum.
+ * @param[in] str String to find length for.
+ * @param[in] maxlen Maximum value to return.
+ * @return Minimum of \a maxlen and length of \a str.
+ */
static int
my_strnlen(const char *str, int maxlen)
{
return len;
}
-/* the function that actually puts it all together */
+/** Workhorse printing function.
+ * @param[in] dest Client to format the message.
+ * @param[in,out] buf_p Description of output buffer.
+ * @param[in] fmt Message format string.
+ * @param[in] vp Variable-length argument list for format string.
+ */
static void
doprintf(struct Client *dest, struct BufData *buf_p, const char *fmt,
va_list vp)
} /* for (; *fmt; fmt++) { */
}
+/* ircd_snprintf() has a big Doxygen comment in the header file. */
int
ircd_snprintf(struct Client *dest, char *buf, size_t buf_len,
const char *format, ...)
return TOTAL(&buf_s);
}
+/** Like ircd_snprintf() but with a va_list argument list.
+ * @param[in] dest Client receiving of message.
+ * @param[out] buf Output buffer for formatted message.
+ * @param[in] buf_len Number of bytes that can be written to \a buf.
+ * @param[in] format Format string for message.
+ * @param[in] args Variable-length argument list for format string.
+ * @return Number of bytes that would be written to \a buf without truncation.
+ */
int
ircd_vsnprintf(struct Client *dest, char *buf, size_t buf_len,
const char *format, va_list args)