Go to the previous, next section.
This chapter describes the functions for creating streams and performing input and output operations on them. As discussed in section Input/Output Overview, a stream is a fairly abstract, high-level concept representing a communications channel to a file, device, or process.
For historical reasons, the type of the C data structure that represents
a stream is called FILE rather than "stream". Since most of
the library functions deal with objects of type FILE *, sometimes
the term file pointer is also used to mean "stream". This leads
to unfortunate confusion over terminology in many books on C. This
manual, however, is careful to use the terms "file" and "stream"
only in the technical sense.
The FILE type is declared in the header file `stdio.h'.
This is the data type is used to represent stream objects. A
FILE object holds all of the internal state information about the
connection to the associated file, including such things as the file
position indicator and buffering information. Each stream also has
error and end-of-file status indicators that can be tested with the
ferror and feof functions; see section End-Of-File and Errors.
FILE objects are allocated and managed internally by the
input/output library functions. Don't try to create your own objects of
type FILE; let the library do it. Your programs should
deal only with pointers to these objects (that is, FILE * values)
rather than the objects themselves.
When the main function of your program is invoked, it already has
three predefined streams open and available for use. These represent
the "standard" input and output channels that have been established
for the process.
These streams are declared in the header file `stdio.h'.
The standard input stream, which is the normal source of input for the program.
The standard output stream, which is used for normal output from the program.
The standard error stream, which is used for error messages and diagnostics issued by the program.
In the GNU system, you can specify what files or processes correspond to these streams using the pipe and redirection facilities provided by the shell. (The primitives shells use to implement these facilities are described in section File System Interface.) Most other operating systems provide similar mechanisms, but the details of how to use them can vary.
It is probably not a good idea to close any of the standard streams.
But you can use freopen to get te effect of closing one and
reopening it. See section Opening Streams.
Opening a file with the fopen function creates a new stream and
establishes a connection between the stream and a file. This may
involve creating a new file.
Everything described in this section is declared in the header file `stdio.h'.
Function: FILE * fopen (const char *filename, const char *opentype)
The fopen function opens a stream for I/O to the file
filename, and returns a pointer to the stream.
The opentype argument is a string that controls how the file is opened and specifies attributes of the resulting stream. It must begin with one of the following sequences of characters:
As you can see, `+' requests a stream that can do both input and
output. When using such a stream, you must call fflush
(see section Stream Buffering) or a file positioning function such as
fseek (see section File Positioning) when switching from reading to
writing or vice versa. Otherwise, internal buffers might not be emptied
properly.
The GNU C library defines one additional character for use in
opentype: the character `x' insists on creating a new
file--if a file filename already exists, fopen fails
rather than opening it. This is equivalent to the O_EXCL option
to the open function (see section File Status Flags).
The character `b' in opentype has a standard meaning; it requests a binary stream rather than a text stream. But this makes no difference in POSIX systems (including the GNU system). If both `+' and `b' are specified, they can appear in either order. See section Text and Binary Streams.
Any other characters in opentype are simply ignored. They may be meaningful in other systems.
If the open fails, fopen returns a null pointer.
You can have multiple streams (or file descriptors) pointing to the same file open at the same time. If you do only input, this works straightforwardly, but you must be careful if any output streams are included. See section Precautions for Mixing Streams and Descriptors. This is equally true whether the streams are in one program (not usual) or in several programs (which can easily happen). It may be advantageous to use the file locking facilities to avoid simultaneous access. See section File Locks.
The value of this macro is an integer constant expression that
represents the minimum number of streams that the implementation
guarantees can be open simultaneously. The value of this constant is at
least eight, which includes the three standard streams stdin,
stdout, and stderr.
Function: FILE * freopen (const char *filename, const char *opentype, FILE *stream)
This function is like a combination of fclose and fopen.
It first closes the stream referred to by stream, ignoring any
errors that are detected in the process. (Because errors are ignored,
you should not use freopen on an output stream if you have
actually done any output using the stream.) Then the file named by
filename is opened with mode opentype as for fopen,
and associated with the same stream object stream.
If the operation fails, a null pointer is returned; otherwise,
freopen returns stream.
The main use of freopen is to connect a standard stream such as
stdir with a file of your own choice. This is useful in programs
in which use of a standard stream for certain purposes is hard-coded.
When a stream is closed with fclose, the connection between the
stream and the file is cancelled. After you have closed a stream, you
cannot perform any additional operations on it any more.
Function: int fclose (FILE *stream)
This function causes stream to be closed and the connection to
the corresponding file to be broken. Any buffered output is written
and any buffered input is discarded. The fclose function returns
a value of 0 if the file was closed successfully, and EOF
if an error was detected.
It is important to check for errors when you call fclose to close
an output stream, because real, everyday errors can be detected at this
time. For example, when fclose writes the remaining buffered
output, it might get an error because the disk is full. Even if you you
know the buffer is empty, errors can still occur when closing a file if
you are using NFS.
The function fclose is declared in `stdio.h'.
If the main function to your program returns, or if you call the
exit function (see section Normal Termination), all open streams are
automatically closed properly. If your program terminates in any other
manner, such as by calling the abort function (see section Aborting a Program) or from a fatal signal (see section Signal Handling), open streams
might not be closed properly. Buffered output may not be flushed and
files may not be complete. For more information on buffering of
streams, see section Stream Buffering.
This section describes functions for performing character- and
line-oriented output. Largely for historical compatibility, there are
several variants of these functions, but as a matter of style (and for
simplicity!) we suggest you stick with using fputc and
fputs, and perhaps putc and putchar.
These functions are declared in the header file `stdio.h'.
Function: int fputc (int c, FILE *stream)
The fputc function converts the character c to type
unsigned char, and writes it to the stream stream.
EOF is returned if a write error occurs; otherwise the
character c is returned.
Function: int putc (int c, FILE *stream)
This is just like fputc, except that most systems implement it as
a macro, making it faster. One consequence is that it may evaluate the
stream argument more than once.
The putchar function is equivalent to fputc with
stdout as the value of the stream argument.
Function: int fputs (const char *s, FILE *stream)
The function fputs writes the string s to the stream
stream. The terminating null character is not written.
This function does not add a newline character, either.
It outputs only the chars in the string.
This function returns EOF if a write error occurs, and otherwise
a non-negative value.
For example:
fputs ("Are ", stdout);
fputs ("you ", stdout);
fputs ("hungry?\n", stdout);
outputs the text `Are you hungry?' followed by a newline.
Function: int puts (const char *s)
The puts function writes the string s to the stream
stdout followed by a newline. The terminating null character of
the string is not written.
Function: int putw (int w, FILE *stream)
This function writes the word w (that is, an int) to
stream. It is provided for compatibility with SVID, but we
recommend you use fwrite instead (see section Block Input/Output).
This section describes functions for performing character- and
line-oriented input. Again, there are several variants of these
functions, some of which are considered obsolete stylistically. It's
suggested that you stick with fgetc, getline, and maybe
getc, getchar and fgets.
These functions are declared in the header file `stdio.h'.
Function: int fgetc (FILE *stream)
This function reads the next character as an unsigned char from
the stream stream and returns its value, converted to an
int. If an end-of-file condition or read error occurs,
EOF is returned instead.
Function: int getc (FILE *stream)
This is just like fgetc, except that it is permissible (and typical)
for it to be implemented as a macro that evaluates the stream
argument more than once.
The getchar function is equivalent to fgetc with stdin
as the value of the stream argument.
Here is an example of a function that does input using fgetc. It
would work just as well using getc instead, or using
getchar () instead of fgetc (stdin).
int
y_or_n_p (const char *question)
{
fputs (question, stdout);
while (1) {
int c, answer;
/* Write a space to separate answer from question. */
fputc (' ', stdout);
/* Read the first character of the line.
This should be the answer character, but might not be. */
c = tolower (fgetc (stdin));
answer = c;
/* Discard rest of input line. */
while (c != '\n')
c = fgetc (stdin);
/* Obey the answer if it was valid. */
if (answer == 'y')
return 1;
if (answer == 'n')
return 0;
/* Answer was invalid: ask for valid answer. */
fputs ("Please answer y or n:", stdout);
}
}
Function: int getw (FILE *stream)
This function reads a word (that is, an int) from stream.
It's provided for compatibility with SVID. We recommend you use
fread instead (see section Block Input/Output).
Since many programs interpret input on the basis of lines, it's convenient to have functions to read a line of text from a stream.
Standard C has functions to do this, but they aren't very safe: null
characters and even (for gets) long lines can confuse them. So
the GNU library provides the nonstandard getline function that
makes it easy to read lines reliably.
Another GNU extension, getdelim, generalizes getline. It
reads a delimited record, defined as everything through the next
occurrence of a specified delimeter character.
All these functions are declared in `stdio.h'.
Function: ssize_t getline (char **lineptr, size_t *n, FILE *stream)
This function reads an entire line from stream, storing the text
(including the newline and a terminating null character) in a buffer
and storing the buffer address in *lineptr.
Before calling getline, you should place in *lineptr
the address of a buffer *n bytes long. If this buffer is
long enough to hold the line, getline stores the line in this
buffer. Otherwise, getline makes the buffer bigger using
realloc, storing the new buffer address back in
*lineptr and the increased size back in *n.
In either case, when getline returns, *lineptr is
a char * which points to the text of the line.
When getline is successful, it returns the number of characters
read (including the newline, but not including the terminating null).
This value enables you to distinguish null characters that are part of
the line from the null character inserted as a terminator.
This function is a GNU extension, but it is the recommended way to read lines from a stream. The alternative standard functions are unreliable.
If an error occurs or end of file is reached, getline returns
-1.
Function: ssize_t getdelim (char **lineptr, size_t *n, int delimiter, FILE *stream)
This function is like getline except that the character which
tells it to stop reading is not necessarily newline. The argument
delimeter specifies the delimeter character; getdelim keeps
reading until it sees that character (or end of file).
The text is stored in lineptr, including the delimeter character
and a terminating null. Like getline, getdelim makes
lineptr bigger if it isn't big enough.
Function: char * fgets (char *s, int count, FILE *stream)
The fgets function reads characters from the stream stream
up to and including a newline character and stores them in the string
s, adding a null character to mark the end of the string. You
must supply count characters worth of space in s, but the
number of characters read is at most count - 1. The extra
character space is used to hold the null character at the end of the
string.
If the system is already at end of file when you call fgets, then
the contents of the array s are unchanged and a null pointer is
returned. A null pointer is also returned if a read error occurs.
Otherwise, the return value is the pointer s.
Warning: If the input data has a null character, you can't tell.
So don't use fgets unless you know the data cannot contain a null.
Don't use it to read files edited by the user because, if the user inserts
a null character, you should either handle it properly or print a clear
error message. We recommend using getline instead of fgets.
Deprecated function: char * gets (char *s)
The function gets reads characters from the stream stdin
up to the next newline character, and stores them in the string s.
The newline character is discarded (note that this differs from the
behavior of fgets, which copies the newline character into the
string).
Warning: The gets function is very dangerous
because it provides no protection against overflowing the string s.
The GNU library includes it for compatibility only. You should
always use fgets or getline instead.
In parser programs it is often useful to examine the next character in the input stream without removing it from the stream. This is called "peeking ahead" at the input because your program gets a glimpse of the input it will read next.
Using stream I/O, you can peek ahead at input by first reading it and
then unreading it (also called pushing it back on the stream).
Unreading a character makes it available to be input again from the stream,
by the next call to fgetc or other input function on that stream.
Here is a pictorial explanation of unreading. Suppose you have a stream reading a file that contains just six characters, the letters `foobar'. Suppose you have read three characters so far. The situation looks like this:
f o o b a r
^
so the next input character will be `b'.
If instead of reading `b' you unread the letter `o', you get a situation like this:
f o o b a r
|
o--
^
so that the next input characters will be `o' and `b'.
If you unread `9' instead of `o', you get this situation:
f o o b a r
|
9--
^
so that the next input characters will be `9' and `b'.
ungetc To Do Unreadingungetc, because it
reverses the action of fgetc.
Function: int ungetc (int c, FILE *stream)
The ungetc function pushes back the character c onto the
input stream stream. So the next input from stream will
read c before anything else.
The character that you push back doesn't have to be the same as the last
character that was actually read from the stream. In fact, it isn't
necessary to actually read any characters from the stream before
unreading them with ungetc! But that is a strange way to write
a program; usually ungetc is used only to unread a character
that was just read from the same stream.
The GNU C library only supports one character of pushback--in other
words, it does not work to call ungetc twice without doing input
in between. Other systems might let you push back multiple characters;
then reading from the stream retrieves the characters in the reverse
order that they were pushed.
Pushing back characters doesn't alter the file; only the internal
buffering for the stream is affected. If a file positioning function
(such as fseek or rewind; see section File Positioning) is
called, any pending pushed-back characters are discarded.
Unreading a character on a stream that is at end of file clears the end-of-file indicator for the stream, because it makes the character of input available. Reading that character will set the end-of-file indicator again.
Here is an example showing the use of getc and ungetc to
skip over whitespace characters. When this function reaches a
non-whitespace character, it unreads that character to be seen again on
the next read operation on the stream.
#include <stdio.h>
void
skip_whitespace (FILE *stream)
{
int c;
do
/* No need to check for EOF because it is not
isspace, and ungetc ignores EOF. */
c = getc (stream);
while (isspace (c));
ungetc (c, stream);
}
The functions described in this section (printf and related
functions) provide a convenient way to perform formatted output. You
call printf with a format string or template string
that specifies how to format the values of the remaining arguments.
Unless your program is a filter that specifically performs line- or
character-oriented processing, using printf or one of the other
related functions described in this section is usually the easiest and
most concise way to perform output. These functions are especially
useful for printing error messages, tables of data, and the like.
The printf function can be used to print any number of arguments.
The template string argument you supply in a call provides
information not only about the number of additional arguments, but also
about their types and what style should be used for printing them.
Ordinary characters in the template string are simply written to the output stream as-is, while conversion specifications introduced by a `%' character in the template cause subsequent arguments to be formatted and written to the output stream. For example,
int pct = 37;
char filename[] = "foo.txt";
printf ("Processing of `%s' is %d%% finished.\nPlease be patient.\n",
filename, pct);
produces output like
Processing of `foo.txt' is 37% finished. Please be patient.
This example shows the use of the `%d' conversion to specify that
an int argument should be printed in decimal notation, the
`%s' conversion to specify printing of a string argument, and
the `%%' conversion to print a literal `%' character.
There are also conversions for printing an integer argument as an unsigned value in octal, decimal, or hexadecimal radix (`%o', `%u', or `%x', respectively); or as a character value (`%c').
Floating-point numbers can be printed in normal, fixed-point notation using the `%f' conversion or in exponential notation using the `%e' conversion. The `%g' conversion uses either `%e' or `%f' format, depending on what is more appropriate for the magnitude of the particular number.
You can control formatting more precisely by writing modifiers between the `%' and the character that indicates which conversion to apply. These slightly alter the ordinary behavior of the conversion. For example, most conversion specifications permit you to specify a minimum field width and a flag indicating whether you want the result left- or right-justified within the field.
The specific flags and modifiers that are permitted and their interpretation vary depending on the particular conversion. They're all described in more detail in the following sections. Don't worry if this all seems excessively complicated at first; you can almost always get reasonable free-format output without using any of the modifiers at all. The modifiers are mostly used to make the output look "prettier" in tables.
This section provides details about the precise syntax of conversion
specifications that can appear in a printf template
string.
Characters in the template string that are not part of a conversion specification are printed as-is to the output stream. Multibyte character sequences (see section Extended Characters) are permitted in a template string.
The conversion specifications in a printf template string have
the general form:
% flags width [ . precision ] type conversion
For example, in the conversion specifier `%-10.8ld', the `-'
is a flag, `10' specifies the field width, the precision is
`8', the letter `l' is a type modifier, and `d' specifies
the conversion style. (This particular type specifier says to
print a long int argument in decimal notation, with a minimum of
8 digits left-justified in a field at least 10 characters wide.)
In more detail, output conversion specifications consist of an initial `%' character followed in sequence by:
The GNU library's version of printf also allows you to specify a
field width of `*'. This means that the next argument in the
argument list (before the actual value to be printed) is used as the
field width. The value must be an int. Other C library versions may
not recognize this syntax.
The GNU library's version of printf also allows you to specify a
precision of `*'. This means that the next argument in the
argument list (before the actual value to be printed) is used as the
precision. The value must be an int. If you specify `*'
for both the field width and precision, the field width argument
precedes the precision argument. Other C library versions may not
recognize this syntax.
int,
but you can specify `h', `l', or `L' for other integer
types.)
The exact options that are permitted and how they are interpreted vary between the different conversion specifiers. See the descriptions of the individual conversions for information about the particular options that they use.
Here is a table summarizing what all the different conversions do:
scanf for input
(see section Table of Input Conversions).
size_t. See section Integer Conversions, for details.
errno.
See section Other Output Conversions.
If the syntax of a conversion specification is invalid, unpredictable things will happen, so don't do this. If there aren't enough function arguments provided to supply values for all the conversion specifications in the template string, or if the arguments are not of the correct types, the results are unpredictable. If you supply more arguments than conversion specifications, the extra argument values are simply ignored; this is sometimes useful.
This section describes the options for the `%d', `%i', `%o', `%u', `%x', `%X', and `%Z' conversion specifications. These conversions print integers in various formats.
The `%d' and `%i' conversion specifications both print an
int argument as a signed decimal number; while `%o',
`%u', and `%x' print the argument as an unsigned octal,
decimal, or hexadecimal number (respectively). The `%X' conversion
specification is just like `%x' except that it uses the characters
`ABCDEF' as digits instead of `abcdef'. `%Z' is like
`%u' but expects an argument of type size_t.
The following flags are meaningful:
If a precision is supplied, it specifies the minimum number of digits to appear; leading zeros are produced if necessary. If you don't specify a precision, the number is printed with as many digits as it needs. If you convert a value of zero with an explicit precision of zero, then no characters at all are produced.
Without a type modifier, the corresponding argument is treated as an
int (for the signed conversions `%i' and `%d') or
unsigned int (for the unsigned conversions `%o', `%u',
`%x', and `%X'). Recall that since printf and friends
are variadic, any char and short arguments are
automatically converted to int by the default argument
promotions. For arguments of other integer types, you can use these
modifiers:
short int or unsigned
short int, as appropriate. A short argument is converted to an
int or unsigned int by the default argument promotions
anyway, but the `h' modifier says to convert it back to a
short again.
long int or unsigned long
int, as appropriate.
long long int. (This type is
an extension supported by the GNU C compiler. On systems that don't
support extra-long integers, this is the same as long int.)
The modifiers for argument type are not applicable to `%Z', since
the sole purpose of `%Z' is to specify the data type
size_t.
Here is an example. Using the template string:
|%5d|%-5d|%+5d|%+-5d|% 5d|%05d|%5.0d|%5.2d|%d|\n"
to print numbers using the different options for the `%d' conversion gives results like:
| 0|0 | +0|+0 | 0|00000| | 00|0| | 1|1 | +1|+1 | 1|00001| 1| 01|1| | -1|-1 | -1|-1 | -1|-0001| -1| -01|-1| |100000|100000|+100000| 100000|100000|100000|100000|100000|
In particular, notice what happens in the last case where the number is too large to fit in the minimum field width specified.
Here are some more examples showing how unsigned integers print under various format options, using the template string:
"|%5u|%5o|%5x|%5X|%#5o|%#5x|%#5X|%#10.8x|\n"
| 0| 0| 0| 0| 0| 0x0| 0X0|0x00000000| | 1| 1| 1| 1| 01| 0x1| 0X1|0x00000001| |100000|303240|186a0|186A0|0303240|0x186a0|0X186A0|0x000186a0|
This section discusses the conversion specifications for floating-point numbers: the `%f', `%e', `%E', `%g', and `%G' conversions.
The `%f' conversion prints its argument in fixed-point notation,
producing output of the form
[-]ddd.ddd,
where the number of digits following the decimal point is controlled
by the precision you specify.
The `%e' conversion prints its argument in exponential notation,
producing output of the form
[-]d.ddde[+|-]dd.
Again, the number of digits following the decimal point is controlled by
the precision. The exponent always contains at least two digits. The
`%E' conversion is similar but the exponent is marked with the letter
`E' instead of `e'.
The `%g' and `%G' conversions print the argument in the style of `%e' or `%E' (respectively) if the exponent would be less than -4 or greater than or equal to the precision; otherwise they use the `%f' style. Trailing zeros are removed from the fractional portion of the result and a decimal-point character appears only if it is followed by a digit.
The following flags can be used to modify the behavior:
The precision specifies how many digits follow the decimal-point
character for the `%f', `%e', and `%E' conversions. For
these conversions, the default is 6. If the precision is
explicitly 0, this has the rather strange effect of suppressing
the decimal point character entirely! For the `%g' and `%G'
conversions, the precision specifies how many significant digits to
print; if 0 or not specified, it is treated like a value of
1.
Without a type modifier, the floating-point conversions use an argument
of type double. (By the default argument promotions, any
float arguments are automatically converted to double.)
The following type modifier is supported:
long
double.
Here are some examples showing how numbers print using the various floating-point conversions. All of the numbers were printed using this template string:
"|%12.4f|%12.4e|%12.4g|\n"
Here is the output:
| 0.0000| 0.0000e+00| 0| | 1.0000| 1.0000e+00| 1| | -1.0000| -1.0000e+00| -1| | 100.0000| 1.0000e+02| 100| | 1000.0000| 1.0000e+03| 1000| | 10000.0000| 1.0000e+04| 1e+04| | 12345.0000| 1.2345e+04| 1.234e+04| | 100000.0000| 1.0000e+05| 1e+05| | 123456.0000| 1.2346e+05| 1.234e+05|
Notice how the `%g' conversion drops trailing zeros.
This section describes miscellaneous conversions for printf.
The `%c' conversion prints a single character. The int
argument is first converted to an unsigned char. The `-'
flag can be used to specify left-justification in the field, but no
other flags are defined, and no precision or type modifier can be given.
For example:
printf ("%c%c%c%c%c", 'h', 'e', 'l', 'l', 'o');
prints `hello'.
The `%s' conversion prints a string. The corresponding argument
must be of type char *. A precision can be specified to indicate
the maximum number of characters to write; otherwise characters in the
string up to but not including the terminating null character are
written to the output stream. The `-' flag can be used to specify
left-justification in the field, but no other flags or type modifiers
are defined for this conversion. For example:
printf ("%3s%-6s", "no", "where");
prints ` nowhere '.
If you accidentally pass a null pointer as the argument for a `%s' conversion, the GNU library prints it as `(null)'. We think this is more useful than crashing. But it's not good practice to pass a null argument intentionally.
The `%m' conversion prints the string corresponding to the error
code in errno. See section Error Messages. Thus:
fprintf (stderr, "can't open `%s': %m\n", filename);
is equivalent to:
fprintf (stderr, "can't open `%s': %s\n", filename, strerror (errno));
The `%m' conversion is a GNU C library extension.
The `%p' conversion prints a pointer value. The corresponding
argument must be of type void *. In practice, you can use any
type of pointer.
In the GNU system, non-null pointers are printed as unsigned integers, as if a `%#x' conversion were used. Null pointers print as `(nil)'. (Pointers might print differently in other systems.)
For example:
printf ("%p", "testing");
prints `0x' followed by a hexadecimal number--the address of the
string constant "testing". It does not print the word
`testing'.
You can supply the `-' flag with the `%p' conversion to specify left-justification, but no other flags, precision, or type modifiers are defined.
The `%n' conversion is unlike any of the other output conversions.
It uses an argument which must be a pointer to an int, but
instead of printing anything it stores the number of characters printed
so far by this call at that location. The `h' and `l' type
modifiers are permitted to specify that the argument is of type
short int * or long int * instead of int *, but no
flags, field width, or precision are permitted.
For example,
int nchar;
printf ("%d %s%n\n", 3, "bears", &nchar);
prints:
3 bears
and sets nchar to 7, because `3 bears' is seven
characters.
The `%%' conversion prints a literal `%' character. This conversion doesn't use an argument, and no flags, field width, precision, or type modifiers are permitted.
This section describes how to call printf and related functions.
Prototypes for these functions are in the header file `stdio.h'.
Function: int printf (const char *template, ...)
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 fprintf (FILE *stream, const char *template, ...)
This function is just like printf, except that the output is
written to the stream stream instead of stdout.
Function: int sprintf (char *s, const char *template, ...)
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 section Copying and Concatenation.
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 snprintf (char *s, size_t size, const char *template, ...)
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.
The return value is the number of characters stored, not including the terminating null. If this value equals size, then there was not enough space in s for all the output. 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 chars of space. */
int size = 100;
char *buffer = (char *) xmalloc (size);
while (1)
{
/* Try to print in the allocated space. */
int nchars = snprintf (buffer, size,
"value of %s is %s", name, value);
/* If that worked, return the string. */
if (nchars < size)
return buffer;
/* Else try again with twice as much space. */
size *= 2;
buffer = (char *) xrealloc (size, buffer);
}
}
In practice, it is often easier just to use asprintf, below.
The functions in this section do formatted output and place the results in dynamically allocated memory.
Function: int asprintf (char **ptr, const char *template, ...)
This function is similar to sprintf, except that it dynamically
allocates a string (as with malloc; see section Unconstrained Allocation) to hold the output, instead of putting the output in a
buffer you allocate in advance. The ptr argument should be the
address of a char * object, and asprintf stores a pointer
to the newly allocated string at that location.
Here is how to use asprint to get the same result as the
snprintf example, but more easily:
/* 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)
{
char *result;
asprintf (&result, "value of %s is %s", name, value);
return result;
}
Function: int obstack_printf (struct obstack *obstack, const char *template, ...)
This function is similar to asprintf, except that it uses the
obstack obstack to allocate the space. See section Obstacks.
The characters are written onto the end of the current object.
To get at them, you must finish the object with obstack_finish
(see section Growing Objects).
The functions vprintf and friends are provided so that you can
define your own variadic printf-like functions that make use of
the same internals as the built-in formatted output functions.
The most natural way to define such functions would be to use a language
construct to say, "Call printf and pass this template plus all
of my arguments after the first five." But there is no way to do this
in C, and it would be hard to provide a way, since at the C language
level there is no way to tell how many arguments your function received.
Since that method is impossible, we provide alternative functions, the
vprintf series, which lets you pass a va_list to describe
"all of my arguments after the first five."
Before calling vprintf or the other functions listed in this
section, you must call va_start (see section Variadic Functions) to initialize a pointer to the variable arguments. Then you
can call va_arg to fetch the arguments that you want to handle
yourself. This advances the pointer past those arguments.
Once your va_list pointer is pointing at the argument of your
choice, you are ready to call vprintf. That argument