Import Trio 1.10 into fetchmail's trunk.

svn path=/trunk/; revision=3995

1 files changed, 532 insertions, 0 deletions

diff --git a/trio/doc/doc_printf.h b/trio/doc/doc_printf.h
new file mode 100644
index 00000000..4321cd5c
--- /dev/null
+++ b/trio/doc/doc_printf.h
@@ -0,0 +1,532 @@
+/*************************************************************************
+ *
+ * $Id: doc_printf.h,v 1.3 2002/05/07 16:26:00 breese Exp $
+ *
+ * Copyright (C) 2001 Bjorn Reese and Daniel Stenberg.
+ *
+ * Permission to use, copy, modify, and distribute this software for any
+ * purpose with or without fee is hereby granted, provided that the above
+ * copyright notice and this permission notice appear in all copies.
+ *
+ * THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
+ * WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
+ * MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE AUTHORS AND
+ * CONTRIBUTORS ACCEPT NO RESPONSIBILITY IN ANY CONCEIVABLE MANNER.
+ *
+ ************************************************************************/
+
+/** @addtogroup Printf Formatted Printing Functions.
+Variations of formatted printing functions.
+
+@b SYNOPSIS
+
+@verbatim
+cc ... -ltrio -lm
+
+#include <trio.h>
+@endverbatim
+
+@b DESCRIPTION
+
+This documentation is incomplete.
+The documentation of the printf family in [C99] and [UNIX98] also applies
+to the trio counterparts.
+
+All these functions outputs a string which is formatted according to the
+@p format string and the consecutive arguments. The @p format string is
+described in the Formatting section below.
+
+@ref trio_printf, @ref trio_vprintf, and @ref trio_printfv writes the
+output to the standard output stream (stdout).
+
+@ref trio_fprintf, @ref trio_vfprintf, and @ref trio_fprintfv writes the
+output to a given output stream.
+
+@ref trio_dprintf, @ref trio_vdprintf, and @ref trio_dprintfv writes the
+output to a file descriptor (this includes, for example, sockets).
+
+@ref trio_sprintf, @ref trio_vsprintf, and @ref trio_sprintfv writes the
+output into @p buffer.
+
+@ref trio_snprintf, @ref trio_vsnprintf, and @ref trio_snprintfv writes @p
+max - 1 characters into @p buffer followed by a terminating zero character.
+If @p max is 1, then @p buffer will be an empty string. If @p max is 0,
+then @p buffer is left untouched, and can consequently be NULL. The number
+of characters that would have been written to @p buffer, had there been
+sufficient space, is returned.
+
+@ref trio_snprintfcat appends the formatted text at the end of @p buffer.
+
+@ref trio_asprintf and @ref trio_vasprintf allocates and returns an
+allocated string in @p buffer containing the formatted text.
+
+@b FORMATTING
+
+The @p format string can contain normal text and conversion indicators.
+The normal text can be any character except the nil character (\000 =
+'\0') and the percent character (\045 = '%'). Conversion indicators
+consists of an indication character (%), followed by zero or more conversion
+modifiers, and exactly one conversion specifier.
+
+@b Modifiers
+
+Some modifiers exhibit the same behaviour for all specifiers, other modifiers
+indicate different behaviours for different specifiers, and other modifiers
+are only applicable to certain specifiers. The relationship is described for
+each modifier. The number 9 is used to denotes an arbitrary integer.
+
+@em Positional ( @c 9$ ) [UNIX98]
+
+Normally the arguments supplied to these functions are interpreted
+incrementially from left to right. Arguments can be referenced specifically in
+the format string. The modifier n$ selects the nth argument. The first
+argument is referred as 1$. If this modifier is used, it must be the first
+modifier after the indication character. n$ can also be used for argument
+width, precision, and base.
+
+The performance penalty of using positionals is almost neglible (contrary to
+most other printf implementations).
+
+@li @em Reference @em Mix.
+Mixing normal and positional specifiers is allowed [TRIO]. For example,
+@verbatim
+  trio_printf("%d %3$d %2$d\n", 1, 2, 3);
+@endverbatim
+results in
+@verbatim
+  1 3 2
+@endverbatim
+Arguments for the printf family are passed on the stack. On most platforms it
+is not possible to determine the size of individual stack elements, so it is
+essential that the format string corresponds exactly to the passed arguments.
+If this is not the case, incorrect values may be put into the result.
+
+@li @em Reference @em Gap.
+For the same reason it is also essential that the format string does not
+contain any &quot;gaps&quot; in the positional arguments. For example,
+@verbatim
+  trio_printf("%1$d %3$d\n", 1, 2, 3);
+@endverbatim
+is NOT allowed. The format string parser has no knowledge about whether the
+second argument is, say, an integer or a long double (which have different
+sizes).
+@verbatim
+@endverbatim
+[UNIX98] describes this as unspecified behaviour. [TRIO] will detect reference
+gaps and return an error.
+
+@li @em Double @em Reference.
+It is also not allowed to reference an argument twice or more. For example,
+@verbatim
+  trio_printf("%1$d %1$lf\n", 1);
+@endverbatim
+is NOT allowed, because it references the first argument as two differently
+sized objects.
+@verbatim
+@endverbatim
+[UNIX98] describes this as unspecified behaviour. [TRIO] will detect double
+references and return an error.
+
+The following two statements are equivalent
+@verbatim
+  trio_printf("|%d %s\n|", 42, "meanings");
+  |42 meanings|
+
+  trio_printf("|%1$d %2$s|\n", 42, "meanings");
+  |42 meanings|
+@endverbatim
+
+@em Width ( @c 9 )
+
+Specifies the minimum width of a field. If the fields has less characters than
+specified by the width, the field will be left adjusted and padded by spaces.
+The adjustment and padding can be changed by the Alignment ( @c - ) and
+Padding ( @c 0 ) modifiers.
+
+The width is specified as a number. If an asterix ( @c * ) is used instead, the
+width will be read from the argument list.
+
+Prefixes, such as 0x for hexadecimal integers, are part of width.
+@verbatim
+  trio_printf("|%10i|\n", 42);
+  |        42|
+@endverbatim
+
+@em Precision ( @c .9 )
+
+The precision has different semantics for the various data types.
+The precision specifies the maximum number of printed characters for strings,
+the number of digits after the decimal-point for floating-point numbers,
+the number of significant digits for the @c g (and @c G) representation of
+floating-point numbers, the minimum number of printed digits for integers.
+@verbatim
+  trio_printf("|%10.8i|%.8i|\n", 42, 42);
+  |  00000042|00000042|
+@endverbatim
+ 
+@em Base ( @c ..9 ) [TRIO]
+
+Sets the base that the associated integer must be converted to. The base can
+be between 2 and 36 (both included).
+@verbatim
+  trio_printf("|%10.8.2i|%10..2i|%..2i|\n", 42, 42, 42);
+  |  00101010|    101010|101010|
+
+  trio_printf("|%*.8.*i|\n", 10, 2, 42);
+  |  00101010|
+@endverbatim
+ 
+@em Padding ( @c 0 )
+
+Integer and floating point numbers are prepended by zeros. The number of
+leading zeros are determined by the precision. If precision is not present,
+width is used instead.
+
+@em Short ( @c h )
+
+Integer arguments are read as an ( @c unsigned ) @c short @c int. String
+and character arguments are read as @c char @c * and @c char respectively.
+
+@em Short @em short ( @c hh ) [C99, GNU]
+
+The argument is read as an ( @c unsigned ) @c char.
+
+@em Fixed @em Size ( @c I ) [MSVC]
+
+The argument is read as a fixed sized integer. The modifier is followed by
+a number, which specifies the number of bits in the integer, and can be one
+of the following
+
+@li @c I8
+@li @c I16
+@li @c I32
+@li @c I64 (if 64-bits integers are supported)
+
+Works only for integers (i, u, d, o, x, X)
+
+@em Largest ( @c j ) [C99]
+
+The argument is read as an @c intmax_t / @c uintmax_t, which is defined to
+be the largest signed/unsigned integer.
+
+@em Long ( @c l )
+
+An integral argument is read as an ( @c unsigned ) @c long @c int. A string
+argument is read as a @c wchar_t @c *, and output as a multi-byte character
+sequence.
+
+@em Long @em long ( @c ll ) [C99, UNIX98, GNU]
+
+The argument is read as an ( @c unsigned ) @c long @c long @c int.
+
+@em Long @em double ( @c L ) [C99, UNIX98, GNU]
+
+The argument is read as a @c long @c double.
+
+@em ptrdiff_t ( @c t ) [C99]
+
+The argument is read as a @c ptrdiff_t, which is defined to be the signed
+integer type of the result of subtracting two pointers.
+
+@em Quad ( @c q ) [BSD, GNU]
+
+Corresponds to the long long modifier ( @c ll ).
+
+@em Wide ( @c w ) [MISC]
+
+For a string argument this is equivalent to using the long modifier ( @c l ).
+
+@em size_t ( @c z ) [C99]
+
+The argument is read as a @c size_t, which is defined to be the type
+returned by the @c sizeof operator.
+
+@em size_t ( @c Z ) [GNU]
+
+Corresponds to the size_t modifier ( @c z ).
+
+@em Alternative ( @c # )
+
+Prepend radix indicator for hexadecimal, octal, and binary integer numbers
+and for pointers.
+Always add a decimal-pointer for floating-point numbers.
+Escape non-printable characters for strings.
+
+@em Spacing ( )
+
+Prepend leading spaces when necessary.
+
+@em Sign ( @c + )
+
+Always prepend a sign to numbers. Normally only the negative sign is prepended
+to a number. With this modifier the positive sign may also be prepended.
+
+@em Alignment ( @c - )
+
+The output will be left-justified in the field specified by the width.
+
+@em Argument ( @c * )
+
+Width, precision, or base is read from the argument list, rather than from
+the formatting string.
+
+@em Quote / @em Grouping ( @c ' ) [MISC]
+
+Groups integers and the integer-part of floating-point numbers according to
+the locale. Quote strings and characters.
+
+@em Sticky ( @c ! ) [TRIO]
+
+The modifiers listed for the current specifier will be reused by subsequent
+specifiers of the same group.
+The following specifier groups exists
+@li Integer ( @c i, @c u, @c d, @c o, @c x, @c X )
+@li Floating-point ( @c f, @c F, @c e, @c E, @c g, @c G, @c a, @c A )
+@li Character ( @c c )
+@li String ( @c s )
+@li Pointer ( @c p )
+@li Count ( @c n )
+@li Errno ( @c m )
+@li Group ( @c [] )
+
+The sticky modifiers are active until superseeded by other sticky modifiers,
+or the end of the format string is reached.
+Local modifiers overrides sticky modifiers for the given specifier only.
+@verbatim
+  trio_printf("|%!08#x|%04x|%x|\n", 42, 42, 42);
+  |0x00002a|0x2a|0x00002a|
+@endverbatim
+
+@b Specifiers
+
+@em Percent ( @c % )
+
+Produce a percent ( @c % ) character. This is used to quote the indication
+character. No modifiers are allowed.
+The full syntax is @c %%.
+@verbatim
+  trio_printf("Percent is %%\n");
+  Percent is %
+@endverbatim
+
+@em Hex @em floats ( @c a, @c A ) [C99]
+
+Output a hexadecimal (base 16) representation of a floating point number. The
+number is automatically preceeded by @c 0x ( or @c 0X ). The exponent is
+@c p ( or @c P ).
+@verbatim
+  trio_printf("|%a|%A|\n", 3.1415, 3.1415e20);
+  |0x3.228bc|0X3.228BCP+14|
+@endverbatim
+
+@em Binary @em numbers ( @c b, @c B ) [MISC - SCO UnixWare 7]
+
+DEPRECATED: Use Base modifier @c %..2i instead.
+
+@em Character ( @c c )
+
+Output a single character.
+
+@li Quote ( @c ' ) [TRIO].
+Quote the character.
+
+@em Decimal ( @c d )
+
+Output a decimal (base 10) representation of a number.
+
+@li Grouping ( @c ' ) [TRIO].
+The number is separated by the locale thousand separator.
+@verbatim
+  trio_printf("|%'ld|\n", 1234567);
+  |1,234,567|
+@endverbatim
+
+@em Floating-point ( @c e, @c E)
+
+Output a decimal floating-point number.
+The style is @c [-]9.99e[-]9, where
+@li @c [-]9.99 is the mantissa (as described for the @c f, @c F specifier), and
+@li @c e[-]9 is the exponent indicator (either @c e or @c E, depending on the
+floating-point specifier), followed by an optional sign and the exponent
+
+If the precision is wider than the maximum number of digits that can be
+represented by the floating-point unit, then the number will be adequately
+rounded. For example, assuming DBL_DIG is 15
+@verbatim
+  trio_printf("|%.18e|\n", (1.0 / 3.0));
+  |3.333333333333333000e-01|
+@endverbatim
+
+@em Floating-point ( @c f, @c F )
+
+Output a decimal floating-point number.
+The style is @c [-]9.99, where
+@li @c [-] is an optional sign (either @c + or @c -),
+@li @c 9 is the integer-part (possibly interspersed with thousand-separators),
+@li @c . is the decimal-point (depending on the locale), and
+@li @c 99 is the fractional-part.
+
+If more digits are needed to output the number, than can be represented with
+the accuracy of the floating-point unit, then the number will be adequately
+rounded. For example, assuming that DBL_DIG is 15
+@verbatim
+  trio_printf("|%f|\n", (2.0 / 3.0) * 1E18);
+  |666666666666666700.000000|
+@endverbatim
+
+The following modifiers holds a special meaning for this specifier
+@li Alternative ( @c # ) [C99].
+Add decimal point.
+@li Grouping ( @c ' ) [TRIO].
+Group integer part of number into thousands (according to locale).
+
+@em Floating-point ( @c g, @c G)
+
+Output a decimal floating-point representation of a number. The format of
+either the @c f, @c F specifier or the @c e, @c E specifier is used, whatever
+produces the shortest result.
+
+@em Integer ( @c i )
+
+Output a signed integer. Default base is 10.
+
+@em Errno ( @c m ) [GNU]
+
+@em Count ( @c n )
+
+Insert into the location pointed to by the argument, the number of octets
+written to the output so far.
+
+@em Octal ( @c o )
+
+Output an octal (base 8) representation of a number.
+
+@em Pointer ( @c p )
+
+Ouput the address of the argument. The address is printed as a hexadecimal
+number. If the argument is the NULL pointer the text @c (nil) will be used
+instead.
+@li Alternative ( @c # ) [TRIO].
+Prepend 0x
+
+@em String ( @c s, @c S )
+
+Output a string. The argument must point to a zero terminated string. If the
+argument is the NULL pointer the text @c (nil) will be used instead.
+@c S is equivalent to @c ls.
+@li Alternative ( @c # ) [TRIO].
+Escape non-printable characters.
+
+Non-printable characters are converted into C escapes, or hexadecimal numbers
+where no C escapes exists for the character. The C escapes, the hexadecimal
+number, and all backslashes are prepended by a backslash ( @c \ ).
+The supported C escapes are
+@li @c \a (\007) = alert
+@li @c \b (\010) = backspace
+@li @c \f (\014) = formfeed
+@li @c \n (\012) = newline
+@li @c \r (\015) = carriage return
+@li @c \t (\011) = horizontal tab
+@li @c \v (\013) = vertical tab
+
+@verbatim
+  trio_printf("|One %s Three|One %'s Three|\n", "Two", "Two");
+  |One Two Three|One "Two" Three|
+
+  trio_printf("|Argument missing %s|\n", NULL);
+  |Argument missing (nil)|
+
+  trio_printf("|%#s|\n", "\007 \a.");
+  |\a \a.|
+@endverbatim
+
+@em Unsigned ( @c u )
+
+Output an unsigned integer. Default base is 10.
+
+@em Hex ( @c x, @c X )
+
+Output a hexadecimal (base 16) representation of a number.
+
+@li Alternative ( @c # ).
+Preceed the number by @c 0x ( or @c 0X ). The two characters are counted
+as part of the width.
+
+@em User-defined ( @c <> )
+
+Invoke user-defined formatting.
+See @ref trio_register for further information.
+
+@b RETURN @b VALUES
+
+All functions returns the number of outputted characters. If an error occured
+then a negative error code is returned [TRIO]. Note that this is a deviation
+from the standard, which simply returns -1 (or EOF) and errno set
+appropriately.
+The error condition can be detected by checking whether the function returns
+a negative number or not, and the number can be parsed with the following
+macros. The error codes are primarily intended as debugging aide for the
+developer.
+
+@li TRIO_EINVAL: Invalid argument.
+@li TRIO_ETOOMANY: Too many arguments.
+@li TRIO_EDBLREF: Double argument reference.
+@li TRIO_EGAP: Argument reference gap.
+@li TRIO_ENOMEM: Out of memory.
+@li TRIO_ERANGE: Invalid range.
+@li TRIO_ERRNO: The error is specified by the errno variable.
+
+Example:
+@verbatim
+  int rc;
+
+  rc = trio_printf("%r\n", 42);
+  if (rc < 0) {
+    if (TRIO_ERROR_CODE(rc) != TRIO_EOF) {
+      trio_printf("Error: %s at position %d\n",
+                  TRIO_ERROR_NAME(rc),
+                  TRIO_ERROR_POSITION(rc));
+    }
+  }
+@endverbatim
+
+@b SEE @b ALSO
+
+@e trio_scanf, @e trio_register.
+
+@b NOTES
+
+The printfv family uses an array rather than the stack to pass arguments.
+This means that @c short @c int and @c float values will not be handled by
+the default argument promotion in C. Instead, these values must be explicitly
+converted with the Short (h) modifier in both cases.
+
+Example:
+@verbatim
+  void *array[2];
+  float float_number = 42.0;
+  short short_number = 42;
+
+  array[0] = &float_number;
+  array[1] = &short_number;
+
+  trio_printfv("%hf %hd\n", array); /* CORRECT */
+  trio_printfv("%f %d\n", array); /* WRONG */
+@endverbatim
+
+@b CONFORMING @b TO
+
+Throughout this document the following abbreviations have been used to
+indicate what standard a feature conforms to. If nothing else is indicated
+ANSI C (C89) is assumed.
+
+@li [C89] ANSI X3.159-1989
+@li [C99] ISO/IEC 9899:1999
+@li [UNIX98] The Single UNIX Specification, Version 2
+@li [BSD] 4.4BSD
+@li [GNU] GNU libc
+@li [MSVC] Microsoft Visual C
+@li [MISC] Other non-standard sources
+@li [TRIO] Extensions specific for this package
+
+*/