printf, fprintf, sprintf, snprintf, wsprintf, vprintf, vfprintf, vsprintf, vwsprintf, or vdprintf Subroutine

Purpose

Prints formatted output.

Library

Standard C Library (libc.a) or the Standard C Library with 128-Bit long doubles (libc128.a)

Syntax

#include <stdio.h>

int printf (Format, [Value, ...])
const char *Format;

int fprintf (Stream, Format, [Value, ...])
FILE *Stream;
const char *Format;

int sprintf (String, Format, [Value, ...])
char *String;
const char *Format;

int snprintf (String, Number, Format, [Value, . . .])
char *String;
int Number;
const char *Format;

#include <stdarg.h>

int vprintf (Format, Value)
const char *Format;
va_list Value;

int vfprintf (Stream, Format, Value)
FILE *Stream;
const char *Format;
va_list Value;

int vsprintf (String, Format, Value)
char *String;
const char *Format;
va_list Value;

int vdprintf (fildes, Format, Value);
int fildes;
const char *Format;
va_list Value;

#include <wchar.h>

int vwsprintf (String, Format, Value)
wchar_t *String;
const char *Format;
va_list Value;

int wsprintf (String, Format, [Value, ...])
wchar_t *String;
const char *Format;

Description

The printf subroutine converts, formats, and writes the Value parameter values, under control of the Format parameter, to the standard output stream. The printf subroutine provides conversion types to handle code points and wchar_t wide character codes.

The fprintf subroutine converts, formats, and writes the Value parameter values, under control of the Format parameter, to the output stream specified by the Stream parameter. This subroutine provides conversion types to handle code points and wchar_t wide character codes.

The sprintf subroutine converts, formats, and stores the Value parameter values, under control of the Format parameter, into consecutive bytes, starting at the address specified by the String parameter. The sprintf subroutine places a null character (\0) at the end. You must ensure that enough storage space is available to contain the formatted string. This subroutine provides conversion types to handle code points and wchar_t wide character codes.

The snprintf subroutine converts, formats, and stores the Value parameter values, under control of the Format parameter, into consecutive bytes, starting at the address specified by the String parameter. The snprintf subroutine places a null character (\0) at the end. You must ensure that enough storage space is available to contain the formatted string. This subroutine provides conversion types to handle code points and wchar_t wide character codes. The snprintf subroutine is identical to the sprintf subroutine with the addition of the Number parameter, which states the size of the buffer referred to by the String parameter.

The wsprintf subroutine converts, formats, and stores the Value parameter values, under control of the Format parameter, into consecutive wchar_t characters starting at the address specified by the String parameter. The wsprintf subroutine places a null character (\0) at the end. The calling process should ensure that enough storage space is available to contain the formatted string. The field width unit is specified as the number of wchar_t characters. The wsprintf subroutine is the same as the printf subroutine, except that the String parameter for the wsprintf subroutine uses a string of wchar_t wide-character codes.

All of the above subroutines work by calling the _doprnt subroutine, using variable-length argument facilities of the varargs macros.

The vdprintf, vprintf, vfprintf, vsprintf, and vwsprintf subroutines format and write varargs macros parameter lists. These subroutines are the same as the drpintf, printf, fprintf, sprintf, snprintf, and wsprintf subroutines, respectively, except that they are not called with a variable number of parameters. Instead, they are called with a parameter-list pointer as defined by the varargs macros.

Parameters

Number

Specifies the number of bytes in a string to be copied or transformed.

Value

Specifies 0 or more arguments that map directly to the objects in the Format parameter.

Stream

Specifies the output stream.

String

Specifies the starting address.

Format

A character string that contains two types of objects:

• Plain characters, which are copied to the output stream.
• Conversion specifications, each of which causes 0 or more items to be retrieved from the Value parameter list. In the case of the vprintf, vfprintf, vsprintf, and vwsprintf subroutines, each conversion specification causes 0 or more items to be retrieved from the varargs macros parameter lists.

  If the Value parameter list does not contain enough items for the Format parameter, the results are unpredictable. If more parameters remain after the entire Format parameter has been processed, the subroutine ignores them.

  Each conversion specification in the Format parameter has the following elements:

• A % (percent sign).
• 0 or more options, which modify the meaning of the conversion specification. The option characters and their meanings are:

  '

  Formats the integer portions resulting from i, d, u, f, g and G decimal conversions with thousands_sep grouping characters. For other conversions the behavior is undefined. This option uses the nonmonetary grouping character.

  -

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

  +

  Begins the result of a signed conversion with a + (plus sign) or - (minus sign).

  space character

  Prefixes a space character to the result if the first character of a signed conversion is not a sign. If both the space-character and + option characters appear, the space-character option is ignored.

  #

  Converts the value 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 a 0x or 0X prefix. 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 0's are not removed from the result.

  0

  Pads to the field width with leading 0's (following any indication of sign or base) for d, i, o, u, x, X, e, E, f, g, and G conversions; the field is not space-padded. If the 0 and - options both appear, the 0 option is ignored. For d, i, o u, x, and X conversions, if a precision is specified, the 0 option is also ignored. If the 0 and ' options both appear, grouping characters are inserted before the field is padded. For other conversions, the results are unreliable.

  B

  Specifies a no-op character.

  N

  Specifies a no-op character.

  J

  Specifies a no-op character.

