diff options
Diffstat (limited to 'man3/setbuf.3')
| -rw-r--r-- | man3/setbuf.3 | 190 |
1 files changed, 190 insertions, 0 deletions
diff --git a/man3/setbuf.3 b/man3/setbuf.3 new file mode 100644 index 000000000..5c58a43db --- /dev/null +++ b/man3/setbuf.3 @@ -0,0 +1,190 @@ +.\" Copyright (c) 1980, 1991 Regents of the University of California. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to Berkeley by +.\" the American National Standards Committee X3, on Information +.\" Processing Systems. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)setbuf.3 6.10 (Berkeley) 6/29/91 +.\" +.\" Converted for Linux, Mon Nov 29 14:55:24 1993, faith@cs.unc.edu +.\" Added section to BUGS, Sun Mar 12 22:28:33 MET 1995, +.\" Thomas.Koenig@ciw.uni-karlsruhe.de +.\" Correction, Sun, 11 Apr 1999 15:55:18, +.\" Martin Vicente <martin@netadmin.dgac.fr> +.\" Correction, 2000-03-03, Andreas Jaeger <aj@suse.de> +.\" Added return value for setvbuf, aeb, +.\" +.TH SETBUF 3 2001-06-09 "Linux" "Linux Programmer's Manual" +.SH NAME +setbuf, setbuffer, setlinebuf, setvbuf \- stream buffering operations +.SH SYNOPSIS +.na +.B #include <stdio.h> +.sp +.BI "void setbuf(FILE *" stream ", char *" buf ); +.br +.BI "void setbuffer(FILE *" stream ", char *" buf ", size_t " size ); +.br +.BI "void setlinebuf(FILE *" stream ); +.br +.BI "int setvbuf(FILE *" stream ", char *" buf ", int " mode +.BI ", size_t " size ); +.ad +.SH DESCRIPTION +The three types of buffering available are unbuffered, block buffered, and +line buffered. When an output stream is unbuffered, information appears 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 +.BR fflush (3) +may be used to force the block out early. +(See +.BR fclose (3).) +Normally all files are block buffered. When the first I/O operation occurs +on a file, +.BR malloc (3) +is called, and a buffer is obtained. If a stream refers to a terminal (as +.I stdout +normally does) it is line buffered. The standard error stream +.I stderr +is always unbuffered by default. +.PP +The +.B setvbuf +function may be used on any open stream to change its buffer. +The +.I mode +parameter must be one of the following three macros: +.RS +.TP +.B _IONBF +unbuffered +.TP +.B _IOLBF +line buffered +.TP +.B _IOFBF +fully buffered +.RE +.PP +Except for unbuffered files, the +.I buf +argument should point to a buffer at least +.I size +bytes long; this buffer will be used instead of the current buffer. If the +argument +.I buf +is +.BR NULL , +only the mode is affected; a new buffer will be allocated on the next read +or write operation. The +.B setvbuf +function may only be used after opening a stream and before any other +operations have been performed on it. +.PP +The other three calls are, in effect, simply aliases for calls to +.BR setvbuf . +The +.B setbuf +function is exactly equivalent to the call +.PP +.RS +setvbuf(stream, buf, buf ? _IOFBF : _IONBF, BUFSIZ); +.RE +.PP +The +.B setbuffer +function is the same, except that the size of the buffer is up to the +caller, rather than being determined by the default +.BR BUFSIZ . +The +.B setlinebuf +function is exactly equivalent to the call: +.PP +.RS +setvbuf(stream, (char *)NULL, _IOLBF, 0); +.RE +.SH "RETURN VALUE" +The function +.B setvbuf +returns 0 on success. +It can return any value on failure, but returns nonzero when +.I mode +is invalid or the request cannot be honoured. It may set +.I errno +on failure. +The other functions are void. +.SH "CONFORMING TO" +The +.B setbuf +and +.B setvbuf +functions conform to ANSI X3.159-1989 (``ANSI C''). +.SH BUGS +The +.B setbuffer +and +.B setlinebuf +functions are not portable to versions of BSD before 4.2BSD, and +are available under Linux since libc 4.5.21. On 4.2BSD and 4.3BSD systems, +.B setbuf +always uses a suboptimal buffer size and should be avoided. +.P +You must make sure that both +.I buf +and the space it points to still exist by the time +.I stream +is closed, which also happens at program termination. +.P +For example, the following is illegal: +.nf +.sp +#include <stdio.h> +int main() +{ + char buf[BUFSIZ]; + setbuf(stdin, buf); + printf("Hello, world!\\n"); + return 0; +} +.fi +.sp +.SH "SEE ALSO" +.BR fclose (3), +.BR fflush (3), +.BR fopen (3), +.BR fread (3), +.BR malloc (3), +.BR printf (3), +.BR puts (3) |