Next: Dynamically Allocating Formatted Output, Previous: Other Output Conversions, Up: Formatted Output [Contents][Index]
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.
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.
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.
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.
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.
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.
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.
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.
Next: Dynamically Allocating Formatted Output, Previous: Other Output Conversions, Up: Formatted Output [Contents][Index]