function
<cstdio>

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:
_IOFBFFull 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.
_IOLBFLine 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.
_IONBFNo 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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
 
/* 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.

See also

setbuf
Set stream buffer (function )
fopen
Open file (function )
fflush
Flush stream (function )

C++