sync undernet upstream ircu changes.

[irc/quakenet/snircd.git] / doc / api / ircd_snprintf.txt

These functions are intended to be a complete replacement for sprintf
and sprintf_irc.  They are a (nearly) complete reimplementation, and
of course they're snprintf clones, making it more difficult for
accidental buffer overflows to crop up.

First off, what's missing?  These functions support all ANSI C
conversion specifiers and selected ones from ISO 9x, with the
exception of all floating-point conversions.  The floating-point
conversions are tricky, and will likely be dependent on the
representation of a floating-point number on a particular
architecture.  While that representation is likely to conform to some
standard, it is not currently used in ircu, so seemed like a good
thing to omit, given the difficulty of implementing it.

There are two more things missing from this implementation that would
be required by ANSI; the first is support for multibyte character
strings, and the second is support for locales, neither of which have
any relevance for ircu, so again omission seemed to be a good policy.
Additionally, %#x always causes '0x' (or '0X') to be printed, even if
the number is zero.

These functions also have some extensions not seen in a
standards-compliant implementation; technically, the ISO 9x extensions
fall into this category, for instance.  The ISO 9x extensions
supported are type extensions--%ju, %tu, and %zu, for 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, dependent on 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.

The following description is descended from the Linux man page for the
printf family of functions.

The format string is composed of zero or more directives: ordinary
characters (not %), which are copied unchanged to the output stream;
and conversion specifications, each of which results in fetching zero
or more subsequent arguments.  Each conversion specification is
introduced by the character %.  The arguments must correspond properly
(after type promotion) with the conversion specifier.  After the %,
the following appear in sequence:

* Zero or more of the following flags:

  #	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 output string
	to a zero (except if a zero value is printed with an explicit
	precision of zero).  For x and X conversions, the string '0x'
	(or '0X' for X conversions) is prepended to it.  For e, E, f,
	g, and G conversions, the result will always contain a decimal
	point, even if no digits follow it (normally, a decimal point
	appears in the results of those conversions only if a digit
	follows).  For g and G 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.

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

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

 ' '	(a space) specifying that a blank should be left before a
	positive number produced by a signed conversion (d, e, E, f,
	g, G, or i).

  +	specifying that a sign always be placed before a number
	produced by a signed conversion.  A + overrides a space if
	both are used.

  :	specifying that a struct Client name should be preceded by a
	':' character if the destination is a user

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

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

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

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

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

* The optional character q.  This is equivalent to L.

* A j character specifying that the following integer (d, i, o, u, x,
  or X) conversion corresponds to an intmax_t argument.

* A t character specifying that the following integer (d, i, o, u, x,
  or X) conversion corresponds to a ptrdiff_t argument.

* A z character specifying that the following integer (d, i, o, u, x,
  or X) conversion corresponds to a size_t argument.

* A T character specifying that the following integer (d, i, o, u, x,
  or X) conversion corresponds to a time_t argument.

* A character that specifies the type of conversion to be applied.

A field width or precision, or both, may be indicated by an asterisk
`*' instead of a digit string.  In this case, an int argument supplies
the field width or precision.  A negative field width is treated as a
left adjustment flag followed by a positive field width; a negative
precision is treated as though it were missing.

The conversion specifiers and their meanings are:

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

  eE		[NOT IMPLEMENTED] 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;
		if the precision is missing, it is taken as 6; if the
		precision is zero, no decimal-point character
		appears.  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.

  f		[NOT IMPLEMENTED] 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.

  g		[NOT IMPLEMENTED] 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
		precision is zero, it is treated as 1.  Style e is
		used if the exponent from its conversion is less than
		-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.

  c		The int argument is converted to an unsigned char, and
		the resulting character is written.

  s		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
		is specified, no more than the number specified are
		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.

  p		The "void *" pointer argument is printed in
		hexadecimal (as if by %#x or %#lx).

  n		The number of characters written so far is stored into
		the integer indicated by the ``int *'' (or variant)
		pointer argument.  No argument is converted.

  m		The error message associated with the current value of
		errno is printed as if by %s.

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

  H		The channel argument identifier (channel name) is
		printed.

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

  %		A `%' is written.  No argument is converted.  The
		complete conversion specification is `%%'.

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.

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

This structure is used by the %v conversion specification.  The
_vd_format_ element must contain a format string, and the _vd_args_
element must be a variable argument list.  Upon return from
ircd_snprintf() or ircd_vsnprintf(), the _vd_chars_ element will
contain the number of characters that were able to be inserted, and
the _vd_overflow_ element will contain the number of characters that
could not be inserted.
</struct>

<function>
int ircd_snprintf(struct Client *dest, char *buf, size_t buf_len,
		  const char *format, ...);

This formats the argument list, under control of the _format_, into
the buffer specified by _buf_, the size of which is specified by
_buf_len_.  The _dest_ parameter is used to determine whether to use a
numeric or a nickname for %C conversions.
</function>

<function>
int ircd_vsnprintf(struct Client *dest, char *buf, size_t buf_len,
		   const char *format, va_list args);

This function is identical to the ircd_snprintf() function except for
the variable argument list given by _args_.
</function>

<authors>
Kev <klmitch@mit.edu>
</authors>

<changelog>
[2001-6-15 Kev] Initial documentation of the ircd_snprintf family of
functions.
</changelog>