Standard I/O Buffering(5.4)

Buffering

The goal of the buffering provided by the standard I/O library is to use the minimum number ofread and write calls. (Recall  Figure 3.5 , where we showed the amount of CPU time required to perform I/O using various buffer sizes.) Also, it tries to do its buffering automatically for each I/O stream, obviating the need for the application to worry about it. Unfortunately, the single aspect of the standard I/O library that generates the most confusion is its buffering.
Three types of buffering are provided:

Fully buffered. In this case, actual I/O takes place when the standard I/O buffer is filled. Files residing on disk are normally fully buffered by the standard I/O library. The buffer used is usually obtained by one of the standard I/O functions calling malloc ( Section 7.8 ) the first time I/O is performed on a stream.
The term flush describes the writing of a standard I/O buffer. A buffer can be flushed automatically by the standard I/O routines, such as when a buffer fills, or we can call the function fflush to flush a stream. Unfortunately, in the UNIX environment, flush means two different things. In terms of the standard I/O library, it means writing out the contents of a buffer, which may be partially filled. In terms of the terminal driver, such as the tcflushfunction in  Chapter 18 , it means to discard the data that's already stored in a buffer.

Line buffered. In this case, the standard I/O library performs I/O when a newline character is encountered on input or output. This allows us to output a single character at a time (with the standard I/O fputc function), knowing that actual I/O will take place only when we finish writing each line. Line buffering is typically used on a stream when it refers to a terminal: standard input and standard output, for example.
Line buffering comes with two caveats. First, the size of the buffer that the standard I/O library is using to collect each line is fixed, so I/O might take place if we fill this buffer before writing a newline. Second, whenever input is requested through the standard I/O library from either (a) an unbuffered stream or (b) a line-buffered stream (that requires data to be requested from the kernel), all line-buffered output streams are flushed. The reason for the qualifier on (b) is that the requested data may already be in the buffer, which doesn't require data to be read from the kernel. Obviously, any input from an unbuffered stream, item (a), requires data to be obtained from the kernel.

Unbuffered. The standard I/O library does not buffer the characters. If we write 15 characters with the standard I/O fputs function, for example, we expect these 15 characters to be output as soon as possible, probably with the write function from  Section 3.8 .
The standard error stream, for example, is normally unbuffered. This is so that any error messages are displayed as quickly as possible, regardless of whether they contain a newline.

ISO C requires the following buffering characteristics.

Standard input and standard output are fully buffered, if and only if they do not refer to an interactive device.

Standard error is never fully buffered.

This, however, doesn't tell us whether standard input and standard output can be unbuffered or line buffered if they refer to an interactive device and whether standard error should be unbuffered or line buffered. Most implementations default to the following types of buffering.

Standard error is always unbuffered.

All other streams are line buffered if they refer to a terminal device; otherwise, they are fully buffered.
The four platforms discussed in this book follow these conventions for standard I/O buffering: standard error is unbuffered, streams open to terminal devices are line buffered, and all other streams are fully buffered.

We explore standard I/O buffering in more detail in  Section 5.12  and  Figure 5.11 .
If we don't like these defaults for any given stream, we can change the buffering by calling either of the following two functions.

#include                                                

 void setbuf(FILE *restrict fp, char *restrict buf); 

 int setvbuf(FILE *restrict fp, char *restrict buf, 

int mode, size_t size);

Returns: 0 if OK, nonzero on error
 
These functions must be called after the stream has been opened (obviously, since each requires a valid file pointer as its first argument) but before any other operation is performed on the stream.
With setbuf, we can turn buffering on or off. To enable buffering, buf must point to a buffer of length BUFSIZ, a constant defined in . Normally, the stream is then fully buffered, but some systems may set line buffering if the stream is associated with a terminal device. To disable buffering, we set buf to NULL.
With setvbuf, we specify exactly which type of buffering we want. This is done with the modeargument:
_IOFBF
fully buffered
_IOLBF
line buffered
_IONBF
unbuffered
If we specify an unbuffered stream, the buf and size arguments are ignored. If we specify fully buffered or line buffered, buf and size can optionally specify a buffer and its size. If the stream is buffered and buf is NULL, the standard I/O library will automatically allocate its own buffer of the appropriate size for the stream. By appropriate size, we mean the value specified by the constant BUFSIZ.
Some C library implementations use the value from the st_blksize member of the statstructure (see  Section 4.2 ) to determine the optimal standard I/O buffer size. As we will see later in this chapter, the GNU C library uses this method.
Figure 5.1  summarizes the actions of these two functions and their various options.
Figure 5.1. Summary of the setbuf and setvbuf functions
Function
mode
buf
Buffer and length
Type of buffering
setbuf
 
non-null
user buf of length BUFSIZ
fully buffered or line buffered
NULL
(no buffer)
unbuffered
setvbuf
_IOLBF
non-null
user buf of length size
fully buffered
NULL
system buffer of appropriate length
_IOFBF
non-null
user buf of length size
line buffered
NULL
system buffer of appropriate length
_IONBF
(ignored)
(no buffer)
unbuffered
 
Be aware that if we allocate a standard I/O buffer as an automatic variable within a function, we have to close the stream before returning from the function. (We'll discuss this more in  Section 7.8 .) Also, some implementations use part of the buffer for internal bookkeeping, so the actual number of bytes of data that can be stored in the buffer is less than size. In general, we should let the system choose the buffer size and automatically allocate the buffer. When we do this, the standard I/O library automatically releases the buffer when we close the stream.
At any time, we can force a stream to be flushed.
 #include  

 int fflush(FILE *fp);

Returns: 0 if OK, EOF on error
 
This function causes any unwritten data for the stream to be passed to the kernel. As a special case, if fp is NULL, this function causes all output streams to be flushed.