fprintf(), printf(), sprintf() — Format and write data

Standards

Format

#include <stdio.h>

int fprintf(FILE *__restrict__stream, const char *__restrict__format-string, …);
int printf(const char *__restrict__format-string, …);
int sprintf(char *__restrict__buffer, const char *__restrict__format-string, …);

#define _OPEN_SYS_UNLOCKED_EXT 1
#include <stdio.h>

int fprintf_unlocked(FILE *__restrict__stream, 
                     const char *__restrict__format-string, …);
int printf_unlocked(const char *__restrict__format-string, …);

General description

These three related functions are referred to as the fprintf family.

The fprintf() function formats and writes output to a stream. It converts each entry in the argument list, if any, and writes to the stream according to the corresponding format specification in the format-string. The fprintf() function cannot be used with a file that is opened using type=record or type=blocked.

The printf() function formats and writes output to the standard output stream stdout. printf() cannot be used if stdout has been reopened using type=record or type=blocked.

The sprintf() function formats and stores a series of characters and values in the array pointed to by buffer. Any argument-list is converted and put out according to the corresponding format specification in the format-string. If the strings pointed to by buffer and format overlap, behavior is undefined.

fprintf() and printf() have the same restriction as any write operation for a read immediately following a write or a write immediately following a read. Between a write and a subsequent read, there must be an intervening flush or reposition. Between a read and a subsequent write, there must also be an intervening flush or reposition unless an EOF has been reached.

The format-string consists of ordinary characters, escape sequences, and conversion specifications. The ordinary characters are copied in order of their appearance. Conversion specifications, beginning with a percent sign (%) or the sequence (%n$) where n is a decimal integer in the range [1,NL_ARGMAX], determine the output format for any argument-list following the format-string. The format-string can contain multibyte characters beginning and ending in the initial shift state. When the format-string includes the use of the optional prefix ll to indicate the size expected is a long long datatype then the corresponding value in the argument list should be a long long datatype if correct output is expected.

fprintf_unlocked() is functionally equivalent to fprintf() with the exception that it is not thread-safe. This function can safely be used in a multithreaded application if and only if it is called while the invoking thread owns the (FILE*) object, as is the case after a successful call to either the flockfile() or ftrylockfile() function.

printf_unlocked() is functionally equivalent to printf() with the exception that it is not thread-safe. This function can safely be used in a multithreaded application if and only if it is called while the invoking thread owns the (FILE*) object, as is the case after a successful call to either the flockfile() or ftrylockfile() function.

The format-string is read from left to right. When the first format specification is found, the value of the first argument after the format-string is converted and output according to the format specification. The second format specification causes the second argument after the format-string to be converted and output, and so on through the end of the format-string. If there are more arguments than there are format specifications, the extra arguments are evaluated and ignored. The results are undefined if there are not enough arguments for all the format specifications. The format specification is illustrated below.

Format Specification for fprintf(), printf(), and sprintf()

>>-%--+-------+--+-------+--+--------------+--+----+------------>
      '-flags-'  '-width-'  '-.--precision-'  +-h--+   
                                              +-hh-+   
                                              +-l--+   
                                              +-ll-+   
                                              +-j--+   
                                              +-t--+   
                                              +-z--+   
                                              +-D--+   
                                              +-DD-+   
                                              +-H--+   
                                              '-L--'   

>--conversion specifier----------------------------------------><

Each field of the format specification is a single character or number signifying a particular format option. The type character, which appears after the last optional format field, determines whether the associated argument is interpreted as a character, a string, a number, or pointer. The simplest format specification contains only the percent sign and a type character (for example, %s).

Percent sign: If a percent sign (%) is followed by a character that has no meaning as a format field, the character is simply copied to stdout. For example, to print a percent sign character, use %%.

The code point for the # character varies between the EBCDIC encoded character sets. The definition of the # character is based on the current LC_SYNTAX category. The default C locale expects the # character to use the code point for encoded character set IBM-1047.

When the LC_SYNTAX category is set using setlocale(), the format strings passed to the printf() functions must use the same encoded character set as is specified for the LC_SYNTAX category.

The # flag should not be used with c, lc, C, d, i, u, s, or p conversion specifier.

Output width: The width argument is a nonnegative decimal integer controlling the minimum number of characters printed. If the number of characters in the output value is less than the specified width, blanks are added on the left or the right (depending on whether the — flag is specified) until the minimum width is reached.

The width never causes a value to be truncated; if the number of characters in the output value is greater than the specified width, or width is not given, all characters of the value are output (subject to the precision specification).

The width specification can be an asterisk (*); if it is, an argument from the argument list supplies the value. The width argument must precede the value being formatted in the argument list. This is an optional field.

If format-string contains the %n$ form of conversion specification, width can be indicated by the sequence *m$, where m is a decimal integer in the range [1,NL_ARGMAX] giving the position of an integer argument in the argument list containing the field width.