• 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-justify) 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 specified, the default value is 0. The precision specifies the following limits:
  • Minimum number of digits to appear for the d, i, o, u, x, or X conversions.
  • Number of digits to appear after the decimal point for the e, E, and f conversions.
  • Maximum number of significant digits for g and G conversions.
  • Maximum number of bytes to be printed from a string in s and S conversions.
  • Maximum number of bytes, converted from the wchar_t array, to be printed from the S conversions. Only complete characters are printed.
• An optional l (lowercase L), ll (lowercase LL), h, or L specifier indicates one of the following:
  • An optional h specifying that a subsequent d, i, u, o, x, or X conversion specifier applies to a short int or unsigned short int Value parameter (the parameter will have been promoted according to the integral promotions, and its value will be converted to a short int or unsigned short int before printing).
  • An optional h specifying that a subsequent n conversion specifier applies to a pointer to a short int parameter.
  • An optional l (lowercase L) specifying that a subsequent d, i, u, o, x, or X conversion specifier applies to a long int or unsigned long int parameter .
  • An optional l (lowercase L) specifying that a subsequent n conversion specifier applies to a pointer to a long int parameter.
  • An optional ll (lowercase LL) specifying that a subsequent d, i, u, o, x, or X conversion specifier applies to a long long int or unsigned long long int parameter.
  • An optional ll (lowercase LL) specifying that a subsequent n conversion specifier applies to a pointer to a long long int parameter.
  • An optional L specifying that a following e, E, f, g, or G conversion specifier applies to a long double parameter. If linked with libc.a, long double is the same as double (64bits). If linked with libc128.a and libc.a, long double is 128 bits.
• An optional H, D, or DD specifier indicates one of the following conversions:
  • An optional H specifying that a following e, E, f, F, g, or G conversion specifier applies to a _Decimal32 parameter.
  • An optional D specifying that a following e, E, f, F, g, or G conversion specifier applies to a _Decimal64 parameter.
  • An optional DD specifying that a following e, E, f, F, g, or G conversion specifier applies to a _Decimal128 parameter.
• An optional vl, lv, vh, hv or v specifier indicates one of the following vector data type conversions:
  • An optional v specifying that a following e, E, f, g, G, a, or A conversion specifier applies to a vector float parameter. It consumes one argument and interprets the data as a series of four 4-byte floating point components.
  • An optional v specifying that a following c, d, i, u, o, x, or X conversion specifier applies to a vector signed char, vector unsigned char, or vector bool char parameter. It consumes one argument and interprets the data as a series of sixteen 1-byte components.
  • An optional vl or lv specifying that a following d, i, u, o, x, or X conversion specifier applies to a vector signed int, vector unsigned int, or vector bool parameter. It consumes one argument and interprets the data as a series of four 4-byte integer components.
  • An optional vh or hv specifying that a following d, i, u, o, x, or X conversion specifier applies to a vector signed short or vector unsigned short parameter. It consumes one argument and interprets the data as a series of eight 2-byte integer components.
  • For any of the preceding specifiers, an optional separator character can be specified immediately preceding the vector size specifier. If no separator is specified, the default separator is a space unless the conversion is c, in which case the default separator is null. The set of supported optional separators are , (comma), ; (semicolon), : (colon), and _ (underscore).
