setvbuf

int setvbuf ( FILE * stream, char * buffer, int mode, size_t size );

Change stream buffering

Specifies a buffer for stream. The function allows to specify the mode and size of the buffer (in bytes).

If buffer is a null pointer, the function automatically allocates a buffer (using size as a hint on the size to use). Otherwise, the array pointed by buffer may be used as a buffer of size bytes.

This function should be called once the stream has been associated with an open file, but before any input or output operation is performed with it.

A stream buffer is a block of data that acts as intermediary between the i/o operations and the physical file associated to the stream: For output buffers, data is output to the buffer until its maximum capacity is reached, then it is flushed (i.e.: all data is sent to the physical file at once and the buffer cleared). Likewise, input buffers are filled from the physical file, from which data is sent to the operations until exhausted, at which point new data is acquired from the file to fill the buffer again.

Stream buffers can be explicitly flushed by calling fflush. They are also automatically flushed by fclose and freopen, or when the program terminates normally.

All files are opened with a default allocated buffer (fully buffered) if they are known to not refer to an interactive device. This function can be used to either redefine the buffer size or mode, to define a user-allocated buffer or to disable buffering for the stream.

The default streams stdin and stdout are fully buffered by default if they are known to not refer to an interactive device. Otherwise, they may either be line buffered or unbuffered by default, depending on the system and library implementation. The same is true for stderr, which is always either line buffered or unbuffered by default.

Parameters

stream: Pointer to a FILE object that identifies an open stream.
buffer: User allocated buffer. Shall be at least size bytes long.
If set to a null pointer, the function automatically allocates a buffer.
mode: Specifies a mode for file buffering. Three special macro constants (_IOFBF, _IOLBF and _IONBF) are defined in <cstdio> to be used as the value for this parameter:

_IOFBF Full buffering: On output, data is written once the buffer is full (or flushed). On Input, the buffer is filled when an input operation is requested and the buffer is empty.

_IOLBF Line buffering: On output, data is written when a newline character is inserted into the stream or when the buffer is full (or flushed), whatever happens first. On Input, the buffer is filled up to the next newline character when an input operation is requested and the buffer is empty.

_IONBF No buffering: No buffer is used. Each I/O operation is written as soon as possible. In this case, the buffer and size parameters are ignored.
size: Buffer size, in bytes.
If the buffer argument is a null pointer, this value may determine the size automatically allocated by the function for the buffer.

Return Value

If the buffer is correctly assigned to the file, a zero value is returned.
Otherwise, a non-zero value is returned; This may be due to an invalid mode parameter or to some other error allocating or assigning the buffer.

Example

/* setvbuf example */
#include <stdio.h>
int main ()
{
 FILE *pFile;
 pFile=fopen ("myfile.txt","w");
 setvbuf ( pFile , NULL , _IOFBF , 1024 );
 // File operations here
 fclose (pFile);
 return 0;
}

In this example, a file called myfile.txt is created and a full buffer of 1024 bytes is requested for the associated stream, so the data output to this stream should only be written to the file each time the 1024-byte buffer is filled.

functions

objects

types

macro constants

setvbuf

Parameters

Return Value

Example

See also