Output precision: The precision argument is a nonnegative decimal integer preceded by a period. It specifies the number of characters to be output, or the number of decimal places. Unlike the width specification, the precision can cause truncation of the output value or rounding of a floating-point value.

Be aware that the rounding of floating-point values may not always occur as expected based on the decimal value of the number. This is because the internal binary representation cannot always be an exact representation of the decimal value, so the rounding may occur on an inexact value. This is true of both OS/390® hexadecimal and IEEE 754 binary floating- point formats.

The precision argument can be an asterisk (*); if it is, an argument from the argument list supplies the value. The precision argument must precede the value being formatted in the argument list. The precision field is optional.

If format-string contains the %n$ form of conversion specification, precision can be indicated by the sequence *m$, where m is a decimal integer in the range [1,NL_ARGMAX] giving the position of an integer argument in the argument list containing the field precision.

Conversion specifier: Table 3 explains the meaning of the type characters used in the precision argument.

Floating-point and the fprintf family of formatted output functions: The fprintf family functions match a, A, e, E, f, F, g, or G conversion specifiers to floating-point arguments for which they produce floating-point number substrings in the output stream. The fprintf family functions have been extended to determine the floating-point format, hexadecimal floating-point or IEEE Binary Floating-Point, of types a, A, e, E, f, F, g, or G by using __isBFP().

The fprintf family functions convert IEEE Binary Floating-Point infinity and NaN argument values to special infinity and NaN floating-point number output sequences.

• The special output sequence for infinity values is a plus or minus sign, then the character sequence INF followed by a white space character (space, tab, or newline), a NULL character (\0) or EOF.
• The special output sequence for NaN values is a plus or minus sign, then the character sequence NANS for a signalling NaN or NANQ for a quiet NaN, then a NaN ordinal sequence, and then a a white space character (space, tab, or newline), a NULL character (\0) or EOF.

  For binary floating point NANs: A NaN ordinal sequence is a left-parenthesis character, “(”, followed by a digit sequence representing an integer n, where 1 <= n <= INT_MAX-1, followed by a right-parenthesis character, “)”. The integer value, n, is determined by the fraction bits of the NaN argument value as follows:

  1. For a signalling NaN value, NaN fraction bits are reversed (left to right) to produce bits (right to left) of an even integer value, 2*n. Then formatted output functions produce a (signalling) NaN ordinal sequence corresponding to the integer value n.
  2. For a quiet NaN value, NaN fraction bits are reversed (left to right) to produce bits (right to left) of an odd integer value, 2*n-1. Then formatted output functions produce a (quiet) NaN ordinal sequence corresponding to the integer value n.

  For decimal floating point NANs: A NaN ordinal sequence is a left parenthesis character, "(", followed by a decimal digit sequence of up to 6 digits for a _Decimal32 output number, up to 15 digits for a _Decimal64 output value, or up to 33 digits for a _Decimal128 output value, followed by a right parenthesis, ")". If the NaN ordinal sequence is omitted, NaN ordinal sequence "(0)" is assumed. If the NaN ordinal sequence is shorter than 6, 15, or 33 digits, it will be padded on the left with "0" digits so that the length becomes 6, 15, or, 33 digits for _Decimal32, _Decimal64, and _Decimal128 values respectively.

  For decimal floating point numbers, the digits are not reversed, and both odd or even NaN ordinal sequences can be specified for either a Quiet NAN or Signalling NAN.

The C99 standard does not distinguish between the quiet NaN and signaling NaN values. An argument representing a NaN (Not a Number) is to be displayed as [-]nan or [-]nan(n-char-sequence); where the implementation decides the representation. For the A, E, F, and G conversion specifiers, NaN values are displayed as the uppercase versions of the aforementioned character string representations. To get this behavior set the environment variable _EDC_C99_NAN to YES.

Some compatibility with NaN sequences output by AIX formatted output functions can be achieved by setting a new environment variable, _AIX_NAN_COMPATIBILITY, which z/OS formatted output functions recognize, to one of the following (string) values:

Value

Output function

1

Formatted output functions which produce special NaN output sequences omit the NaN ordinal output sequence (1). This results in output NaN sequences of plus or minus sign followed by NANS or NANQ instead of plus or minus sign followed by NANS(1) or NANQ(1). All other NaN ordinal sequences are explicitly output.

ALL

Formatted output functions which produce special NaN output sequences omit the NaN ordinal output sequence for all NaN values. This results in output NaN sequences of plus or minus sign followed by NANS or NANQ instead of plus or minus sign followed by NANS(n) or NANQ(n) for all NaN values.

The sprintf() function is available to C applications in a stand-alone System Programming C (SPC) Environment.

Usage notes

