setbuffer()

Assign block buffering to a stream

Synopsis:

#include <unix.h>

void setbuffer( FILE *iop,
                char *abuf,
                size_t asize );

Arguments:

iop: The stream that you want to set the buffering for.
abuf: NULL, or a pointer to the buffer that you want the stream to use.
asize: The size of the buffer.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The setbuffer() and setlinebuf() functions assign buffering to a stream. The types of buffering available are:

Unbuffered: Information appears on the destination file or terminal as soon as written.
Block-buffered: Many characters are saved and written as a block.
Line-buffered: Characters are saved until either a newline is encountered or input is read from stdin.

You can use fflush() to force the block out early. Normally all files are block-buffered. A buffer is obtained from malloc() when you perform the first getc() or putc() on the file. If the standard stream stdout refers to a terminal, it's line-buffered. The standard stream stderr is unbuffered by default.

If you want to use setbuffer(), you must call it after opening the stream, but before doing any reading or writing. It uses the character array abuf, whose size is given by asize, instead of an automatically allocated buffer. If abuf is NULL, input and output are completely unbuffered. A manifest constant BUFSIZ, defined in the <stdio.h> header, tells how large an array is needed:

char buf[BUFSIZ];

You can use freopen(). to change a stream from unbuffered or line-buffered to block buffered. To change a stream from block-buffered or line-buffered to unbuffered, call freopen(), and then call setbuf() with a buffer argument of NULL.

Classification:

Unix

Safety:
Cancellation point	No
Interrupt handler	No
Signal handler	No
Thread	Yes

Caveats:

A common source of error is allocating buffer space as an automatic variable in a code block, and then failing to close the stream in the same block.