printf, printf_l -- print formatted output

SYNOPSIS

#include <stdio.h>

#include <locale.h>

int asprintf(char **ret, const char *format, ...);

int asprintf_l(char **ret, locale_t locale, const char *format, ...);

int fprintf(FILE *stream, const char *format, ...);

int fprintf_l(FILE *stream, locale_t locale, const char *format, ...);

int dprintf(int fd, const char * format, ...);

int dprintf_l(int fd, locale_t locale, const char * format, ...);

int printf(const char *format, ...);

int printf_l(locale_t locale, const char *format, ...);

int snprintf(char *s, size_t n, const char *format, ...);

int snprintf_l(char *s, size_t n, locale_t locale, const char *format, ...);

int snprintf_ss(char *s, size_t n, const char *format, ...);

int sprintf(char *s, const char *format, ...);

int sprintf_l(char *s, locale_t locale, const char *format, ...);

int vasprintf_l(char **ret, locale_t locale, const char *format, va_list ap);

int vfprintf(FILE *stream, const char *format, va_list ap);

int vfprintf_l(FILE *stream, locale_t locale, const char *format, va_list ap);

int vprintf(const char *format, va_list ap);

int vprintf_l(locale_t locale, const char *format, va_list ap);

int vdprintf(int fd, const char * format, va_list ap);

int vdprintf_l(int fd, locale_t locale, const char * format, va_list ap);

int vsnprintf(char *s, size_t n, const char *format, va_list ap);

int vsnprintf_l(char *s, size_t n, locale_t locale, const char *format, va_list ap);

int vsnprintf_ss(char *s, size_t n, const char *format, va_list ap);

int vsprintf(char *s, const char *format, va_list ap);

int vsprintf_l(char *s, locale_t locale, const char *format, va_list ap);

int vasprintf(char **ret, const char *format, va_list ap);

#include <wchar.h>

#include <locale.h>

int aswprintf(wchar_t **ret, wchar_t const *format, ...);

int aswprintf_l(wchar_t **ret, locale_t locale, wchar_t const *format, ...);

int fwprintf(FILE *stream, const wchar_t *format, ...);

int fwprintf_l(FILE *stream, locale_t locale, const wchar_t *format, ...);

int swprintf(wchar_t *s, size_t n, const wchar_t *format, ...);

int vfwprintf(FILE *stream, const wchar_t *format, va_list ap);

int vfwprintf_l(FILE *stream, locale_t locale, const wchar_t *format, va_list ap);

int vswprintf(wchar_t *stream, size_t n, const wchar_t *format, va_list ap);

int wprintf(const wchar_t *format, ...);

int wprintf_l(locale_t locale, const wchar_t *format, ...);

int vwprintf(const wchar_t *format, va_list ap);

int vwprintf_l(locale_t locale, const wchar_t *format, va_list ap);

These functions create formatted output. The fprintf() and vfprintf() functions print to the specified stream. The printf() and vprintf() functions print on the standard output stream stdout. The functions dprintf() and vdprintf() outout to the specified file descriptor. The snprintf(), sprintf(), vsnprintf(), and vsprintf() functions generate their output in the specified string buffers, followed by a terminating null. The snprintf(), snprintf_ss(), vsnprintf() and vsnprintf_ss() functions generate at most the specified number of characters, while the sprintf() and vsprintf() functions continue generating output until their format is exhausted. The asprintf() and vasprintf() functions set *ret to be a pointer to a buffer sufficiently large to hold the formatted string. This pointer should be passed to free(3)() to release the allocated storage when it is no longer needed. If sufficient space cannot be allocated, asprintf() and vasprintf() will return -1 and set ret to be a NULL pointer.

The aswprintf(), fwprintf(), swprintf(), vfwprintf(), vaswprintf(), vswprintf(), wprintf(), and vwprintf() functions are wide character versions of asprintf(), fprintf(), sprintf(), vfprintf(), vasprintf(), vsprintf(), printf() and vprintf() respectively. In all other ways, the wide character versions of these functions behave in an identical fashion to the narrow character versions.

