|
setvbuf
int setvbuf ( FILE * stream , char * buffer , int mode , size_t size ); | stdio.h |
| cplusplus.com |
Change stream buffering.
Changes the buffer to be used for I/O operations with the
specified stream. Size and mode for the buffer can be specified.
This function should be called once the file associated with the
stream has been opened
but before any input or output operation has been done.
The size of the buffer is specified by the size parameter, and can be any value
between 2 and 32767 in bytes, this value may be rounded down by some system due to specific alignment.
buffer can be NULL. In that case system dinamically allocates the amount of
memory requested by size and uses it as 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 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. This can be forced flushing
the stream by calling
fflush or by closing the file
(fclose). All buffers are also flushed
when program terminates.
With unbuffered streams, data is directly written to the device on
each writing operation.
Normally, files are opened with a default allocated buffer, where this function can be used
to 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.
| _IOFBF | Full buffering: On output the data is written to the file once the buffer is full. On Input the buffer is filled when an input operation is requested and buffer is empty. |
| _IOLBF | Line buffering: On output the data will be written to the file when a newline characted is written to the stream or when the buffer is full, whatever happens first. On Input the buffer is filled when an input operation is requested and buffer is empty. |
| _IONBF | No buffering: No buffer is used. Each I/O operation is directly carried out to the file without buffering. buffer and size parameters are ignored. |
Return Value.
If the buffer is correctly assigned to the file a 0 value is returned.
On error, a non-zero value is returned. This can be because an invalid type or size
has been specified or because an error allocating memory (if NULL buffer was specified).
Example.
/* setvbuf example */
#include <stdio.h>
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 is
assigned to its stream, so the data outputed to this stream is only written to the file
each time the 1024-bytes buffer is full.
See also.
setbuf,
fopen,
fflush