1. FLOAT(HEX) normalizes differently than FLOAT(IEEE). FLOAT(HEX) produces output in 0x0.hhhhhp+/-dd format, not in the 0x1.hhhhhhp+/-dd format.
2. To use IEEE decimal floating-point, the hardware must have the Decimal Floating-Point Facility installed.

Returned value

If successful, fprintf(), printf(), and sprintf() return the number of characters output. The ending NULL character is not counted.

If unsuccessful, they return a negative value.

Example

⁄* CELEBF30                                      

   This example prints data using &printf. in a variety of                      
   formats.                                                                     
                                                                                
 *⁄                                                                             
#include <stdio.h>                                                              
                                                                                
int main(void)                                                                  
{                                                                               
   char ch = 'h', *string = "computer";                                         
   int count = 234, hex = 0x10, oct = 010, dec = 10;                            
   double fp = 251.7366;                                                        
   unsigned int a = 12;                                                         
   float b = 123.45;                                                            
   int c;                                                                       
   void *d = "a";                                                               
                                                                                
   printf("the unsigned int is %u\n\n",a);                                      
                                                                                
   printf("the float number is %g, and %G\n\n",b,b);                            
                                                                                
   printf("RAY%n\n\n",&c);                                                      
                                                                                
   printf("last line prints %d characters\n\n",c);                              
                                                                                
   printf("Address of d is %p\n\n",d);                                          
                                                                                
   printf("%d   %+d    %06d     %X    %x     %o\n\n",                           
      count, count, count, count, count, count);                                
                                                                                
   printf("1234567890123%n4567890123456789\n\n", &count);                       
                                                                                
   printf("Value of count should be 13; count = %d\n\n", count);                
                                                                                
   printf("%10c%5c\n\n", ch, ch);                                               
                                                                                
   printf("%25s\n%25.4s\n\n", string, string);                                  
                                                                                
   printf("%f    %.2f    %e    %E\n\n", fp, fp, fp, fp);                        
                                                                                
   printf("%i    %i     %i\n\n", hex, oct, dec);                                
}                                                                               

the unsigned int is 12

the float number is 123.45 and 123.45

RAY

last line prints 3 characters

Address of d is DD72F9

234   +234    000234     EA    ea     352

12345678901234567890123456789

Value of count should be 13; count = 13

         h    h

                 computer
                     comp

251.736600    251.74    2.517366e+02    2.517366E+02

16    8     10

/* CELEBF31
   The following example illustrates the use of printf() to print
   fixed-point decimal data types.
   This example works under C only, not C++.
 */
#include <stdio.h>
#include <decimal.h>

decimal(10,2) pd01 = -12.34d;
decimal(12,4) pd02 = 12345678.9876d;
decimal(31,10) pd03 = 123456789013579246801.9876543210d;

int main(void) {
  printf("pd01 %%D(10,2)      = %D(10,2)\n", pd01);
  printf("pd02 %%D( 12 , 4 )  = %D( 12 , 4 )\n", pd02);

  printf("pd01 %%010.2D(10,2) = %010.2D(10,2)\n", pd01);
  printf("pd02 %%20.2D(12,4)  = %20.2D(12,4)\n", pd02);
  printf("\n Give strange result if the specified size is wrong!\n");
  printf("pd03 %%D(15,3)      = %D(15,3)\n\n", pd03);
}

pd01 %D(10,2)      = -12.34
pd02 %D( 12 , 4 )  = 12345678.9876
pd01 %010.2D(10,2) = -000012.34
pd02 %20.2D(12,4)  =          12345678.98

Give strange result if the specified size is wrong!
pd03 %D(15,3)      = -123456789013.579

/* CELEBF32
   This example illustrates the use of sprintf() to format and print
   various data.
 */
#include <stdio.h>

char buffer[200];
int i, j;
double fp;
char *s = "baltimore";
char c;

int main(void)
{
   c = 'l';
   i = 35;
   fp = 1.7320508;

   /* Format and print various data */
   j = sprintf(buffer, "%s\n", s);
   j += sprintf(buffer+j, "%c\n", c);
   j += sprintf(buffer+j, "%d\n", i);
   j += sprintf(buffer+j, "%f\n", fp);
   printf("string:\n%s\ncharacter count = %d\n", buffer, j);
}

string:
Baltimore
l
35
1.732051

character count = 24

Related information

• See the topic about internationalization of locales and characters sets in z/OS XL C/C++ Programming Guide
• See the topic about system programming C (SPC) facilities in z/OS XL C/C++ Programming Guide
• locale.h
• stdio.h
• wchar.h
• fscanf(), scanf(), sscanf() — Read and format data
• __isBFP() — Determine application floating-point format
• localeconv() — Query numeric conventions
• setlocale() — Set locale
• wcrtomb() — Convert a wide character to a multibyte character