'\" et

.TH FPRINTF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual"

.SH PROLOG

This manual page is part of the POSIX Programmer's Manual.

The Linux implementation of this interface may differ (consult

the corresponding Linux manual page for details of Linux behavior),

or the interface may not be implemented on Linux.

.SH NAME

dprintf,

fprintf,

printf,

snprintf,

sprintf

\(em print formatted output

.SH SYNOPSIS

.LP

.nf

#include <stdio.h>

.P

int dprintf(int \fIfildes\fP, const char *restrict \fIformat\fP, ...);

int fprintf(FILE *restrict \fIstream\fP, const char *restrict \fIformat\fP, ...);

int printf(const char *restrict \fIformat\fP, ...);

int snprintf(char *restrict \fIs\fP, size_t \fIn\fP,

    const char *restrict \fIformat\fP, ...);

int sprintf(char *restrict \fIs\fP, const char *restrict \fIformat\fP, ...);

.fi

.SH DESCRIPTION

Excluding

\fIdprintf\fR():

The functionality described on this reference page is aligned with the

ISO\ C standard. Any conflict between the requirements described here and the

ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard.

.P

The

\fIfprintf\fR()

function shall place output on the named output

.IR stream .

The

\fIprintf\fR()

function shall place output on the standard output stream

.IR stdout .

The

\fIsprintf\fR()

function shall place output followed by the null byte,

.BR '\e0' ,

in consecutive bytes starting at *\fIs\fP; it is the user's

responsibility to ensure that enough space is available.

.P

The

\fIdprintf\fR()

function shall be equivalent to the

\fIfprintf\fR()

function, except that

\fIdprintf\fR()

shall write output to the file associated with the file descriptor

specified by the

.IR fildes

argument rather than place output on a stream.

.P

The

\fIsnprintf\fR()

function shall be equivalent to

\fIsprintf\fR(),

with the addition of the

.IR n

argument which states the size of the buffer referred to by

.IR s .

If

.IR n

is zero, nothing shall be written and

.IR s

may be a null pointer. Otherwise, output bytes beyond the

.IR n \(hy1st

shall be discarded instead of being written to the array, and a null

byte is written at the end of the bytes actually written into the

array.

.P

If copying takes place between objects that overlap as a result of a

call to

\fIsprintf\fR()

or

\fIsnprintf\fR(),

the results are undefined.

.P

Each of these functions converts, formats, and prints its arguments

under control of the

.IR format .

The

.IR format

is a character string, beginning and ending in its initial shift state,

if any. The

.IR format

is composed of zero or more directives:

.IR "ordinary characters" ,

which are simply copied to the output stream, and

.IR "conversion specifications" ,

each of which shall result in the fetching of zero or more arguments.

The results are undefined if there are insufficient arguments for the

.IR format .

If the

.IR format

is exhausted while arguments remain, the excess arguments shall be

evaluated but are otherwise ignored.

.P

Conversions can be applied to the

.IR n th

argument after the

.IR format

in the argument list, rather than to the next unused argument. In this

case, the conversion specifier character

.BR %

(see below) is replaced by the sequence \fR"%\fIn\fR$"\fR, where

.IR n

is a decimal integer in the range [1,{NL_ARGMAX}],

giving the position of the argument in the argument list. This feature

provides for the definition of format strings that select arguments in

an order appropriate to specific languages (see the EXAMPLES section).

.P

The

.IR format

can contain either numbered argument conversion specifications (that

is, \fR"%\fIn\fR$"\fR and \fR"*\fIm\fR$"\fR), or unnumbered argument

conversion specifications (that is,

.BR %

and

.BR * ),

but not both. The only exception to this is that

.BR %%

can be mixed with the \fR"%\fIn\fR$"\fR form. The results of mixing

numbered and unnumbered argument specifications in a

.IR format

string are undefined. When numbered argument specifications are used,

specifying the

.IR N th

argument requires that all the leading arguments, from the first to the

(\fIN\(mi1\fP)th, are specified in the format string.

.P

In format strings containing the \fR"%\fIn\fR$"\fR form of conversion

specification, numbered arguments in the argument list can be

referenced from the format string as many times as required.

.P

In format strings containing the

.BR %

form of conversion specification, each conversion specification uses

the first unused argument in the argument list.

.P

All forms of the

\fIfprintf\fR()

functions allow for the insertion of a language-dependent radix

character in the output string. The radix character is defined in the

current locale (category

.IR LC_NUMERIC ).

In the POSIX locale, or in a locale where the radix character is not

defined, the radix character shall default to a

<period>

(\c

.BR '.' ).

.P

Each conversion specification is introduced by the

.BR '%' 

character

or by the character sequence \fR"%\fIn\fR$"\fR,

after which the following appear in sequence:

.IP " *" 4

Zero or more

.IR flags

(in any order), which modify the meaning of the conversion

specification.

.IP " *" 4

An optional minimum

.IR "field width" .

If the converted value has fewer bytes than the field width, it shall

be padded with

<space>

characters by default on the left; it shall be padded on the right if

the left-adjustment flag (\c

.BR '\(mi' ),

described below, is given to the field width. The field width takes the

form of an

<asterisk>

(\c

.BR '*' ),

described below, or a decimal integer.

.IP " *" 4

An optional

.IR precision

that gives the minimum number of digits to appear for the

.BR d ,

.BR i ,

.BR o ,

.BR u ,

.BR x ,

and

.BR X

conversion specifiers; the number of digits to appear after the radix

character for the

.BR a ,

.BR A ,

.BR e ,

.BR E ,

.BR f ,

and

.BR F

conversion specifiers; the maximum number of significant digits for the

.BR g

and

.BR G

conversion specifiers; or the maximum number of bytes to be printed

from a string in the

.BR s

and

.BR S

conversion specifiers. The precision takes the form of a

<period>

(\c

.BR '.' )

followed either by an

<asterisk>

(\c

.BR '*' ),

described below, or an optional decimal digit string, where a null

digit string is treated as zero. If a precision appears with any other

conversion specifier, the behavior is undefined.

.IP " *" 4

An optional length modifier that specifies the size of the argument.

.IP " *" 4

A

.IR "conversion specifier"

character that indicates the type of conversion to be applied.

.P

A field width, or precision, or both, may be indicated by an

<asterisk>

(\c

.BR '*' ).

In this case an argument of type

.BR int

supplies the field width or precision. Applications shall ensure that

arguments specifying field width, or precision, or both appear in that

order before the argument, if any, to be converted. A negative field

width is taken as a

.BR '\(mi' 

flag followed by a positive field width. A negative precision is taken

as if the precision were omitted.

In

.IR format

strings containing the \fR"%\fIn\fR$"\fR form of a

conversion specification, a field width or precision may be indicated

by the sequence \fR"*\fIm\fR$"\fR, where

.IR m

is a decimal integer in the range [1,{NL_ARGMAX}] giving the position

in the argument list (after the

.IR format

argument) of an integer argument containing the field width or

precision, for example:

.sp

.RS 4

.nf

\fB

printf("%1$d:%2$.*3$d:%4$.*3$d\en", hour, min, precision, sec);

.fi \fR

.P

.RE

.P

The flag characters and their meanings are:

.IP "\fR'\fR" 8

(The

<apostrophe>.)

The integer portion of the result of a decimal conversion (\c

.BR %i ,

.BR %d ,

.BR %u ,

.BR %f ,

.BR %F ,

.BR %g ,

or

.BR %G )

shall be formatted with thousands' grouping characters. For other

conversions the behavior is undefined. The non-monetary grouping

character is used.

.IP "\fR\(mi\fR" 8

The result of the conversion shall be left-justified within the field.

The conversion is right-justified if this flag is not specified.

.IP "\fR+\fR" 8

The result of a signed conversion shall always begin with a sign (\c

.BR '+' 

or

.BR '\(mi' ).

The conversion shall begin with a sign only when a negative value is

converted if this flag is not specified.

.IP <space> 8

If the first character of a signed conversion is not a sign or if a

signed conversion results in no characters, a

<space>

shall be prefixed to the result. This means that if the

<space>

and

.BR '+' 

flags both appear, the

<space>

flag shall be ignored.

.IP "\fR#\fR" 8

Specifies that the value is to be converted to an alternative

form. For

.BR o

conversion, it increases the precision (if necessary) to force the

first digit of the result to be zero. For

.BR x

or

.BR X

conversion specifiers, a non-zero result shall have 0x (or 0X) prefixed

to it. For

.BR a ,

.BR A ,

.BR e ,

.BR E ,

.BR f ,

.BR F ,

.BR g ,

and

.BR G

conversion specifiers, the result shall always contain a radix

character, even if no digits follow the radix character. Without this

flag, a radix character appears in the result of these conversions only

if a digit follows it. For

.BR g

and

.BR G

conversion specifiers, trailing zeros shall

.IR not

be removed from the result as they normally are. For other conversion

specifiers, the behavior is undefined.

.IP "\fR0\fR" 8

For

.BR d ,

.BR i ,

.BR o ,

.BR u ,

.BR x ,

.BR X ,

.BR a ,

.BR A ,

.BR e ,

.BR E ,

.BR f ,

.BR F ,

.BR g ,

and

.BR G

conversion specifiers, leading zeros (following any indication of sign

or base) are used to pad to the field width rather than performing

space padding, except when converting an infinity or NaN. If the

.BR '0' 

and

.BR '\(mi' 

flags both appear, the

.BR '0' 

flag is ignored. For

.BR d ,

.BR i ,

.BR o ,

.BR u ,

.BR x ,

and

.BR X

conversion specifiers, if a precision is specified, the

.BR '0' 

flag shall be ignored.

If the

.BR '0' 

and

<apostrophe>

flags both appear, the grouping characters are inserted before zero

padding. For other conversions, the behavior is undefined.

.P

The length modifiers and their meanings are:

.IP "\fRhh\fR" 8

Specifies that a following

.BR d ,

.BR i ,

.BR o ,

.BR u ,

.BR x ,

or

.BR X

conversion specifier applies to a

.BR "signed char"

or

.BR "unsigned char"

argument (the argument will have been promoted according to the integer

promotions, but its value shall be converted to

.BR "signed char"

or

.BR "unsigned char"

before printing); or that a following

.BR n

conversion specifier applies to a pointer to a

.BR "signed char"

argument.

.IP "\fRh\fR" 8

Specifies that a following

.BR d ,

.BR i ,

.BR o ,

.BR u ,

.BR x ,

or

.BR X

conversion specifier applies to a

.BR "short"

or

.BR "unsigned short"

argument (the argument will have been promoted according to the integer

promotions, but its value shall be converted to

.BR "short"

or

.BR "unsigned short"

before printing); or that a following

.BR n

conversion specifier applies to a pointer to a

.BR "short"

argument.

.IP "\fRl\fR\ (ell)" 8

Specifies that a following

.BR d ,

.BR i ,

.BR o ,

.BR u ,

.BR x ,

or

.BR X

conversion specifier applies to a

.BR "long"

or

.BR "unsigned long"

argument; that a following

.BR n

conversion specifier applies to a pointer to a

.BR "long"

argument; that a following

.BR c

conversion specifier applies to a

.BR wint_t

argument; that a following

.BR s

conversion specifier applies to a pointer to a

.BR wchar_t

argument; or has no effect on a following

.BR a ,

.BR A ,

.BR e ,

.BR E ,

.BR f ,

.BR F ,

.BR g ,

or

.BR G

conversion specifier.

.IP "\fRll\fR\ (ell-ell)" 8

.br

Specifies that a following

.BR d ,

.BR i ,

.BR o ,

.BR u ,

.BR x ,

or

.BR X

conversion specifier applies to a

.BR "long long"

or

.BR "unsigned long long"

argument; or that a following

.BR n

conversion specifier applies to a pointer to a

.BR "long long"

argument.

.IP "\fRj\fR" 8

Specifies that a following

.BR d ,

.BR i ,

.BR o ,

.BR u ,

.BR x ,

or

.BR X

conversion specifier applies to an

.BR intmax_t

or

.BR uintmax_t

argument; or that a following

.BR n

conversion specifier applies to a pointer to an

.BR intmax_t

argument.

.IP "\fRz\fR" 8

Specifies that a following

.BR d ,

.BR i ,

.BR o ,

.BR u ,

.BR x ,

or

.BR X

conversion specifier applies to a

.BR size_t

or the corresponding signed integer type argument; or that a following

.BR n

conversion specifier applies to a pointer to a signed integer type

corresponding to a

.BR size_t

argument.

.IP "\fRt\fR" 8

Specifies that a following

.BR d ,

.BR i ,

.BR o ,

.BR u ,

.BR x ,

or

.BR X

conversion specifier applies to a

.BR ptrdiff_t

or the corresponding

.BR unsigned

type argument; or that a following

.BR n

conversion specifier applies to a pointer to a

.BR ptrdiff_t

argument.

.IP "\fRL\fR" 8

Specifies that a following

.BR a ,

.BR A ,

.BR e ,

.BR E ,

.BR f ,

.BR F ,

.BR g ,

or

.BR G

conversion specifier applies to a

.BR "long double"

argument.

.P

If a length modifier appears with any conversion specifier other than

as specified above, the behavior is undefined.

.P

The conversion specifiers and their meanings are:

.IP "\fRd\fR,\ \fRi\fR" 8

The

.BR int

argument shall be converted to a signed decimal in the style

\fR"[\(mi]\fIdddd\fR"\fR. The precision specifies the minimum number of

digits to appear; if the value being converted can be represented in

fewer digits, it shall be expanded with leading zeros. The default

precision is 1. The result of converting zero with an explicit

precision of zero shall be no characters.

.IP "\fRo\fP" 8

The

.BR unsigned

argument shall be converted to unsigned octal format in the style

\fR"\fIdddd\fR"\fR. The precision specifies the minimum number of

digits to appear; if the value being converted can be represented in

fewer digits, it shall be expanded with leading zeros. The default

precision is 1. The result of converting zero with an explicit

precision of zero shall be no characters.

.IP "\fRu\fP" 8

The

.BR unsigned

argument shall be converted to unsigned decimal format in the style

\fR"\fIdddd\fR"\fR. The precision specifies the minimum number of

digits to appear; if the value being converted can be represented in

fewer digits, it shall be expanded with leading zeros. The default

precision is 1. The result of converting zero with an explicit

precision of zero shall be no characters.

.IP "\fRx\fP" 8

The

.BR unsigned

argument shall be converted to unsigned hexadecimal format in the

style \fR"\fIdddd\fR"\fR; the letters

.BR \(dqabcdef\(dq 

are used. The precision specifies the minimum number of digits to

appear; if the value being converted can be represented in fewer

digits, it shall be expanded with leading zeros. The default precision

is 1. The result of converting zero with an explicit precision of zero

shall be no characters.

.IP "\fRX\fP" 8

Equivalent to the

.BR x

conversion specifier, except that letters

.BR \(dqABCDEF\(dq 

are used instead of

.BR \(dqabcdef\(dq .

.IP "\fRf\fR,\ \fRF\fR" 8

The

.BR double

argument shall be converted to decimal notation in the style

\fR"[\(mi]\fIddd\fR.\fIddd\fR"\fR, where the number of digits after the

radix character is equal to the precision specification. If the

precision is missing, it shall be taken as 6; if the precision is

explicitly zero and no

.BR '#' 

flag is present, no radix character shall appear. If a radix character

appears, at least one digit appears before it. The low-order digit

shall be rounded in an implementation-defined manner.

.RS 8 

.P

A

.BR double

argument representing an infinity shall be converted in one of the

styles

.BR \(dq[\(mi]inf\(dq 

or

.BR \(dq[\(mi]infinity\(dq ;

which style is implementation-defined. A

.BR double

argument representing a NaN shall be converted in one of the styles

\fR"[\(mi]nan(\fIn-char-sequence\fR)"\fR or

.BR \(dq[\(mi]nan\(dq ;

which style, and the meaning of any

.IR n-char-sequence ,

is implementation-defined. The

.BR F

conversion specifier produces

.BR \(dqINF\(dq ,

.BR \(dqINFINITY\(dq ,

or

.BR \(dqNAN\(dq 

instead of

.BR \(dqinf\(dq ,

.BR \(dqinfinity\(dq ,

or

.BR \(dqnan\(dq ,

respectively.

.RE

.IP "\fRe\fR,\ \fRE\fR" 8

The

.BR double

argument shall be converted in the style

\fR"[\(mi]\fId\fR.\fIddd\fRe\(+-\fIdd\fR"\fR, where there is one digit

before the radix character (which is non-zero if the argument is

non-zero) and the number of digits after it is equal to the precision;

if the precision is missing, it shall be taken as 6; if the precision

is zero and no

.BR '#' 

flag is present, no radix character shall appear. The low-order digit

shall be rounded in an implementation-defined manner. The

.BR E

conversion specifier shall produce a number with

.BR 'E' 

instead of

.BR 'e' 

introducing the exponent. The exponent shall always contain at least

two digits. If the value is zero, the exponent shall be zero.

.RS 8 

.P

A

.BR double

argument representing an infinity or NaN shall be converted in

the style of an

.BR f

or

.BR F

conversion specifier.

.RE

.IP "\fRg\fR,\ \fRG\fR" 8

The

.BR double

argument representing a floating-point number shall be converted in the

style

.BR f

or

.BR e

(or in the style

.BR F

or

.BR E

in the case of a

.BR G

conversion specifier), depending on the value converted and the precision.

Let

.BR P

equal the precision if non-zero, 6 if the precision is omitted, or 1 if the

precision is zero. Then, if a conversion with style

.BR E

would have an exponent of

.IR X :

.RS 8 

.IP -- 4

If

.BR P >\c

.IR X \(>=\(mi4,

the conversion shall be with style

.BR f

(or

.BR F )

and precision

.BR P \(mi(\c

.IR X +1).

.IP -- 4

Otherwise, the conversion shall be with style

.BR e

(or

.BR E )

and precision

.BR P \(mi1.

.P

Finally, unless the

.BR '#' 

flag is used, any trailing zeros shall be removed from the fractional

portion of the result and the decimal-point character shall be removed

if there is no fractional portion remaining.

.P

A

.BR double

argument representing an infinity or NaN shall be converted in the

style of an

.BR f

or

.BR F

conversion specifier.

.RE

.IP "\fRa\fR,\ \fRA\fR" 8

A

.BR double

argument representing a floating-point number shall be converted in the

style \fR"[\(mi]0x\fIh\fR.\fIhhhh\fRp\(+-\fId\fR"\fR, where there is

one hexadecimal digit (which shall be non-zero if the argument is a

normalized floating-point number and is otherwise unspecified) before

the decimal-point character and the number of hexadecimal digits after

it is equal to the precision; if the precision is missing and FLT_RADIX

is a power of 2, then the precision shall be sufficient for an exact

representation of the value; if the precision is missing and FLT_RADIX

is not a power of 2, then the precision shall be sufficient to

distinguish values of type

.BR double ,

except that trailing zeros may be omitted; if the precision is zero and

the

.BR '#' 

flag is not specified, no decimal-point character shall appear. The

letters

.BR \(dqabcdef\(dq 

shall be used for

.BR a

conversion and the letters

.BR \(dqABCDEF\(dq 

for

.BR A

conversion. The

.BR A

conversion specifier produces a number with

.BR 'X' 

and

.BR 'P' 

instead of

.BR 'x' 

and

.BR 'p' .

The exponent shall always contain at least one digit, and only as many

more digits as necessary to represent the decimal exponent of 2. If the

value is zero, the exponent shall be zero.

.RS 8 

.P

A

.BR double

argument representing an infinity or NaN shall be converted in the

style of an

.BR f

or

.BR F

conversion specifier.

.RE

.IP "\fRc\fP" 8

The

.BR int

argument shall be converted to an

.BR "unsigned char" ,

and the resulting byte shall be written.

.RS 8 

.P

If an

.BR l

(ell) qualifier is present, the

.BR wint_t

argument shall be converted as if by an

.BR ls

conversion specification with no precision and an argument that points

to a two-element array of type

.BR wchar_t ,

the first element of which contains the

.BR wint_t

argument to the

.BR ls

conversion specification and the second element contains a null wide

character.

.RE

.IP "\fRs\fP" 8

The argument shall be a pointer to an array of

.BR char .

Bytes from the array shall be written up to (but not including) any

terminating null byte. If the precision is specified, no more than that

many bytes shall be written. If the precision is not specified or is

greater than the size of the array, the application shall ensure that

the array contains a null byte.

.RS 8 

.P

If an

.BR l

(ell) qualifier is present, the argument shall be a pointer to an array

of type

.BR wchar_t .

Wide characters from the array shall be converted to characters (each

as if by a call to the

\fIwcrtomb\fR()

function, with the conversion state described by an

.BR mbstate_t

object initialized to zero before the first wide character is

converted) up to and including a terminating null wide character. The

resulting characters shall be written up to (but not including) the

terminating null character (byte). If no precision is specified, the

application shall ensure that the array contains a null wide character.

If a precision is specified, no more than that many characters (bytes)

shall be written (including shift sequences, if any), and the array

shall contain a null wide character if, to equal the character sequence

length given by the precision, the function would need to access a wide

character one past the end of the array. In no case shall a partial

character be written.

.RE

.IP "\fRp\fP" 8

The argument shall be a pointer to

.BR void .

The value of the pointer is converted to a sequence of printable

characters, in an implementation-defined manner.

.IP "\fRn\fP" 8

The argument shall be a pointer to an integer into which is written the

number of bytes written to the output so far by this call to one of the

\fIfprintf\fR()

functions. No argument is converted.

.IP "\fRC\fP" 8

Equivalent to

.BR lc .

.IP "\fRS\fP" 8

Equivalent to

.BR ls .

.IP "\fR%\fR" 8

Print a

.BR '%' 

character; no argument is converted. The complete conversion

specification shall be

.BR %% .

.P

If a conversion specification does not match one of the above forms,

the behavior is undefined. If any argument is not the correct type for

the corresponding conversion specification, the behavior is undefined.

.P

In no case shall a nonexistent or small field width cause truncation of

a field; if the result of a conversion is wider than the field width,

the field shall be expanded to contain the conversion result.

Characters generated by

\fIfprintf\fR()

and

\fIprintf\fR()

are printed as if

\fIfputc\fR()

had been called.

.P

For the

.BR a

and

.BR A

conversion specifiers, if FLT_RADIX is a power of 2, the value shall be

correctly rounded to a hexadecimal floating number with the given

precision.

.P

For

.BR a

and

.BR A

conversions, if FLT_RADIX is not a power of 2 and the result is not