• The following characters indicate the type of conversion to be applied:

  %

  Performs no conversion. Prints (%).

  d or i

  Accepts a Value parameter specifying an integer 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 0's. The default precision is 1. The result of converting a value of 0 with a precision of 0 is a null string. Specifying a field width with a 0 as a leading character causes the field-width value to be padded with leading 0's.

  u

  Accepts a Value parameter specifying an unsigned integer 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 0's. The default precision is 1. The result of converting a value of 0 with a precision of 0 is a null string. Specifying a field width with a 0 as a leading character causes the field-width value to be padded with leading 0's.

  o

  Accepts a Value parameter specifying an unsigned integer 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 0's. The default precision is 1. The result of converting a value of 0 with a precision of 0 is a null string. Specifying a field-width with a 0 as a leading character causes the field width value to be padded with leading 0's. An octal value for field width is not implied.

  x or X

  Accepts a Value parameter specifying an unsigned integer 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 0's. The default precision is 1. The result of converting a value of 0 with a precision of 0 is a null string. Specifying a field width with a 0 as a leading character causes the field-width value to be padded with leading 0's.

  f

  Accepts a Value parameter specifying a double 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 0, no decimal point appears.

  e or E

  Accepts a Value parameter specifying a double and converts it to the exponential form [-]d.ddde+/-dd. One digit exists before the decimal point, and the number of digits after the decimal point is equal to the precision specification. The precision specification can be in the range of 0-17 digits. If no precision is specified, six digits are output. If the precision is 0, 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 or G

  Accepts a Value parameter specifying a double and converts it in the style of the e, E, or f conversion characters, with the precision specifying the number of significant digits. Trailing 0's 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. If an explicit precision is 0, it is taken as 1.

  c

  Accepts and prints a Value parameter specifying an integer converted to an unsigned char data type.

  C

  Accepts and prints a Value parameter specifying a wchar_t wide character code. The wchar_t wide character code specified by the Value parameter is converted to an array of bytes representing a character and that character is written; the Value parameter is written without conversion when using the wsprintf subroutine.

  s

  Accepts a Value parameter as a string (character pointer), and characters from the string are printed until a null character (\0) is encountered or the number of bytes indicated by the precision is reached. If no precision is specified, all bytes up to the first null character are printed. If the string pointer specified by the Value parameter has a null value, the results are unreliable.

  S

  Accepts a corresponding Value parameter as a pointer to a wchar_t string. Characters from the string are printed (without conversion) until a null character (\0) is encountered or the number of wide 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 specified by the Value parameter has a value of null, the results are unreliable.

  p

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

  n

  Accepts a pointer to an integer into which is written the number of characters (wide-character codes in the case of the wsprintf subroutine) written to the output stream 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 retrieved 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 and no truncation occurs. However, a small field width or precision can cause truncation on the right.

The printf, fprintf, sprintf, snprintf, wsprintf, vprintf, vfprintf, vsprintf, or vwsprintf subroutine allows the insertion of a language-dependent radix character in the output string. The radix character is defined by language-specific data in the LC_NUMERIC category of the program's locale. In the C locale, or in a locale where the radix character is not defined, the radix character defaults to a . (dot).

After any of these subroutines runs successfully, and before the next successful completion of a call to the fclose or fflush subroutine on the same stream or to the exit or abort subroutine, the st_ctime and st_mtime fields of the file are marked for update.

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

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

These subroutines can handle a format string that enables the system to process elements of the parameter 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 from 1 to the NL_ARGMAX value. Conversion is then applied to the specified 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 you use the variable-ordering feature, you must specify it for all conversions.

The following criteria apply:

• The format passed to the NLS extensions can contain either the format of the conversion or the explicit or implicit argument number. However, these forms cannot be mixed within a single format string, except for %% (double percent sign).
• The n value must have no leading zeros.
• If %n$ is used, %1$ to %n - 1$ inclusive must be used.
• The n in %n$ is in the range from 1 to the NL_ARGMAX value, inclusive. See the limits.h file for more information about the NL_ARGMAX value.
• Numbered arguments in the argument list can be referenced as many times as required.
• The * (asterisk) specification for field width or precision is not permitted with the variable order %n$ format; instead, the *m$ format is used.

Return Values

Upon successful completion, the printf, fprintf, vprintf, and vfprintf subroutines return the number of bytes transmitted (not including the null character [\0] in the case of the sprintf, and vsprintf subroutines). If an error was encountered, a negative value is output.

Upon successful completion, the snprintf subroutine returns the number of bytes written to the String parameter (excluding the terminating null byte). If output characters are discarded because the output exceeded the Number parameter in length, then the snprintf subroutine returns the number of bytes that would have been written to the String parameter if the Number parameter had been large enough (excluding the terminating null byte).

Upon successful completion, the wsprintf and vwsprintf subroutines return the number of wide characters transmitted (not including the wide character null character [\0]). If an error was encountered, a negative value is output.

Error Codes

The printf, fprintf, sprintf, snprintf, or wsprintf subroutine is unsuccessful if the file specified by the Stream parameter is unbuffered or the buffer needs to be flushed and one or more of the following are true:

The printf, fprintf, sprintf, snprintf, or wsprintf subroutine may be unsuccessful if one or more of the following are true:

Examples

The following example demonstrates how the vfprintf subroutine can be used to write an error routine:

#include <stdio.h>
#include <stdarg.h>
/* The error routine should be called with the
     syntax:       */
/* error(routine_name, Format
     [, value, . . . ]); */
/*VARARGS0*/
void error(char *fmt, . . .);
/* **  Note that the function name and
     Format arguments cannot be **
     separately declared because of the **
     definition of varargs.  */  {
   va_list args;

   va_start(args, fmt);
   /*
   ** Display the name of the function
      that called the error routine   */
   fprintf(stderr, "ERROR in %s: ",
      va_arg(args, char *));   /*
   ** Display the remainder of the message
   */
   fmt = va_arg(args, char *);
   vfprintf(fmt, args);
   va_end(args);
    abort();  }