PRINTF(3s,L) AIX Technical Reference PRINTF(3s,L)
-------------------------------------------------------------------------------
printf, fprintf, sprintf, NLprintf, NLfprintf, NLsprintf, wsprintf
PURPOSE
Prints formatted output.
LIBRARY
Standard I/O Library (libc.a)
SYNTAX
#include <stdio.h>
int printf ( fmt [, val, ...int NLprintf ( fmt [, val, ... ])
char *fmt; char *fmt;
int fprintf (stream, fmt [, int,NLfprintf (stream, fmt [, val, ... ])
FILE *stream; FILE *stream;
char *fmt; char *fmt;
int sprintf (s, fmt [, val, int NLsprintf (s, fmt [, val, ... ])
char *s, *fmt; char *s, *fmt;
int wsprintf (scs, fmt [,val,...])
wchar_t *wcs;
char *fmt;
DESCRIPTION
The printf subroutine converts, formats, and writes its val parameters, under
control of the fmt parameter, to the standard output stream stdout.
The fprintf subroutine converts, formats, and writes its val parameters, under
control of the fmt parameter, to the output stream specified by its stream
parameter.
The sprintf subroutine converts, formats, and stores its val parameters, under
control of the fmt parameter, into consecutive bytes starting at the address
specified by the s parameter. The sprintf subroutine places a "'\0'" (null
character) at the end. It is your responsibility to ensure that enough storage
space is available to contain the formatted string.
Processed November 7, 1990 PRINTF(3s,L) 1
PRINTF(3s,L) AIX Technical Reference PRINTF(3s,L)
The wsprintf subroutine is equivalent to sprintf except that the argument wcs
specifies an array of wide characters into which the generated output is
written. A NULL wide character is appended at the end of the array, but it is
not counted as part of the returned sum. If copying takes place between
objects that overlap, the behavior is undefined.
The NLprintf, NLfprintf, and NLsprintf subroutines are provided for backward
compatibility and behave exactly like the printf, fprintf, and sprintf
subroutines respectively.
The fmt parameter is a character string that contains two types of objects:
o Plain characters, which are copied to the output stream.
o Conversion specifications, each of which causes zero or more items to be
fetched from the val parameter list.
If there are not enough items for the fmt in the val parameter list, then the
results are unpredictable. If more vals remain after the entire fmt has been
processed, they are ignored.
Conversions can be applied to the nth argument in the argument list, rather
than to the next unused argument. In this case, the conversion character "%"
is replaced by the sequence "%digit$", where digit is a decimal integer n in
the range of [1, {NL_ARGMAX}], giving the position of the argument in the
argument list. With this feature, format strings can be defined to assure that
arguments are selected in an order appropriate for the specified language.
Each conversion specification in the fmt parameter has the following syntax:
o A "%" (percent) sign or the character sequence "%digit$", which introduces
the conversion specification.
o Zero or more options, which modify the meaning of the conversion
specification. The option characters and their meanings are:
"-" The result of the conversion is left-justified within the field.
"+" The result of a signed conversion always begins with a sign ("+" or
"-").
blank If the first character of a signed conversion is not a sign, a blank
is prefixed to the result. If both the blank and "+" options
appear, then the blank option is ignored.
"#" This option specifies that the value is to be converted to an
alternate form. For c, d, s, and u conversions, the option has no
effect. For o conversion, it increases the precision to force the
first digit of the result to be a "0". For x and X conversions, a
nonzero result has "0x" or "0X" prefixed to it. For e, E, f, g, and
G conversions, the result always contains a decimal point, even if
Processed November 7, 1990 PRINTF(3s,L) 2
PRINTF(3s,L) AIX Technical Reference PRINTF(3s,L)
no digits follow the decimal point. For g and G conversions,
trailing zeros are not removed from the result.
B This option affects conversions using the s or S conversion
characters of the NLprintf, NLfprintf, and NLsprintf subroutines
only. The B flag specifies that field width and precision are given
in bytes rather than in code points.
N This option affects the s and S conversion characters of the
NLprintf, NLfprintf, and NLsprintf subroutines only. The N flag
specifies that each international character support code point in
the converted string converts into a printable ASCII escape sequence
that uniquely identifies the code point.
o An optional decimal digit string that specifies the minimum field width.
If the converted value has fewer characters than the field width, the field
is padded on the left to the length specified by the field width. If the
left-adjustment option is specified, the field is padded on the right. For
the NLprintf, NLfprintf, and NLsprintf subroutines, field width is measured
in code points rather than bytes, unless the B flag is specified.
o An optional precision. The precision is a "." (period) followed by a
decimal digit string. If no precision is given, it is treated as 0. The
precision specifies:
- The minimum number of digits to appear for the d, i, u, o, x, or X
conversions
- The number of digits to appear after the decimal point for the e and f
conversions
- The maximum number of significant digits for the g conversion
- The maximum number of characters to be printed from a string in the s
conversion.
o An optional l (the letter "ell") specifying that a following d, i, u, o, x,
or X conversion character applies to a long integer val. With printf, an
optional L specifying that a following d, i, u, o, x, or X conversion
character applies to a long double val.
o A character that indicates the type of conversion to be applied:
"%" Performs no conversion. Prints a "%".
Note: If the character after the "%" or "%digit$" sequence is not a
valid conversion character, the results of the conversion are
undefined.
d, i Accepts an integer val and converts it to signed decimal notation.
The precision specifies the minimum number of digits to appear. If
the value being converted can be represented in fewer digits, it is
expanded with leading zeros. The default precision is 1. The result
of converting a 0 value with a precision of 0 is a null string.
Processed November 7, 1990 PRINTF(3s,L) 3
PRINTF(3s,L) AIX Technical Reference PRINTF(3s,L)
Specifying a field width with a zero as a leading character causes
the field width value to be padded with leading zeros.
Note: i applies to printf only.
u Accepts an integer value and converts it to unsigned decimal
notation. The precision specifies the minimum number of digits to
appear. If the value being converted can be represented in fewer
digits, it is expanded with leading zeros. The default precision is
1. The result of converting a 0 value with a precision of 0 is a
null string. Specifying a field width with a zero as a leading
character causes the field width value to be padded with leading
zeros.
o Accepts an integer val and converts it to octal notation. The
precision specifies the minimum number of digits to appear. If the
value being converted can be represented in fewer digits, it is
expanded with leading zeros. The default precision is 1. The result
of converting a 0 value with a precision of 0 is a null string.
Specifying a field width with a zero as a leading character causes
the field width value to be padded with leading zeros.
An octal value for field width is not implied.
x, X Accepts an integer val and converts it to hexadecimal notation. The
letters "abcdef" are used for the x conversion and the letters
"ABCDEF" are used for the X conversion. The precision specifies the
minimum number of digits to appear. If the value being converted can
be represented in fewer digits, it is expanded with leading zeros.
The default precision is 1. The result of converting a 0 value with
a precision of 0 is a null string. Specifying a field width with a
zero as a leading character causes the field width value to be padded
with leading zeros.
f Accepts a float or double val and converts it to decimal notation in
the format [-]ddd.ddd. The number of digits after the decimal point
is equal to the precision specification. If no precision is
specified, then six digits are output. If the precision is 0, then
no decimal point appears.
e, E Accepts a float or double val and converts it to the exponential form
[-]d.ddde+/-dd. There is one digit before the decimal point and the
number of digits after the decimal point is equal to the precision
specification. If no precision is specified, then six digits are
output. If the precision is 0, then no decimal point appears. The E
conversion character produces a number with E instead of e before the
exponent. The exponent always contains at least two digits.
g, G Accepts a float or double val and converts it in the style of the e,
E or f conversion characters, with the precision specifying the
number of significant digits. Trailing zeros are removed from the
result. A decimal point appears only if it is followed by a digit.
Processed November 7, 1990 PRINTF(3s,L) 4
PRINTF(3s,L) AIX Technical Reference PRINTF(3s,L)
The style used depends on the value converted. Style e (E, if G is
the flag used) results only if the exponent resulting from the
conversion is less than -4, or if it is greater than or equal to the
precision.
c Accepts and prints the character val.
C Prints one NLchar. Applies to NLprintf only.
s Accepts a val is as a string (character pointer) and characters from
the string are printed until a "'\0'" (null character) is encountered
or the number of characters indicated by the precision is reached.
If no precision is specified, all characters up to the first null
character are printed. If the string pointer val has a value of 0 or
NULL, the results are undefined.
S The corresponding NLprintf, NLfprintf, or NLsprintf val is taken to
be a pointer to a string of the type NLchar. Characters from the
string are printed until a "\0" (null) character is encountered or
the number of characters indicated by precision is reached. If no
precision is specified, all characters up to the first null character
are printed. If the string pointer val has a value of 0 or NULL, the
results are undefined.
n Accepts a pointer to an integer. The number of characters
successfully written so far to the stream or buffer is stored in the
integer whose address is given as the argument. Applies to printf
only.
p Accepts an integer val and converts it to hexidecimal notation. The
precision specifies the minimum number of digits to appear. If the
value being converted can be represented in fewer digits, it is
expanded with leading zeros. The default precision is 1. The result
of converting a 0 value with a precision of 0 is a null string.
Specifying a field width with a zero as a leading character causes
the field with value to be padded with zeros. This type of
conversion applies to NLprintf only.
%wc The wchar_t type argument is converted to an array of characters and
the resulting multibyte characters are written. If the resulting
multibyte characters contain fewer bytes than the specified field
width, the field is padded with blank characters. Precision is
ignored, even if specified. This conversion is the same as that
performed by the wctomb subroutine.
%ws The argument is a pointer to a wchar_t type array. Wide characters
from the array are converted to multibyte characters and the
resulting multibyte characters are written up to (but no including) a
terminating NULL wide character. If both the precision and the "#"
are specified, the number of wide characters written cannot exceed
the number of bytes specified by the precision; if only precision is
specified, the number of characters written is equal to the precision
Processed November 7, 1990 PRINTF(3s,L) 5
PRINTF(3s,L) AIX Technical Reference PRINTF(3s,L)
number. If the precision is not specified or it is greater than the
size of the array, the array contains a NULL character. If the
resulting multibyte characters have fewer bytes than the specified
field width, the field will be padded with blanks. This conversion
is the same as that performed by the wcstombs subroutine.
A field width or precision may be indicated by an * (asterisk) instead of a
digit string. In this case, an integer val parameter supplies the field width
or precision. The val parameter that is converted for output is not fetched
until the conversion letter is reached, so the parameters specifying field
width or precision must appear before the value (if any) to be converted.
If the result of a conversion is wider than the field width, then the field is
expanded to contain the converted result. No truncation occurs. However, a
small precision may cause truncation on the right.
The e, E, f and g formats represent the special floating-point values as
follows:
Quiet NaN "+QNaN" or "-QNaN"
Signalling NaN "+SNaN" or "-SNaN"
+/-infinity "+INF" or "-INF"
+/-0 "+0" or "-0"
The representation of the plus sign depends on whether the + or blank
formatting option is specified.
RETURN VALUE
Upon successful completion, each of these subroutines except wsprintf returns
the number of display characters in the output string rather than the number of
bytes in the string. (The NLprintf, NLfprintf and NLsprintf subroutines use
strings that may contain 2-byte NLchars.) The value returned by sprintf and
NLsprintf does not include the final "'\0'" character. If an output error
occurs, a negative value is returned.
The wsprintf subroutine returns the number of wide characters written into the
array, not counting the terminating NULL wide character.
EXAMPLE
To print the language-dependent date and time format, the following statement
could be used:
printf (format, weekday, month, day, hour, min);
For American usage, format could be a pointer to the string:
%1$s, %2$s %3$d, %4$d:%5$.2d\n
producing the message:
Processed November 7, 1990 PRINTF(3s,L) 6
PRINTF(3s,L) AIX Technical Reference PRINTF(3s,L)
Sunday, July 3, 10:02
whereas for German usage, format could be a pointer to the string:
%1Ss, %3$d. %2$s, %4$d:%5$.2d\n
producing the message:
Sonntag, 3. Juli, 10:02
RELATED INFORMATION
In this book: "conv," "vprintf, vfprintf, vsprintf, NLvprintf, NLvfprintf,
NLvsprintf," "limits.h," "ecvt, fcvt, gcvt," "putc, putchar, fputc, putw,
putwc, putwchar, fputwc," "scanf, fscanf, sscanf, NLscanf, NLfscanf, NLsscanf,
wsscanf," and "stdio."
Examples of using printf in AIX C Language Guide and AIX C Language Reference.
"Introduction to International Character Support" in Managing the AIX Operating
System.
AIX Guide to Multibyte Character Set (MBCS) Support.
Processed November 7, 1990 PRINTF(3s,L) 7