OSF

NAME

printf, fprintf, sprintf − Prints formatted output

LIBRARY

Standard I/O Package (libc.a)

SYNOPSIS

#include <stdio.h> int printf (
const char ∗format [ , value, ... ]);
int fprintf (
FILE ∗stream,
const char ∗format [ , value, ... ] );
int sprintf (
char ∗string,
const char ∗format [ , value, ... ] );

PARAMETERS

formatSpecifies a character string combining literal characters with conversion specifications. 

valueSpecifies the data to be converted according to the format parameter. 

streamPoints to a FILE structure specifying an open stream to which converted values will be written. 

stringPoints to a character array in which the converted values will be stored. 

DESCRIPTION

The printf() function converts, formats, and writes its value parameters, under control of the format parameter, to the standard output stream stdout. 

The fprintf() function converts, formats, and writes its value parameters, under control of the format parameter, to the output stream specified by its stream parameter. 

The sprintf() function converts, formats, and stores its value parameters, under control of the format parameter, into consecutive bytes starting at the address specified by the string parameter. The sprintf() function places a ’\0’ (null character) at the end.  You must ensure that enough storage space is available to contain the formatted string. 

The format parameter is a character string that contains two types of objects:

       •Literal characters, which are copied to the output stream. 

       •Conversion specifications, each of which causes zero or more items to be fetched from the value parameter list. 

If there are not enough items for format in the value parameter list, the results are unpredictable. If more values remain after the entire format has been processed, they are ignored. 

Conversion Specifications

Each conversion specification in the format parameter has the following syntax:

       •A % (percent) sign. 

       •Zero or more options, which modify the meaning of the conversion specification. The option characters and their meanings are:

-Left align within the field the result of the conversion. 

+Begin the result of a signed conversion with a sign (+ or -). 

(space)Prefix a space character to the result if the first character of a signed conversion is not a sign. If both the (space) and + options appear, the (space) option is ignored. 

#Convert the value to an alternate form. For c, d, i, 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 (zero). 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 no digits follow it. For g and G conversions, trailing zeros are not removed from the result. 

BGive field width and precision in bytes, rather than in code points, for conversions using the s or S conversion characters. 

NConvert each international character support code point in the converted string into a printable ASCII escape sequence that uniquely identifies the code point. This option affects the s and S conversion characters. 

0Pad to field width using leading zeros (following any indication of sign or base) for d, i, o, u, x, X, e, E, f, g, and G conversions; no space padding is performed. If the 0 and - (dash) flags both appear, the 0 flag will be ignored.  For d, i, o u, x, and X conversions, if a precision is specified, the 0 flag is also ignored.  For other conversions, the behavior is undefined. 

JFor Japanese language support.  This option can be used with all conversion characters that take an int, long, double, or float value as an argument. The J flag, appearing with any of these numeric conversions, indicates that output such as characters, digits, signs, or padding blanks will be 2-byte codes and two columns wide.  The J flag can also be used with the %c, %s, and %S conversion characters to indicate that padding should use double-width spaces. 

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

       •An optional precision. The precision is a .  (dot) followed by a decimal digit string. If no precision is given, it is treated as 0 (zero). The precision specifies:

       —
The minimum number of digits to appear for the d, u, o, x, or X conversions. 

       —
The number of digits to appear after the decimal point for the e, E, and f conversions. 

       —
The maximum number of significant digits for the g  and G conversions. 

       —
The maximum number of characters to be printed from a string in the s conversion. 

       •An optional h, l, or L specifying that a following d, i, u, o, x, or X conversion character applies to, respectively, a long integer value, a short integer value, or a double integer value.  The h and l options can also be used with the n conversion specifier to indicate a pointer to a short int or long int argument, respectively. 

       •A character that indicates the type of conversion to be applied:

%Performs no conversion. Prints %. 

d, iAccepts an integer value 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 zero value with a precision of zero 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. 

uAccepts 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 zero value with a precision of zero 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. 

oAccepts an integer value and converts it to unsigned 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 zero value with a precision of zero 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, XAccepts an integer value and converts it to unsigned 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 zero value with a precision of zero 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. 

