[ Bottom of Page | Previous Page | Next Page | Contents | Index | Library Home | Legal | Search ]

Technical Reference: Base Operating System and Extensions, Volume 1

printf, fprintf, sprintf, snprintf, wsprintf, vprintf, vfprintf, vsprintf, or vwsprintf 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;

#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 vprintf, vfprintf, vsprintf, and vwsprintf subroutines format and write varargs macros parameter lists. These subroutines are the same as the 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:
 

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 (fclose or fflush Subroutine) or fflush subroutine on the same stream or to the exit (exit, atexit, _exit, or _Exit Subroutine) or abort (abort Subroutine) 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:

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-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:

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:

EAGAIN The O_NONBLOCK flag is set for the file descriptor underlying the file specified by the Stream or String parameter and the process would be delayed in the write operation.
EBADF The file descriptor underlying the file specified by the Stream or String parameter is not a valid file descriptor open for writing.
EFBIG An attempt was made to write to a file that exceeds the file size limit of this process or the maximum file size. For more information, refer to the ulimit subroutine.
EINTR The write operation terminated due to receipt of a signal, and either no data was transferred or a partial transfer was not reported.
Note
Depending upon which library routine the application binds to, this subroutine may return EINTR. Refer to the signal subroutine regarding sa_restart.
EIO The process is a member of a background process group attempting to perform a write to its controlling terminal, the TOSTOP flag is set, the process is neither ignoring nor blocking the SIGTTOU signal, and the process group of the process has no parent process.
ENOSPC No free space remains on the device that contains the file.
EPIPE An attempt was made to write to a pipe or first-in-first-out (FIFO) that is not open for reading by any process. A SIGPIPE signal is sent to the process.

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

EILSEQ An invalid character sequence was detected.
EINVAL The Format parameter received insufficient arguments.
ENOMEM Insufficient storage space is available.
ENXIO A request was made of a nonexistent device, or the request was outside the capabilities of the device.

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();  }

Related Information

The abort (abort Subroutine) subroutine, conv (conv Subroutines) subroutine, ecvt, fcvt, or gcvt (ecvt, fcvt, or gcvt Subroutine) subroutine, exit (exit, atexit, _exit, or _Exit Subroutine) subroutine, fclose or fflush (fclose or fflush Subroutine) subroutine, putc, putchar, fputc, or putw (putc, putchar, fputc, or putw Subroutine) subroutine, putwc, putwchar, or fputwc (putwc, putwchar, or fputwc Subroutine) subroutine, scanf, fscanf, sscanf, or wsscanf subroutine, setlocale subroutine.

Input and Output Handling and 128-Bit Long Double Floating-Point Data Type in AIX 5L Version 5.2 General Programming Concepts: Writing and Debugging Programs.

[ Top of Page | Previous Page | Next Page | Contents | Index | Library Home | Legal | Search ]