Many of the printf() family of functions have an _l() variant. These functions are used to convert formatted output in the locale locale (perhaps returned from newlocale(). They behave in the same way as the versions without the _l suffix, but use the specified locale rather than the global or per-thread locale.

These functions convert, format, and print their arguments under control of the format. The format is a character string that contains three types of objects:

Plain characters copied to the output stream

Escape sequences that represent non-graphic characters

Conversion specifications

The following escape sequences produce the associated action on display devices that are capable of the action:

\a (Alert): Ring the bell.
\b (Backspace): Move the printing position to one character before the current position, unless the current position is the start of a line.
\f (Form Feed): Move the printing position to the initial printing position of the next logical page.
\n (Newline): Move the printing position to the next line.
\r (Carriage Return): Move the printing position to the start of the current line.
\t (Horizontal Tab): Move the printing position to the next horizontal tab position on the current line.
\v (Vertical Tab): Move the printing position to the start of the next vertical tab position.

The printf() functions let you insert a language-dependent decimal-point character, as defined by the program locale (category LC_NUMERIC). In the C locale or in a locale where the decimal-point character is not defined, the decimal-point character defaults to a period (.).

The % character introduces each conversion specification. The following appear in sequence after the %:

Zero or more flags.

An optional decimal integer to specify the minimum field width. If the converted value has fewer characters than the field width, it is padded on the left (or right, if the left-adjustment flag (-), described below, has been given) to the field width. If the format is %s then the field width should be interpreted as the minimum columns of screen display. For example %10s means if the converted value has a screen width of 7 columns, then 3 spaces would be padded to the right.

An optional precision value, giving the minimum number of digits to appear for the d, i, o, u, x, or X conversions (the field is padded with leading zeros), the number of digits to appear after the decimal-point character for the e, E, and f conversions, the maximum number of significant digits for the g and G conversions, or the maximum number of characters to be printed from a string in s conversion. The precision takes the form of a period (.) followed by a decimal digit string. A NULL digit string is treated as zero. Padding specified by the precision overrides the padding specified by the field width.

An optional h specifies that a following d, i, o, u, x, or X conversion specifier applies to a short int or unsigned short int argument (the argument is promoted according to the integral promotions and its value converted to short int or unsigned short int before printing).

An optional h specifies that a following n conversion specifier applies to a pointer to a short int argument.

An optional h specifies that a following C conversion specifier applies to an argument of type char.

An optional h specifies that a following S conversion specifier applies to a string (char *) argument.

An optional l (lowercase L) specifies that a following d, i, o, u, x, or X conversion specifier applies to a long int or unsigned long int argument.

An optional l (lowercase L) specifies that a following n conversion specifier applies to a pointer to long int parameter.

An optional l (lowercase L) specifies that a following c conversion specifier applies to a wchar_t parameter.

An optional l (lowercase L) specifies that a following s conversion specifier applies to a wide character string (wchar_t *) parameter.

An optional ll (double lowercase L) specifies that a following d, i, o, u, x, or X conversion specifier applies to a quad_t or unsigned quad_t argument.

Note:

While the type quad_t is used here for 64-bit integer, the types long long and __int64 are equivalent and also acceptable.

An optional I32 followed by a d, i, o, u, x, or X conversion specifier is equivalent to l followed by that specifier.

An optional I64 followed by a d, i, o, u, x, or X conversion specifier is equivalent to ll followed by that specifier.

An optional L specifies that a following e, E, f, g, or G conversion specifier applies to a long double parameter.

An optional L followed by a d, i, o, u, x, or X conversion specifier is equivalent to ll followed by that specifier.

An optional q followed by a d, i, o, u, x, or X conversion specifier is equivalent to ll followed by that specifier.

A conversion character that indicates 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 argument of type int supplies the field width or precision. The argument that is actually converted is not fetched until the conversion letter is seen, so the argument specifying field width or precision must appear before the argument (if any) to be converted. If the precision argument is negative, it is changed to zero. A negative field width argument is taken as a - flag, followed by a positive field width.

The flag characters and their meanings are:

-: The result of the conversion is left justified within the field. (It is right justified if this flag is not specified.)
+: The result of a signed conversion always begins with a sign (+ or -). (It begins with a sign only when a negative value is converted if this flag is not specified.)
space: If the first character of a signed conversion is not a sign, a space is placed before the result. This means that if the space and + flags both appear, the space flag is ignored.
#: The value is to be converted to an alternate form. For c, d, I, s, and u conversions, the flag has no effect. For an o conversion, it increases the precision to force the first digit of the result to be zero. For x (or X) conversion, a non-zero result has 0x (or 0X) prepended to it. For e, E, f, g, and G conversions, the result always contains a decimal point (normally, a decimal point appears in the result of these conversions only if a digit follows it). For g and G conversions, trailing zeros are not removed from the result as they normally are.
0: For d, i, o, u, x, X, e, E, f, g, and G conversions, leading zeros (following any indication of sign or base) are used to pad to the field width; no space padding is performed. If the 0 and space flags both appear, the 0 flag is ignored. For d, i, o, u, x, and X conversions, if a precision is specified, the 0 flag is ignored.

Each conversion character results in fetching zero or more arguments. The excess arguments are ignored if the format is exhausted while arguments remain.

The conversion characters and their meanings are:

d

i

o

u

x

X

The int argument is converted to signed decimal (d or i), unsigned octal (o), unsigned decimal (u), or unsigned hexadecimal notation (x and X). The x conversion uses the letters abcdef and the X conversion uses the letters ABCDEF. Additionally the X conversion is the same as using the lx conversion.

The precision specifies the minimum number of digits to appear. If the value being converted can be represented in fewer digits than the specified minimum, it is expanded with leading zeros. The default precision is 1. The result of converting a zero value with a precision of zero is no characters.

D

O

U

Same as ld, lo, or lu respectively.

f

The double argument is converted to decimal notation in the style [-]ddd.ddd, where the number of digits after the decimal-point character (see setlocale()) is equal to the precision specification. If the precision is omitted from the argument, six digits are output; if the precision is explicitly zero and the # flag is not specified, no decimal-point character appears. If a decimal-point character appears, at least 1 digit appears before it. The value is rounded to the appropriate number of digits.

e

E

The double argument is converted to the style [-]d.ddde+dd, where there is one digit before the decimal-point character (which is non-zero if the argument is non-zero) and the number of digits after it is equal to the precision. When the precision is missing, six digits are produced; if the precision is zero and the # flag is not specified, no decimal-point character appears.

The E conversion character produces a number with E instead of e introducing the exponent. The exponent always contains at least two digits. The value is rounded to the appropriate number of digits.

g

G

The double argument is printed in style f or e (or in style E in the case of a G conversion character), with the precision specifying the number of significant digits. If the precision is zero, it is taken as one. The style used depends on the value converted: style e (or E) is used only if the exponent resulting from the 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 character appears only if a digit follows it.

c

The int argument is converted to a char and the resulting character is printed.

s

The argument is taken to be a string (char *) and characters from the string are written up to (but not including) a terminating null character (\0); if the precision is specified, no more that that many characters are written. If the precision is not specified, it is taken to be infinite, so all characters up to the first null character are printed.

C

Same as lc.

S

Same as ls.

p

The argument should be a pointer to void (void *). The value of the pointer is converted to an implementation-defined set of sequences of printable characters, which should be the same as the set of sequences that are matched by the %p conversion of the scanf() functions.

n

The argument should be a pointer to an integer into which is written the number of characters written to the output standard I/O stream so far by this call to printf(). No argument is converted.

%

Print a %; no argument is converted.

If the character after the % sequence is not a valid conversion character the results of the conversion are undefined.

If a floating-point value is the internal representation for infinity, the output is [+]Infinity, where Infinity is either Infinity or Inf, depending on the desired output string length. Printing of the sign follows the rules described above.

If a floating-point value is the internal representation for not-a-number, the output is [+]NaN. Printing of the sign follows the rules described above.

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 simply expanded to contain the conversion result. Characters generated by printf() and vprintf() are printed as if the putc() routine had been called. Characters generated by fprintf() and vfprintf() are printed as if the fputc() routine had been called.

PARAMETERS

stream: Points to the output stream.
format: Is the format string for the following parameters.
s: Is the character string (char *) where output is placed.
n: Is the size of string s.
...: Represents substitution arguments for format.
ap: Is the argument list, of type va_list, containing substitution arguments for format.

RETURN VALUES

If successful, the printf() functions return the number of characters transmitted. If an error occurs, they return a negative value and an errno value is set:

EAGAIN: The O_NONBLOCK flag is set for the file descriptor underlying stream and the process would be delayed in the write operation.
EFBIG: The file is a regular file and an attempt was made to write at or beyond the offset maximum.
EILSEQ: A wide character code that does not correspond to a valid character has been detected
EINTR: A signal interrupted the call.
EIO: A physical I/O error has occurred.
EPIPE: An attempt is made to write to a pipe or FIFO that is not open for reading by any process. A SIGPIPE signal is also sent to the thread.
ENOMEM: Insufficient storage space is available.
ENXIO: A request was made of a non-existent device, or the request was outside the capabilities of the device.

CONFORMANCE

The functions fprintf(), printf(), sprintf(), vprintf(), vfprintf(), and vsprintf() conform to ANSI C and ISO C99 With the same reservation, the snprintf() and vsnprintf() functions conform to ISO C99. The functions asprintf() and vasprintf() are modeled on the ones that first appeared in the GNU C library. The functions snprintf_ss() vsnprintf_ss() is non-standard and appeared in NetBSD 4.0 The functions dprintf() and vdprintf() are parts of POSIX 1003.1-2008

MULTITHREAD SAFETY LEVEL

fprintf(), printf(), snprintf(), sprintf(): MT-Safe, with exceptions.

vfprintf(), vprintf(), vsnprintf(), vsprintf(): MT-Safe, with exceptions.

These functions are MT-Safe as long as no thread calls setlocale() while these functions are executing.

PORTING ISSUES

The NuTCRACKER Platform implementation of the printf() functions add several additional conversion specification characters to those defined by UNIX 98; these are all detailed in the DESCRIPTION section. The NuTCRACKER Platform implementation currently does not recognize the %n$ positional-parameter specifier defined in UNIX 98.

AVAILABILITY

PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Professional Developers 64-Bit Edition
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition

printf, printf_l
print formatted output

Command