int setvbuf ( FILE * stream, char * buffer, int mode, size_t size ); |
<cstdio> |
Change stream buffering
Changes the buffer to be used for I/O operations with the specified stream. The function allows to specify the mode and size for the buffer.
This function should be called once the file associated with the stream has already been opened but before any input or output operation has taken place.
The size of the buffer is specified by the size parameter in bytes.
If no buffer is specified (i.e. the buffer argument is NULL), the system dinamically allocates the amount of memory requested by the function (size bytes) and uses it as the buffer for the stream.
The type parameter is used to specify if the buffer has to be fully buffered, line buffered or if the stream has to be unbuffered (see below).
With full buffered streams, writing operations do not write directly to the physical device associated with them; instead, the data is accumulated in the buffer and written to the device as a block when the bufer is filled. This writing of the whole block can be forced by flushing the stream, which can be done by calling fflush or by closing the file (fclose). All buffers are also flushed when the program terminates.
With line buffered streams, the buffer is writen to the physical device each time a new-line character is written.
With unbuffered streams, data is written to the device as soon as possible after each writing operation.
All files are opened with a default allocated buffer. This function can be used to either redefine the buffer size, define a user-allocated buffer or to disable buffering for the file. System standard streams like stdout and stderr are unbuffered by default if they are not redirected.
Parameters
- stream
- Pointer to a FILE object that identifies an open stream.
- buffer
- User allocated buffer. Must be at least size bytes long.
If set to NULL, the function automatically allocates a buffer of the specified size.
- mode
- Specifies a mode for file buffering:
_IOFBF | Full buffering: On output, data is written once the buffer is full. 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, 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 NULL, this determines the minimum size automatically allocated by the function for the buffer, otherwise it must be a value equal or lower to the size in bytes of the array specified as 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 invalid
type or
size parameters or to an error while allocating memory if
NULL was specified as
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 example.txt is created and a full buffer of 1024 bytes is assigned to its stream, so the data output to this stream should only be written to the file each time the 1024-byte buffer is full.
See also
setbuf | Set stream buffer (function) |
fopen | Open file (function) |
fflush | Flush stream (function) |