Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
SETBUF(3)		 BSD Library Functions Manual		     SETBUF(3)

     setbuf, setbuffer,	setlinebuf, setvbuf -- stream buffering	operations

     Standard C	Library	(libc, -lc)

     #include <stdio.h>

     setbuf(FILE * restrict stream, char * restrict buf);

     setbuffer(FILE *stream, char *buf,	int size);

     setlinebuf(FILE *stream);

     setvbuf(FILE * restrict stream, char * restrict buf, int mode,
	 size_t	size);

     The three types of	buffering available are	unbuffered, block buffered,
     and line buffered.	 When an output	stream is unbuffered, information ap-
     pears on the destination file or terminal as soon as written; when	it is
     block buffered many characters are	saved up and written as	a block; when
     it	is line	buffered characters are	saved up until a newline is output or
     input is read from	any stream attached to a terminal device (typically
     stdin).  The function fflush(3) may be used to force the block out	early.
     (See fclose(3).)

     Normally all files	are block buffered.  When the first I/O	operation oc-
     curs on a file, malloc(3) is called, and an optimally-sized buffer	is ob-
     tained.  If a stream refers to a terminal (as stdout normally does) it is
     line buffered.  The standard error	stream stderr is always	unbuffered.

     The setvbuf() function may	be used	to alter the buffering behavior	of a
     stream.  The mode argument	must be	one of the following three macros:

	   _IONBF  unbuffered

	   _IOLBF  line	buffered

	   _IOFBF  fully buffered

     The size argument may be given as zero to obtain deferred optimal-size
     buffer allocation as usual.  If it	is not zero, then except for un-
     buffered files, the buf argument should point to a	buffer at least	size
     bytes long; this buffer will be used instead of the current buffer.  If
     buf is not	NULL, it is the	caller's responsibility	to free(3) this	buffer
     after closing the stream.	(If the	size argument is not zero but buf is
     NULL, a buffer of the given size will be allocated	immediately, and re-
     leased on close.  This is an extension to ANSI C; portable	code should
     use a size	of 0 with any NULL buffer.)

     The setvbuf() function may	be used	at any time, but may have peculiar
     side effects (such	as discarding input or flushing	output)	if the stream
     is	``active''.  Portable applications should call it only once on any
     given stream, and before any I/O is performed.

     The other three calls are,	in effect, simply aliases for calls to
     setvbuf().	 Except	for the	lack of	a return value,	the setbuf() function
     is	exactly	equivalent to the call

	   setvbuf(stream, buf,	buf ? _IOFBF : _IONBF, BUFSIZ);

     The setbuffer() function is the same, except that the size	of the buffer
     is	up to the caller, rather than being determined by the default BUFSIZ.
     The setlinebuf() function is exactly equivalent to	the call:

	   setvbuf(stream, (char *)NULL, _IOLBF, 0);

     The setvbuf() function returns 0 on success, or EOF if the	request	cannot
     be	honored	(note that the stream is still functional in this case).

     The setlinebuf() function returns what the	equivalent setvbuf() would
     have returned.

     fclose(3),	fopen(3), fread(3), malloc(3), printf(3), puts(3)

     The setbuf() and setvbuf()	functions conform to ISO/IEC 9899:1990
     ("ISO C90").

     The setbuffer() and setlinebuf() functions	are not	portable to versions
     of	BSD before 4.2BSD.  On 4.2BSD and 4.3BSD systems, setbuf() always uses
     a suboptimal buffer size and should be avoided.

BSD				 June 4, 1993				   BSD


Want to link to this manual page? Use this URL:

home | help