.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
.TH "SETVBUF" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" setvbuf 
.SH NAME
setvbuf \- assign buffering to a stream
.SH SYNOPSIS
.LP
\fB#include <stdio.h>
.br
.sp
int setvbuf(FILE *restrict\fP \fIstream\fP\fB, char *restrict\fP \fIbuf\fP\fB,
int\fP \fItype\fP\fB,
.br
\ \ \ \ \ \  size_t\fP \fIsize\fP\fB);
.br
\fP
.SH DESCRIPTION
.LP
The \fIsetvbuf\fP() function may be used after the stream pointed
to by \fIstream\fP is associated with an open file but
before any other operation (other than an unsuccessful call to \fIsetvbuf\fP())
is performed on the stream. The argument
\fItype\fP determines how \fIstream\fP shall be buffered, as follows:
.IP " *" 3
{_IOFBF} shall cause input/output to be fully buffered.
.LP
.IP " *" 3
{_IOLBF} shall cause input/output to be line buffered.
.LP
.IP " *" 3
{_IONBF} shall cause input/output to be unbuffered.
.LP
.LP
If \fIbuf\fP is not a null pointer, the array it points to may be
used instead of a buffer allocated by \fIsetvbuf\fP() and
the argument \fIsize\fP specifies the size of the array; otherwise,
\fIsize\fP may determine the size of a buffer allocated by
the \fIsetvbuf\fP() function. The contents of the array at any time
are unspecified.
.LP
For information about streams, see \fIStandard I/O Streams\fP .
.SH RETURN VALUE
.LP
Upon successful completion, \fIsetvbuf\fP() shall return 0. Otherwise,
it shall return a non-zero value if an invalid value is
given for \fItype\fP or if the request cannot be honored,   \ and
may set \fIerrno\fP to indicate the error. 
.SH ERRORS
.LP
The \fIsetvbuf\fP() function may fail if:
.TP 7
.B EBADF
The file descriptor underlying \fIstream\fP is not valid. 
.sp
.LP
\fIThe following sections are informative.\fP
.SH EXAMPLES
.LP
None.
.SH APPLICATION USAGE
.LP
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.
.LP
With \fIsetvbuf\fP(), allocating a buffer of \fIsize\fP bytes does
not necessarily imply that all of \fIsize\fP bytes are
used for the buffer area.
.LP
Applications should note that many implementations only provide line
buffering on input from terminal devices.
.SH RATIONALE
.LP
None.
.SH FUTURE DIRECTIONS
.LP
None.
.SH SEE ALSO
.LP
\fIStandard I/O Streams\fP , \fIfopen\fP() , \fIsetbuf\fP() , the
Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI<stdio.h>\fP
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group. In the
event of any discrepancy between this version and the original IEEE and
The Open Group Standard, the original IEEE and The Open Group Standard
is the referee document. The original Standard can be obtained online at
http://www.opengroup.org/unix/online.html .