|
|
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
cc ... -ltrio -lm
#include <trio.h>
int trio_printf(const char *format, ...);
int trio_fprintf(FILE *file, const char *format, ...);
int trio_dprintf(int 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, ...);
int trio_asprintf(char **buffer, const char *format, ...);
int trio_vprintf(const char *format, va_list args);
int trio_vfprintf(FILE *file, const char *format, va_list args);
int trio_vdprintf(int 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);
int trio_vasprintf(char **buffer, const char *format, va_list args);
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 and trio_vprintf writes the output to the standard output stream (stdout).
trio_fprintf and trio_vfprintf writes the output to a given output stream.
trio_dprintf and trio_vdprintf writes the output to a file descriptor (this includes, for example, sockets).
trio_sprintf and trio_vsprintf writes the output into buffer.
trio_snprintf and trio_vsnprintf 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 a 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 (ASCII 000 = '0') and the percent character (ASCII 045 = '%'). Conversion indicators consists of an indication character (%), followed by zero or more conversion modifiers, and exactly one 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. Furthermore, the | character is used to clarify the output.
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 arbitary 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).
Mixing
Mixing normal and positional specifiers is allowed [TRIO]. 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 format string 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. [TRIO] 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. [TRIO] will detect double references and return an error.
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|
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.
1. trio_printf("|%10i|", 42);
| 42|
Precision (.9)
1. trio_printf("|%10.8i|%.8i|", 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).
1. trio_printf("|%10.8.2i|%10..2i|%..2i|", 42, 42, 42);
| 00101010| 101010|101010|
2. trio_printf("|%*.8.*i|", 10, 2, 42);
| 00101010|
Padding (0)
This modifier 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.
Short (h)
The argument is read as an (unsigned) short int.
Short short (hh) [C99, GNU]
The argument is read as an (unsigned) char.
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)
The argument is read as an (unsigned) long int.
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).
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 (#)
Spacing ( )
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.
Argument (*)
Quote/Grouping (') [MISC]
Groups integers and the integer-part of floating-point numbers according to the locale.
Sticky (!) [TRIO]
The modifiers listed for the current specifier will be reused by subsequent specifiers of the same group.
The following specifier groups exists
* Integers (i, u, d, o, x, X)
* Floating-point (f, F, e, E, g, G, a, A)
* Characters (c, C)
* Strings (s, S)
* Pointer (p)
* Count (n)
* Errno (m)
* Group ([])
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.
1. trio_printf("|%!08#x|%04x|%x|", 42, 42, 42);
|0x00002a|0x2a|0x00002a|
Allocate (<alloc>) [TRIO]
SPECIFIERS
Percent (%)
Produce a percent (%) character. This is used to quote the indication character. No modifiers are allowed. The full syntax is "%%".
1. trio_printf("Percent is %%");
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').
1. trio_printf("|%a|%A|", 3.1415, 3.1415e20);
|0x3.228bc|0X3.228BCP+14|
Binary numbers (b, B) [MISC - SCO UnixWare 7]
DEPRECATED: Use Base %..2i instead.
Character (c)
Output a single character.
* Quote (') [TRIO]
Quote the character
Decimal (d)
Output a decimal (base 10) representation of a number.
* Grouping (') [TRIO]
The number is separated by the locale thousand separator.
Assuming the thousand separator is comma and the grouping is set to 3
1. trio_printf("|%'ld|", 1234567);
|1,234,567|
Floating-point (e, E)
Output a decimal floating-point number. The style is [\-]9.99e[\-]9 where
[\-]9.99 is the mantissa (as described for the f, F specifier),
e[\-]9 is the exponent indicator (either e or E, depending on the floating-point specifier), followed by an optional sign and the exponent
Floating-point (f, F)
Output a decimal floating-point number. The style is [\-]9.99 where
[\-] is an optional sign (either + or -),
9 is the integer-part (possibly interspersed with thousand-separators),
. is the decimal-point (depending on the locale), and
99 is the fractional-part.
The following modifiers holds a special meaning for this specifier
* Alternative (#) [C99]
Add decimal point.
* Grouping (') [TRIO]
Group integer part of number into thousands.
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.
* Alternative (#) [TRIO]
Prepend 0x
String (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.
* Quote (') [TRIO]
Quote the string.
* Alternative (#) [TRIO]
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 known C escapes are
a (ASCII 007) = alert
b (ASCII 010) = backspace
f (ASCII 014) = formfeed
n (ASCII 012) = newline
r (ASCII 015) = carriage return
t (ASCII 011) = horizontal tab
v (ASCII 013) = vertical tab
1. trio_printf("|One %s Three|One %'s Three|", "Two", "Two");
|One Two Three|One "Two" Three|
2. trio_printf("|Argument missing %s|", NULL);
|Argument missing (nil)|
3. trio_printf("|%#s|", "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.
* Alternative (#)
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 [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", 42); if (rc < 0) { if (TRIO_ERROR_CODE(rc) != TRIO_EOF) { trio_printf("Error: at position 0n", TRIO_ERROR_NAME(rc), TRIO_ERROR_POSITION(rc)); } }
rc = trio_printf("%r", 42); if (rc < 0) { if (TRIO_ERROR_CODE(rc) != TRIO_EOF) { trio_printf("Error: at position 0n", TRIO_ERROR_NAME(rc), TRIO_ERROR_POSITION(rc)); } }
SEE ALSO
trio_scanf (3)
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 ANSI X3.159-1989
C99 ISO/IEC 9899:1999
UNIX98 The Single UNIX Specification, Version 2
BSD 4.4BSD
GNU GNU libc
MISC Other non-standard sources
TRIO Extensions specific for this package
LEGAL ISSUES
Copyright (C) 1998-2000 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.
This HTML page was made with roffit.