C++

Reference

<cstdio> (stdio.h)

function
<cstdio>

setbuf

void setbuf ( FILE * stream, char * buffer );
Set stream buffer
Specifies the buffer to be used by the stream for I/O operations, which becomes a fully buffered stream. Or, alternatively, if buffer is a null pointer, buffering is disabled for the stream, which becomes an unbuffered stream.

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.

The buffer is assumed to be at least BUFSIZ bytes in size (see setvbuf to specify a size of the buffer).

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.

A full buffered stream uses the entire size of the buffer as buffer whenever enough data is available (see setvbuf for other buffer modes).

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 set a specific memory block to be used as 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.

A call to this function is equivalent to calling setvbuf with _IOFBF as mode and BUFSIZ as size (when buffer is not a null pointer), or equivalent to calling it with _IONBF as mode (when it is a null pointer).

Parameters

stream
Pointer to a FILE object that identifies an open stream.
buffer
User allocated buffer. Shall be at least BUFSIZ bytes long.
Alternatively, a null pointer can be specified to disable buffering.

Return Value

none.

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
 
/* setbuf example */
#include <stdio.h>

int main ()
{
  char buffer[BUFSIZ];
  FILE *pFile1, *pFile2;

  pFile1=fopen ("myfile1.txt","w");
  pFile2=fopen ("myfile2.txt","a");

  setbuf ( pFile1 , buffer );
  fputs ("This is sent to a buffered stream",pFile1);
  fflush (pFile1);

  setbuf ( pFile2 , NULL );
  fputs ("This is sent to an unbuffered stream",pFile2);

  fclose (pFile1);
  fclose (pFile2);

  return 0;
}

In this example, two files are opened for writing. The stream associated with the file myfile1.txt is set to a user allocated buffer; a writing operation to it is performed; the data is logically part of the stream, but it has not been writen to the device until the fflush function is called.
The second buffer in the example, associated with the file myfile2.txt, is set to unbuffered, so the subsequent output operation is written to the device as soon as possible.
The final state, however, is the same for both buffered and unbuffered streams once the files have been closed (closing a file flushes its buffer).

See also

setvbuf
Change stream buffering (function)
fopen
Open file (function)
fflush
Flush stream (function)