X-Git-Url: https://git.subgeniuskitty.com/unix-history/.git/blobdiff_plain/8c8a5b54e79564c14fc7a2823a21a8f048449bcf..af359dea2e5ab3e937b62107ecd6a51d78189ed7:/usr/src/lib/libc/stdio/setbuf.3 diff --git a/usr/src/lib/libc/stdio/setbuf.3 b/usr/src/lib/libc/stdio/setbuf.3 index cf072a928d..618d910203 100644 --- a/usr/src/lib/libc/stdio/setbuf.3 +++ b/usr/src/lib/libc/stdio/setbuf.3 @@ -1,32 +1,60 @@ -.\" Copyright (c) 1980 Regents of the University of California. -.\" All rights reserved. The Berkeley software License Agreement -.\" specifies the terms and conditions for redistribution. +.\" Copyright (c) 1980, 1991 Regents of the University of California. +.\" All rights reserved. .\" -.\" @(#)setbuf.3 6.7 (Berkeley) %G% +.\" This code is derived from software contributed to Berkeley by +.\" the American National Standards Committee X3, on Information +.\" Processing Systems. .\" -.TH SETBUF 3 -.UC 4 -.SH NAME -setbuf, setbuffer, setlinebuf, setvbuf \- assign buffering to a stream -.SH SYNOPSIS -.nf -.ft B -#include - -int -setbuf(FILE *stream, char *buf); - -int -setbuffer(FILE *stream, char *buf, size_t size); - -int -setlinebuf(FILE *stream); - -int -setvbuf(FILE *stream, char *buf, int mode, size_t size); -.ft R -.fi -.SH DESCRIPTION +.\" 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 +.\" +.Dd June 29, 1991 +.Dt SETBUF 3 +.Os BSD 4 +.Sh NAME +.Nm setbuf , +.Nm setbuffer , +.Nm setlinebuf , +.Nm setvbuf +.Nd stream buffering operations +.Sh SYNOPSIS +.Fd #include +.Ft int +.Fn setbuf "FILE *stream" "char *buf" +.Ft int +.Fn setbuffer "FILE *stream" "char *buf" "size_t size" +.Ft int +.Fn setlinebuf "FILE *stream" +.Ft int +.Fn setvbuf "FILE *stream" "char *buf" "int mode" "size_t size" +.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 @@ -35,95 +63,115 @@ 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). -.I Fflush -(see -.IR fclose (3)) +The function +.Xr fflush 3 may be used to force the block out early. +(See +.Xr fclose 3 . ) Normally all files are block buffered. -A buffer is obtained from -.IR malloc (3) -upon the first read or write operation on the file. +When the first +.Tn I/O +operation occurs on a file, +.Xr malloc 3 +is called, +and a buffer is obtained. If a stream refers to a terminal (as -.B stdout +.Em stdout normally does) it is line buffered. -The standard stream -.B stderr +The standard error stream +.Em stderr is always unbuffered. -.PP -.I Setvbuf +.Pp +The +.Fn setvbuf +function may be used at any time on any open stream to change its buffer. The -.I mode +.Fa mode parameter must be one of the following three macros: -.RS -.TP 8 -.B _IONBF +.Bl -tag -width _IOFBF -offset indent +.It Dv _IONBF unbuffered -.br -.ns -.TP 8 -.B _IOLBF +.It Dv _IOLBF line buffered -.br -.ns -.TP 8 -.B _IOFBF +.It Dv _IOFBF fully buffered -.RE -.LP +.El +.Pp Except for unbuffered files, the -.I buf +.Fa buf argument should point to a buffer at least -.I size +.Fa size bytes long; this buffer will be used instead of the current buffer. -If -.I buf +If the argument +.Fa buf is NULL, only the mode is affected; a new buffer will be allocated on the next read or write operation. -.I Setvbuf +The +.Fn setvbuf +function may be used at any time, but can only change the mode of a stream when it is not ``active'': -that is, before any I/O, +that is, before any +.Tn I/O , or immediately after a call to -.IR fflush . -.PP +.Xr fflush . +.Pp The other three calls are, in effect, simply aliases for calls to -.IR setvbuf . -.I Setbuf +.Fn setvbuf . +The +.Fn setbuf +function is exactly equivalent to the call -.sp -.ti +0.5i -setvbuf(stream, buf, buf ? _IOFBF : _IONBF, BUFSIZ); -.sp -.I Setbuffer +.Pp +.Dl setvbuf(stream, buf, buf ? _IOFBF : _IONBF, BUFSIZ); +.Pp +The +.Fn setbuffer +function is the same, except that the size of the buffer is up to the caller, -rather than being determined by the manifest constant -.SM -.BR BUFSIZ . -.I Setlinebuf -is exactly equivalent to the call -.sp -.ti +0.5i -setvbuf(stream, (char *)NULL, _IOLBF, 0); -.SH "SEE ALSO" -fopen(3), fclose(3), fread(3), malloc(3), puts(3), printf(3) -.SH STANDARDS -.I Setbuf +rather than being determined by the default +.Dv BUFSIZ . +The +.Fn setlinebuf +function +is exactly equivalent to the call: +.Pp +.Dl setvbuf(stream, (char *)NULL, _IOLBF, 0); +.Sh SEE ALSO +.Xr fopen 3 , +.Xr fclose 3 , +.Xr fread 3 , +.Xr malloc 3 , +.Xr puts 3 , +.Xr printf 3 +.Sh STANDARDS +The +.Fn setbuf and -.I setvbuf -conform to ANSI X3.159-1989 (``ANSI C''). -.SH BUGS +.Fn setvbuf +functions +conform to +.St -ansiC . +.Sh BUGS The -.I setbuffer +.Fn setbuffer +and +.Fn setlinebuf +functions are not portable to versions of +.Bx +before +.Bx 4.2 . +On +.Bx 4.2 and -.I setlinebuf -functions are not portable to versions of BSD UNIX before 4.2BSD. -On 4.2BSD and 4.3BSD systems, -.I setbuf +.Bx 4.3 +systems, +.Fn setbuf always uses a suboptimal buffer size and should be avoided.