NAME
	trio_printf, trio_fprintf, trio_sprintf, trio_snprintf,
	trio_snprintfcat, trio_aprintf, trio_vprintf, trio_vfprintf,
	trio_vsprintf, trio_vsnprintf, trio_vaprintf - formatted
	output conversion


SYNOPSIS
	#include <trio.h>

	int trio_printf(const char *format, ...);
	int trio_fprintf(FILE *fd, const char *format, ...);
	int trio_sprintf(char *buffer, const char *format, ...);
	int trio_snprintf(char *buffer, size_t max, const char *format, ...);
	int trio_snprintfcat(char *buffer, size_t max, const char *format, ...);
	char *trio_aprintf(const char *format, ...);
	
	int trio_vprintf(const char *format, va_list args);
	int trio_vfprintf(FILE *fd, const char *format, va_list args);
	int trio_vsprintf(char *buffer, const char *format, va_list args);
	int trio_vsnprintf(char *buffer, size_t bufferSize, const char *format, va_list args);
	char *trio_vaprintf(const char *format, va_list args);


DESCRIPTION

	{trio_printf and the others}
	
	trio_snprintfcat appends the formatted text at the end of the
	buffer.

	trio_aprintf returns an allocated string containing the formatted
	text.
	
	
FORMATTING

	The format string can contain normal text and conversion
	indicators. The normal text can be any character except
	the nil character (ASCII 000 = '\0') and the percent
	character (ASCII 045 = '%'.) Conversion indicators consists
	a indication character (%), followed by zero or more conversion
	flags, and a single conversion specifier.

	NOTE: The examples below are missing the \n character. This
	was omitted to improve readability. To make trio_printf
	actually print the formatted text, the \n character must be
	added to the examples.
	
	
	FLAGS

	Some flags exhibit the same behaviour for all specifiers, other
	flags indicate different behaviours for different specifiers,
	and other flags are only applicable to certain specifiers. The
	relationship is described for each flag.

	* 9$ - Positional [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 flag
	  n$ selects the nth argument. The first argument is referred
	  as 1$. If this flag is used, it must be the first flag after
	  the indication character.
	  
	  Mixing:

	  Mixing normal and positional specifiers are allowed [EXT].
	  For example, trio_printf("%d %3$d %2$d", 1, 2, 3); results in
	  ``1 3 2''.

	  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.

	  Reference gap:

	  For the same reason it is also essential that the format
	  string does not contain any "gaps" in the positional arguments.
	  For example, trio_printf("%1$d %3$d", 1, 2, 3); is NOT allowed.
	  The parser has no knowledge about whether the second argument
	  is, say, an integer or a long double (which have different sizes).
	  [UNIX98] describes this as unspecified behaviour. [EXT] will
	  detect reference gaps and return an error.

	  Double reference:

	  It is also not allowed to reference an argument twice or more.
	  For example, trio_printf("%1$d %1$lf", 1); is NOT allowed,
	  because it references the first argument as two differently
	  sized objects.
	  [UNIX98] describes this as unspecified behaviour. [EXT] will
	  detect double references and return an error.

	  Examples:

	  The following two statements are equivalent
	  1) trio_printf("%d %s", 42, "meanings");
	     ``42 meanings''
	  2) trio_printf("%1$d %2$s", 42, "meanings");
	     ``42 meanings''

	* 9 - Width
	  {Prefix (0x) is part of width}

	* .9 - Precision

	* 0 - Padding
	  This flag means that (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.
	
	* h - Short

	* hh - Short short [C9X, GNU]
	  A short short corresponds to an (unsigned) char.

	* l - Long

	* ll - Long long [C9X, UNIX98, GNU]

	* L - Long double [C9X, UNIX98, GNU]

	* q - Quad [BSD, GNU]

	* Z - size_t [GNU]
	  size_t is defined to be the type returned by the sizeof operator.

	* w - Widechar [MISC]
	  N/A

	* # - Alternative
	  String [EXT]

	*   - Spacing

	* + - Sign
	  Always prepend a sign to numbers. Normally only the negative
	  sign is prepended to a number. With this flag the positive sign
	  may also be prepended.

	* - - Alignment

	* * - Parameter

	* ' - Quote/Thousands

	* <alloc> - Allocate [EXT]

	* <base=9> - Radix base [EXT]

	* <quote=c> - Quote text [EXT]
	

	SPECIFIERS

	* % - Percent
          Produce a percent (%) character. This is used to quote the
	  indication character. No flags are allowed. The full syntax is
	  ``%%''.

	  Examples:

	  1) trio_printf("Percent is %%");
	     ``Percent is %''
	
	* a,A - Hex floats [C9X]
	  Insert a hexadecimal (base 16) representation of a floating
	  point number. The number is automatically preceeded by 0x
	  (or 0X). The exponent is 'p' (or 'P'.)

	  Examples:

	  1) trio_printf("%a", 3.1415);
	     ``0x3.228bc''
	  2) trio_printf("%A", 3.1415e20);
	     ``0X3.228BCP+14''

	* b,B - Binary numbers [EXT]
	  Insert a binary (base 2) representation of a number.

	  # Preceed the number by 0b (or 0B)
	  ' Grouping

	  Examples:

	  1) trio_printf("%b", 42);
	     ``00101010''
	  2) trio_printf("%#'b", 42);
	     ``0b0010,1010''

	* c - Char
	  Insert a single character.

	  ' [EXT] Quote the character

	* C - Widechar [MISC]
	  N/A

	* d - Decimal
	  Insert a decimal (base 10) representation of a number.

	  ' [EXT] Grouping. The number is separated by the locale
	    thousand separator.

	  Examples:

	  x) trio_printf("%'ld", 1234567);
	     ``1,234,567''

	* e,E - Floating-point

	* f,F - Floating-point

	  # [C9X] Add decimal point
	  ' [EXT] Grouping

	* g,G - Floating-point

	* i - Integer

	* m - Errno [GNU]

	* n - Count

	* o - Octal
	  Insert an octal (base 8) representation of a number.

	* p - Pointer
	  Insert the address of the argument.

	  # [EXT] Prepend 0x

	* s - String
	  Insert a string. The argument must point to a zero terminated
	  string. If the argument is the NULL pointer the text ``(nil)''
	  will be inserted instead.

	  ' [EXT] Quote the string
	  # [EXT] Non-printable characters are converted into their octal
	    value. The octal value and all backslashes are prepended by a
	    backslash (/),

	  Examples:

	  x) trio_printf("One %s Three", "Two");
	     ``One Two Three''
	  x) trio_printf("One %'s Three", "Two");
	     ``One "Two" Three''
	  x) trio_printf("Argument missing %s", NULL);
	     ``Argument missing (nil)''
	  x) trio_printf("%#s", "\r.");
	     ``\015.''

	* S - Widechar string [MISC]
	  N/A

	* u - Unsigned

	* x,X - Hex
	  Insert a hexadecimal (base 16) representation of a number.

	  # Preceed the number by 0x (or 0X.) The two characters are
	    counted as part of the width.


RETURN VALUES

       All functions returns the number of outputted characters. If an
       error occured then a negative error code is returned [EXT]. Note that
       this is a deviation from the standard, which simply returns -1 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.

       TRIO_ERROR_CODE
       
         TRIO_EOF - End Of File
	 TRIO_EINVAL - An unknown/invalid flag or specifier was found
	 TRIO_ETOOMANY - Too many arguments where specified or the
	   positional number was too big.
	 TRIO_EDBLREF - A double reference was detected (see the description
	   of the positional qualifier.)
	 TRIO_EGAP - A reference gap was detected (see the description of
	   the positional qualifier.)

       TRIO_ERROR_NAME

       TRIO_ERROR_POSITION

       Examples:
       
         int rc;

	 rc = trio_printf("%r", 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));
	   }
	 }


SEE ALSO

	trio_scanf


CONFORMING 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.
	   
	C89    - C3.159-1989 (ANSI)
	C9X    - WG14/N843 draft (ISO)
	UNIX98 - The Single UNIX Specification, Version 2
	         (The Open Group)
	BSD    - 4.4BSD
	GNU    - GNU libc
	MISC   - Other non-standard sources
	EXT    - Extensions specific for this package


BUGS

	There is no multi-byte or wide-character support yet.