fAccepts a float or double value 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, six digits are output.  If the precision is zero, no decimal point appears.  If a decimal point is output, at least one digit is output before it.  The value is rounded to the appropriate number of digits. 

e, EAccepts a float or double value 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, six digits are output.  If the precision is zero, 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.  If the value is zero, the exponent is zero. 

g, GAccepts a float or double value 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.  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 or equal to the precision. 

cAccepts and prints an integer value converted to an unsigned char. 

sAccepts a value as a string (character pointer), and characters from the string are printed until a ’ ’ (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 value has a value of 0 (zero) or null, the results are undefined. 

pAccepts a pointer to void. The value of the pointer is converted to a sequence of printable characters, the same as unsigned hexadecimal (x). 

nAccepts a pointer to an integer into which is written the number of characters written to the output stream so far by this call. No argument is converted. 

A field width or precision can be indicated by an ∗ (asterisk) instead of a digit string. In this case, an integer value parameter supplies the field width or precision. The value parameter 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, the field is expanded to contain the converted result. No truncation occurs.  However, a small precision can cause truncation on the right. 

The e, E, f, and g formats represent the special floating-point values as follows:

Quiet NaN+NaNQ or -NaNQ

Signaling NaN
+NaNS or -NaNS

+/-INF+INF or -INF

+/-0+0 or -0

The representation of the plus sign depends on whether the + or (space) formatting option is specified. 

The printf() functions can handle a format string that enables the system to process elements of the argument list in variable order. In such a case, the normal conversion character % (percent sign) is replaced by "%digit"$", where digit is a decimal number in the range [1, NL_ARGMAX]. Conversion is then applied to the argument, rather than to the next unused argument.  This feature provides for the definition of format strings in an order appropriate to specific languages.  When variable ordering is used, the ∗ (asterisk) specification for field width in precision is replaced by "%digit"$".  If the variable ordering feature is used, it must be specified for all conversions. 

The ∗ (asterisk) specification for field width or precision is not permitted with the variable order %digit$ format. 

All forms of the printf() functions allow for the insertion of a language-dependent radix character in the output string.  The radix character is defined by langinfo data in the program’s locale (category LC_NUMERIC).  In the “C” locale, or in a locale where the radix character is not defined, the radix character defaults to . (decimal point). 

The st_ctime and st_mtime fields of the file are marked for update between the successful execution of the printf() or fprintf() functions and the next successful completion of a call to the fflush() or fclose() functions on the same stream, or a call to the exit() or abort() functions. 

AES Support Level:
Full use

RETURN VALUES

Upon successful completion, each of these functions returns the number of display characters in the output string rather than the number of bytes in the string.  Otherwise, a negative value is returned. 

The value returned by the sprintf() function does not include the final ’\0’ character. 

ERRORS

The printf() or fprintf() functions fail if either the stream is unbuffered, or the stream’s buffer needed to be flushed and the function call caused an underlying write() or lseek() function to be invoked.  In addition, if the printf() or fprintf() function fails, errno may be set to one of the following values:

[EAGAIN]The O_NONBLOCK flag is set for the file descriptor underlying stream and the process would be delayed in the write operation. 

[EBADF]The file descriptor underlying stream is not a valid file descriptor open for writing. 

[EFBIG]An attempt was made to write to a file that exceeds the process’ file size limit or the maximum file size. 

[EINTR]The read operation was interrupted by a signal which was caught, and no data was transferred. 

[EIO]The implementation supports job control, the process is a member of a background process group attempting to write to its controlling terminal, TOSTOP is set, the process is neither ignoring nor blocking SIGTTOU and the process group of the process is orphaned.  This error may also be returned under implementation-defined conditions. 

[ENOSPC]There was no free space remaining on the device containing the file. 

[EPIPE]An attempt was made to write to a pipe or FIFO that is not open for reading by any process.  A SIGPIPE signal will also be sent to the process. 

RELATED INFORMATION

Functions: conv(3), ecvt(3), putc(3), scanf(3), wsprintf(3)