Formatted Output Functions (The GNU C Library)

#### 12.12.7 Formatted Output Functions ¶

This section describes how to call `printf` and related functions. Prototypes for these functions are in the header file `stdio.h`. Because these functions take a variable number of arguments, you must declare prototypes for them before using them. Of course, the easiest way to make sure you have all the right prototypes is to just include `stdio.h`.

The `printf` family shares the error codes listed below. Individual functions may report additional `errno` values if they fail.

`EOVERFLOW`

  The number of written bytes would have exceeded `INT_MAX`, and thus could not be represented in the return type `int`.

`ENOMEM`

  The function could not allocate memory during processing. Long argument lists and certain floating point conversions may require memory allocation, as does initialization of an output stream upon first use.

`EILSEQ`

  POSIX specifies this error code should be used if a wide character is encountered that does not have a matching valid character. The GNU C Library always performs transliteration, using a replacement character if necessary, so this error condition cannot occur on output. However, the GNU C Library uses `EILSEQ` to indicate that an input character sequence (wide or multi-byte) could not be converted successfully.

Function: `int` printf `(const char *template, …)` ¶

  Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap | AC-Unsafe mem lock corrupt | See POSIX Safety Concepts.

  The `printf` function prints the optional arguments under the control of the template string template to the stream `stdout`. It returns the number of characters printed, or a negative value if there was an output error.

Function: `int` wprintf `(const wchar_t *template, …)` ¶

  Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap | AC-Unsafe mem lock corrupt | See POSIX Safety Concepts.

  The `wprintf` function prints the optional arguments under the control of the wide template string template to the stream `stdout`. It returns the number of wide characters printed, or a negative value if there was an output error.

Function: `int` fprintf `(FILE *stream, const char *template, …)` ¶

  Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap | AC-Unsafe mem lock corrupt | See POSIX Safety Concepts.

  This function is just like `printf`, except that the output is written to the stream stream instead of `stdout`.

Function: `int` fwprintf `(FILE *stream, const wchar_t *template, …)` ¶

  Preliminary: | MT-Safe locale | AS-Unsafe corrupt heap | AC-Unsafe mem lock corrupt | See POSIX Safety Concepts.

  This function is just like `wprintf`, except that the output is written to the stream stream instead of `stdout`.

Function: `int` sprintf `(char *s, const char *template, …)` ¶

  Preliminary: | MT-Safe locale | AS-Unsafe heap | AC-Unsafe mem | See POSIX Safety Concepts.

  This is like `printf`, except that the output is stored in the character array s instead of written to a stream. A null character is written to mark the end of the string.

  The `sprintf` function returns the number of characters stored in the array s, not including the terminating null character.

  The behavior of this function is undefined if copying takes place between objects that overlap—for example, if s is also given as an argument to be printed under control of the ‘`%s`’ conversion. See Copying Strings and Arrays.

  Warning: The `sprintf` function can be dangerous because it can potentially output more characters than can fit in the allocation size of the string s. Remember that the field width given in a conversion specification is only a minimum value.

  To avoid this problem, you can use `snprintf` or `asprintf`, described below.

Function: `int` swprintf `(wchar_t *ws, size_t size, const wchar_t *template, …)` ¶

  Preliminary: | MT-Safe locale | AS-Unsafe heap | AC-Unsafe mem | See POSIX Safety Concepts.

  This is like `wprintf`, except that the output is stored in the wide character array ws instead of written to a stream. A null wide character is written to mark the end of the string. The size argument specifies the maximum number of characters to produce. The trailing null character is counted towards this limit, so you should allocate at least size wide characters for the string ws.

  The return value is the number of characters generated for the given input, excluding the trailing null. If not all output fits into the provided buffer a negative value is returned, and `errno` is set to `E2BIG`. (The setting of `errno` is a GNU extension.) You should try again with a bigger output string. Note: this is different from how `snprintf` handles this situation.

  Note that the corresponding narrow stream function takes fewer parameters. `swprintf` in fact corresponds to the `snprintf` function. Since the `sprintf` function can be dangerous and should be avoided the ISO C committee refused to make the same mistake again and decided to not define a function exactly corresponding to `sprintf`.

Function: `int` snprintf `(char *s, size_t size, const char *template, …)` ¶

  Preliminary: | MT-Safe locale | AS-Unsafe heap | AC-Unsafe mem | See POSIX Safety Concepts.

  The `snprintf` function is similar to `sprintf`, except that the size argument specifies the maximum number of characters to produce. The trailing null character is counted towards this limit, so you should allocate at least size characters for the string s. If size is zero, nothing, not even the null byte, shall be written and s may be a null pointer.

  The return value is the number of characters which would be generated for the given input, excluding the trailing null. If this value is greater than or equal to size, not all characters from the result have been stored in s. If this happens, you should be wary of using the truncated result as that could lead to security, encoding, or other bugs in your program (see Truncating Strings while Copying). Instead, you should try again with a bigger output string. Here is an example of doing this:

      /* Construct a message describing the value of a variable
         whose name is name and whose value is value. */
      char *
      make_message (char *name, char *value)
      {
        /* Guess we need no more than 100 bytes of space. */
        size_t size = 100;
        char *buffer = xmalloc (size);

       /* Try to print in the allocated space. */
        int buflen = snprintf (buffer, size, "value of %s is %s",
      		         name, value);
        if (! (0 <= buflen && buflen < SIZE_MAX))
          fatal ("integer overflow");

        if (buflen >= size)
          {
            /* Reallocate buffer now that we know
      	 how much space is needed. */
            size = buflen;
            size++;
            buffer = xrealloc (buffer, size);

            /* Try again. */
            snprintf (buffer, size, "value of %s is %s",
      		name, value);
          }
        /* The last call worked, return the string. */
        return buffer;
      }

  In practice, it is often easier just to use `asprintf`, below.

  Attention: In versions of the GNU C Library prior to 2.1 the return value is the number of characters stored, not including the terminating null; unless there was not enough space in s to store the result in which case `-1` is returned. This was changed in order to comply with the ISO C99 standard.

Function: `int` dprintf `(int fd, template, ...)` ¶

  | MT-Safe locale | AS-Unsafe heap | AC-Unsafe mem | See POSIX Safety Concepts.

  This function formats its arguments according to template and writes the result to the file descriptor fd, using the `write` function. It returns the number of bytes written, or a negative value if there was an error. In the error case, `errno` is set appropriately. The possible `errno` values depend on the type of the file descriptor fd, in addition to the general `printf` error codes.

  The number of calls to `write` is unspecified, and some `write` calls may have happened even if `dprintf` returns with an error.

  Portability Note: POSIX does not require that this function is async-signal-safe, and the GNU C Library implementation is not. However, some other systems offer this function as an async-signal-safe alternative to `fprintf`. See POSIX Safety Concepts.