From c116e68a05e2feb9a0c8e735aab097ef5ea1dfb3 Mon Sep 17 00:00:00 2001 From: Matthias Andree Date: Fri, 5 Mar 2010 22:33:03 +0100 Subject: Drop outdated documentation. Can be regenerated with Doxygen. --- trio/html/group___printf.html | 1259 ----------------------------------------- 1 file changed, 1259 deletions(-) delete mode 100644 trio/html/group___printf.html (limited to 'trio/html/group___printf.html') diff --git a/trio/html/group___printf.html b/trio/html/group___printf.html deleted file mode 100644 index 7f79200f..00000000 --- a/trio/html/group___printf.html +++ /dev/null @@ -1,1259 +0,0 @@ - - - - - TRIO - - - - -
-Main Page   Modules  
-

Formatted Printing Functions.

Variations of formatted printing functions. -More... - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Functions

int trio_printf (const char *format,...)
 Print to standard output stream. More...

int trio_vprintf (const char *format, va_list args)
 Print to standard output stream. More...

int trio_printfv (const char *format, trio_pointer_t *args)
 Print to standard output stream. More...

int trio_fprintf (FILE *file, const char *format,...)
 Print to file. More...

int trio_vfprintf (FILE *file, const char *format, va_list args)
 Print to file. More...

int trio_fprintfv (FILE *file, const char *format, trio_pointer_t *args)
 Print to file. More...

int trio_dprintf (int fd, const char *format,...)
 Print to file descriptor. More...

int trio_vdprintf (int fd, const char *format, va_list args)
 Print to file descriptor. More...

int trio_dprintfv (int fd, const char *format, trio_pointer_t *args)
 Print to file descriptor. More...

int trio_sprintf (char *buffer, const char *format,...)
 Print to string. More...

int trio_vsprintf (char *buffer, const char *format, va_list args)
 Print to string. More...

int trio_sprintfv (char *buffer, const char *format, trio_pointer_t *args)
 Print to string. More...

int trio_snprintf (char *buffer, size_t max, const char *format,...)
 Print at most max characters to string. More...

int trio_vsnprintf (char *buffer, size_t max, const char *format, va_list args)
 Print at most max characters to string. More...

int trio_snprintfv (char *buffer, size_t max, const char *format, trio_pointer_t *args)
 Print at most max characters to string. More...

-

Detailed Description

-Variations of formatted printing functions. -

-SYNOPSIS -

-

-cc ... -ltrio -lm
-
-#include <trio.h>
-
-

-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 format string and the consecutive arguments. The format string is described in the Formatting section below. -

-trio_printf, trio_vprintf, and trio_printfv writes the output to the standard output stream (stdout). -

-trio_fprintf, trio_vfprintf, and trio_fprintfv writes the output to a given output stream. -

-trio_dprintf, trio_vdprintf, and trio_dprintfv writes the output to a file descriptor (this includes, for example, sockets). -

-trio_sprintf, trio_vsprintf, and trio_sprintfv writes the output into buffer. -

-trio_snprintf, trio_vsnprintf, and trio_snprintfv writes max - 1 characters into buffer followed by a terminating zero character. If max is 1, then buffer will be an empty string. If max is 0, then buffer is left untouched, and can consequently be NULL. The number of characters that would have been written to buffer, had there been sufficient space, is returned. -

-trio_snprintfcat appends the formatted text at the end of buffer. -

