HP 3000 Manuals HP 3000 Manuals
setbuf
Assigns a buffer to an open stream.
Syntax
#include <stdio.h>
void setbuf (FILE *stream, char *buffer);
Parameters
stream A pointer to an open stream.
buffer Either a pointer to a character array for buffered I/O, or
null for unbuffered I/O.
Return Values
None.
Description
Normally, a standard I/O buffer is obtained through a call to malloc() on
the first call to getc() or putc() (which all I/O functions eventually
call). The standard I/O system normally buffers I/O in a buffer which is
BUFSIZ bytes long. Exceptions are stdout, which, when directed to a
terminal, is line buffered, and stderr, which is normally unbuffered.
NOTE Using an automatic array as a standard I/O buffer can be dangerous.
Automatic variables are only defined in the code block in which
they are declared. Thus, buffering which relies on an automatic
array is only in effect during the current code block (main program
or function). If you pass a file pointer to another function, and
the stream pointed to by that file pointer is buffered using an
automatic array, memory faults or other errors can occur.
Therefore, if you use an automatic array for stream buffering, the
stream should be used and closed only in the code block containing
the array declaration. To avoid this restriction, use global or
static arrays for buffering:
char buffer[BUFSIZ];
:
main()
{
:
setbuf (fp, buffer);
}
The setbuf function enables you to change the buffer used for all
standard I/O functions. The following example of a code fragment causes
the array buffer to be used for buffering:
:
FILE *fp;
char buffer[BUFSIZ];
fp = fopen(argv[1], "r");
:
setbuf(fp, buffer);
:
This fragment shows the correct order of events. First, the file is
opened, and the buffering is assigned using setbuf(). From that point on
any input taken from fp is buffered through the array buffer. Buffering
can be eliminated altogether by specifying the null pointer in place of
the buffer name, as in
setbuf(fp, NULL);
This causes input or output using fp to be completely unbuffered.
The setbuf function is limited to buffer sizes of either BUFSIZ bytes or
zero. setbuf() assumes that the character array pointed to by buffer is
BUFSIZ bytes. Passing setbuf() a (non-null) pointer to a smaller array
can cause severe problems during operation because the standard I/O
functions might overwrite memory following the end of the buffer.
See Also
setvbuf(), fopen(), getc(), malloc(), putc(), ANSI C 4.9.5.5, POSIX.1 8.1