setbuf(3)setbuf(3)NAME
setbuf, setvbuf, setvbuf_unlocked, setbuffer, setlinebuf - Assign
buffering to a stream
SYNOPSIS
#include <stdio.h>
void setbuf(
FILE *stream,
char *buffer ); int setvbuf(
FILE *stream,
char *buffer,
int mode,
size_t size ); int setvbuf_unlocked(
FILE *stream,
char *buffer,
int mode,
size_t size ); void setbuffer(
FILE *stream,
char *buffer,
int size ); void setlinebuf(
FILE *stream );
LIBRARY
Standard C Library (libc)
STANDARDS
Interfaces documented on this reference page conform to industry stan‐
dards as follows:
setbuf(), setvbuf(): XPG4, XPG4-UNIX
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
PARAMETERS
Specifies the input/output stream. Points to a character array.
Determines how the stream parameter is buffered. Specifies the size of
the buffer to be used.
DESCRIPTION
The setbuf() function causes the character array pointed to by the buf‐
fer parameter to be used instead of an automatically allocated buffer.
Use the setbuf() function after a stream has been opened but before it
is read or written.
If the buffer parameter is a null pointer, input/output is unbuffered.
A constant, BUFSIZ, defined in the stdio.h header file, tells how large
an array is needed:
char buf[BUFSIZ];
For the setvbuf() function, the mode parameter determines how the
stream parameter is buffered: Causes input/output to be fully buffered.
Causes output to be line buffered. The buffer is flushed when a new
line is written, the buffer is full, or input is requested. Causes
input/output to be completely unbuffered.
If the buffer parameter is not a null pointer, the array that the
parameter points to is used for buffering instead of a buffer that is
automatically allocated. The size parameter specifies the size of the
buffer to be used. The constant BUFSIZ in the stdio.h header file is
one buffer size. If input/output is unbuffered, the buffer and size
parameters are ignored. The setbuffer() function, an alternate form of
the setbuf() function, is used after stream has been opened but before
it is read or written. The character array buffer, whose size is deter‐
mined by the size parameter, is used instead of an automatically allo‐
cated buffer. If the buffer parameter is a null pointer, input/output
is completely unbuffered.
The setbuffer() function is not needed under normal circumstances,
since the default file I/O buffer size is optimal.
The setlinebuf() function is used to change stdout or stderr from block
buffered or unbuffered to line buffered. Unlike the setbuf() and set‐
buffer() functions, the setlinebuf() function can be used any time the
file descriptor is active.
A buffer is normally obtained from the malloc() function at the time of
the first getc() or putc() function on the file, except that the stan‐
dard error stream, stderr, is normally not buffered.
Output streams directed to terminals are always either line buffered or
unbuffered.
The setvbuf_unlocked() function is functionally identical to the
setvbuf() function, except that setvbuf_unlocked() may be safely used
only within a scope that is protected by the flockfile() and funlock‐
file() functions used as a pair. The caller must ensure that the stream
is locked before these functions are used.
NOTES
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.
RETURN VALUES
The setvbuf() and setvbuf_unlocked() functions return zero when suc‐
cessful. If they cannot honor the request, or if you give an invalid
value in the mode argument, they return a nonzero value.
ERRORS
If the following condition occurs, the setvbuf() function sets errno to
the corresponding value. The file descriptor that underlies stream is
invalid.
SEE ALSO
Functions: fopen(3), fread(3), getc(3), getwc(3), malloc(3), putc(3),
putwc(3)
Standards: standards(5)setbuf(3)