-trio_asprintf and trio_vasprintf allocates and returns an allocated string in buffer 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 (\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. -

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

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

-

- - -The following two statements are equivalent 
-  trio_printf("|%d %s\n|", 42, "meanings");
-  |42 meanings|
-
-  trio_printf("|%1$d %2$s|\n", 42, "meanings");
-  |42 meanings|
-
-

-Width ( 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 ( - ) and Padding ( 0 ) modifiers. -

-The width is specified as a number. If an asterix ( * ) is used instead, the width will be read from the argument list. -

-Prefixes, such as 0x for hexadecimal integers, are part of width. 

-  trio_printf("|%10i|\n", 42);
-  |        42|
-
-

-Precision ( .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 g (and G) representation of floating-point numbers, the minimum number of printed digits for integers. 

-  trio_printf("|%10.8i|%.8i|\n", 42, 42);
-  |  00000042|00000042|
-
-

-Base ( ..9 ) [TRIO] -

-Sets the base that the associated integer must be converted to. The base can be between 2 and 36 (both included). 

-  trio_printf("|%10.8.2i|%10..2i|%..2i|\n", 42, 42, 42);
-  |  00101010|    101010|101010|
-
-  trio_printf("|%*.8.*i|\n", 10, 2, 42);
-  |  00101010|
-
-

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

-Short ( h ) -

-Integer arguments are read as an ( unsigned ) short int. String and character arguments are read as char * and char respectively. -

-Short short ( hh ) [C99, GNU] -

-The argument is read as an ( unsigned ) char. -

-Fixed Size ( 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 -

-

-Works only for integers (i, u, d, o, x, X) -

-Largest ( j ) [C99] -

-The argument is read as an intmax_t / uintmax_t, which is defined to be the largest signed/unsigned integer. -

-Long ( l ) -

-An integral argument is read as an ( unsigned ) long int. A string argument is read as a wchar_t *, and output as a multi-byte character sequence. -

-Long long ( ll ) [C99, UNIX98, GNU] -

-The argument is read as an ( unsigned ) long long int. -

-Long double ( L ) [C99, UNIX98, GNU] -

-The argument is read as a long double. -

-ptrdiff_t ( t ) [C99] -

-The argument is read as a ptrdiff_t, which is defined to be the signed integer type of the result of subtracting two pointers. -

-Quad ( q ) [BSD, GNU] -

-Corresponds to the long long modifier ( ll ). -

-Wide ( w ) [MISC] -

-For a string argument this is equivalent to using the long modifier ( l ). -

-size_t ( z ) [C99] -

-The argument is read as a size_t, which is defined to be the type returned by the sizeof operator. -

-size_t ( Z ) [GNU] -

-Corresponds to the size_t modifier ( z ). -

-Alternative ( # ) -

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

-Spacing ( ) -

-Prepend leading spaces when necessary. -

-Sign ( + ) -

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

-Alignment ( - ) -

-The output will be left-justified in the field specified by the width. -

-Argument ( * ) -

-Width, precision, or base is read from the argument list, rather than from the formatting string. -

-Quote / Grouping ( ' ) [MISC] -

-Groups integers and the integer-part of floating-point numbers according to the locale. Quote strings and characters. -

-Sticky ( ! ) [TRIO] -

-The modifiers listed for the current specifier will be reused by subsequent specifiers of the same group. The following specifier groups exists

-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. 
-  trio_printf("|%!08#x|%04x|%x|\n", 42, 42, 42);
-  |0x00002a|0x2a|0x00002a|
-
-

-Specifiers -

-Percent ( % ) -

-Produce a percent ( % ) character. This is used to quote the indication character. No modifiers are allowed. The full syntax is %%. 

-  trio_printf("Percent is %%\n");
-  Percent is %
-
-

-Hex floats ( a, A ) [C99] -

-Output 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 ). 

-  trio_printf("|%a|%A|\n", 3.1415, 3.1415e20);
-  |0x3.228bc|0X3.228BCP+14|
-
-

-Binary numbers ( b, B ) [MISC - SCO UnixWare 7] -

-DEPRECATED: Use Base modifier %..2i instead. -

-Character ( c ) -

-Output a single character. -

-

-Decimal ( d ) -

-Output a decimal (base 10) representation of a number. -

-

-Floating-point ( e, E) -

-Output a decimal floating-point number. The style is [-]9.99e[-]9, where

-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 
-  trio_printf("|%.18e|\n", (1.0 / 3.0));
-  |3.333333333333333000e-01|
-
-

-Floating-point ( f, F ) -

-Output a decimal floating-point number. The style is [-]9.99, where

-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 
-  trio_printf("|%f|\n", (2.0 / 3.0) * 1E18);
-  |666666666666666700.000000|
-
-

-The following modifiers holds a special meaning for this specifier

-Floating-point ( g, G) -

-Output a decimal floating-point representation of a number. The format of either the f, F specifier or the e, E specifier is used, whatever produces the shortest result. -

-Integer ( i ) -

-Output a signed integer. Default base is 10. -

-Errno ( m ) [GNU] -

-Count ( n ) -

-Insert into the location pointed to by the argument, the number of octets written to the output so far. -

-Octal ( o ) -

-Output an octal (base 8) representation of a number. -

-Pointer ( p ) -

-Ouput the address of the argument. The address is printed as a hexadecimal number. If the argument is the NULL pointer the text (nil) will be used instead.

-String ( s, S ) -

-Output a string. The argument must point to a zero terminated string. If the argument is the NULL pointer the text (nil) will be used instead. S is equivalent to ls.

-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 ( \ ). The supported C escapes are -
-  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.|
-
-

-Unsigned ( u ) -

-Output an unsigned integer. Default base is 10. -

-Hex ( x, X ) -

-Output a hexadecimal (base 16) representation of a number. -

-

-User-defined ( <> ) -

-Invoke user-defined formatting. See trio_register for further information. -

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

-

-Example: 
-  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));
-    }
-  }
-
-

-SEE ALSO -

-trio_scanf, trio_register. -

-NOTES -

-The printfv family uses an array rather than the stack to pass arguments. This means that short int and 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: 

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

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

-

-

Function Documentation

-

- - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - -
int trio_dprintf ( int   fd,
const char *   format,
...  
) 
-
- - - - - -
-   - - -

-Print to file descriptor. -

-

-Parameters:
- - - - -
fd  -File descriptor.
format  -Formatting string.
...  -Arguments.
-
-Returns:
-Number of printed characters.
-

- - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - -
int trio_dprintfv ( int   fd,
const char *   format,
trio_pointer_t *   args
) 
-
- - - - - -
-   - - -

-Print to file descriptor. -

-

-Parameters:
- - - - -
fd  -File descriptor.
format  -Formatting string.
args  -Arguments.
-
-Returns:
-Number of printed characters.
-

- - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - -
int trio_fprintf ( FILE *   file,
const char *   format,
...  
) 
-
- - - - - -
-   - - -

-Print to file. -

-

-Parameters:
- - - - -
file  -File pointer.
format  -Formatting string.
...  -Arguments.
-
-Returns:
-Number of printed characters.
-

- - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - -
int trio_fprintfv ( FILE *   file,
const char *   format,
trio_pointer_t *   args
) 
-
- - - - - -
-   - - -

-Print to file. -

-

-Parameters:
- - - - -
file  -File pointer.
format  -Formatting string.
args  -Arguments.
-
-Returns:
-Number of printed characters.
-

- - - - -
- - - - - - - - - - - - - - - - - - - -
int trio_printf ( const char *   format,
...  
) 
-
- - - - - -
-   - - -

-Print to standard output stream. -

-

-Parameters:
- - - -
format  -Formatting string.
...  -Arguments.
-
-Returns:
-Number of printed characters.
-

- - - - -
- - - - - - - - - - - - - - - - - - - -
int trio_printfv ( const char *   format,
trio_pointer_t *   args
) 
-
- - - - - -
-   - - -

-Print to standard output stream. -

-

-Parameters:
- - - -
format  -Formatting string.
args  -Arguments.
-
-Returns:
-Number of printed characters.
-

- - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
int trio_snprintf ( char *   buffer,
size_t   max,
const char *   format,
...  
) 
-
- - - - - -
-   - - -

-Print at most max characters to string. -

-

-Parameters:
- - - - - -
buffer  -Output string.
max  -Maximum number of characters to print.
format  -Formatting string.
...  -Arguments.
-
-Returns:
-Number of printed characters.
-

- - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
int trio_snprintfv ( char *   buffer,
size_t   max,
const char *   format,
trio_pointer_t *   args
) 
-
- - - - - -
-   - - -

-Print at most max characters to string. -

-

-Parameters:
- - - - - -
buffer  -Output string.
max  -Maximum number of characters to print.
format  -Formatting string.
args  -Arguments.
-
-Returns:
-Number of printed characters.
-

- - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - -
int trio_sprintf ( char *   buffer,
const char *   format,
...  
) 
-
- - - - - -
-   - - -

-Print to string. -

-

-Parameters:
- - - - -
buffer  -Output string.
format  -Formatting string.
...  -Arguments.
-
-Returns:
-Number of printed characters.
-

- - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - -
int trio_sprintfv ( char *   buffer,
const char *   format,
trio_pointer_t *   args
) 
-
- - - - - -
-   - - -

-Print to string. -

-

-Parameters:
- - - - -
buffer  -Output string.
format  -Formatting string.
args  -Arguments.
-
-Returns:
-Number of printed characters.
-

- - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - -
int trio_vdprintf ( int   fd,
const char *   format,
va_list   args
) 
-
- - - - - -
-   - - -

-Print to file descriptor. -

-

-Parameters:
- - - - -
fd  -File descriptor.
format  -Formatting string.
args  -Arguments.
-
-Returns:
-Number of printed characters.
-

- - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - -
int trio_vfprintf ( FILE *   file,
const char *   format,
va_list   args
) 
-
- - - - - -
-   - - -

-Print to file. -

-

-Parameters:
- - - - -
file  -File pointer.
format  -Formatting string.
args  -Arguments.
-
-Returns:
-Number of printed characters.
-

- - - - -
- - - - - - - - - - - - - - - - - - - -
int trio_vprintf ( const char *   format,
va_list   args
) 
-
- - - - - -
-   - - -

-Print to standard output stream. -

-

-Parameters:
- - - -
format  -Formatting string.
args  -Arguments.
-
-Returns:
-Number of printed characters.
-

- - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
int trio_vsnprintf ( char *   buffer,
size_t   max,
const char *   format,
va_list   args
) 
-
- - - - - -
-   - - -

-Print at most max characters to string. -

-

-Parameters:
- - - - - -
buffer  -Output string.
max  -Maximum number of characters to print.
format  -Formatting string.
args  -Arguments.
-
-Returns:
-Number of printed characters.
-

- - - - -
- - - - - - - - - - - - - - - - - - - - - - - - - -
int trio_vsprintf ( char *   buffer,
const char *   format,
va_list   args
) 
-
- - - - - -
-   - - -

-Print to string. -

-

-Parameters:
- - - - -
buffer  -Output string.
format  -Formatting string.
args  -Arguments.
-
-Returns:
-Number of printed characters.
-

-
Copyright (C) 2001 Bjørn Reese and Daniel Stenberg.
- - -- cgit v1.2.3