stdio/setbuf.3

   1 .\" Copyright (c) 1980, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" This code is derived from software contributed to Berkeley by
   5 .\" the American National Standards Committee X3, on Information
   6 .\" Processing Systems.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\" 3. All advertising materials mentioning features or use of this software
  17 .\"    must display the following acknowledgement:
  18 .\"     This product includes software developed by the University of
  19 .\"     California, Berkeley and its contributors.
  20 .\" 4. Neither the name of the University nor the names of its contributors
  21 .\"    may be used to endorse or promote products derived from this software
  22 .\"    without specific prior written permission.
  23 .\"
  24 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  25 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  26 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  27 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  28 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  29 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  30 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  31 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  32 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  33 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  34 .\" SUCH DAMAGE.
  35 .\"
  36 .\"     @(#)setbuf.3    8.1 (Berkeley) 6/4/93
  37 .\" $FreeBSD: src/lib/libc/stdio/setbuf.3,v 1.15 2004/08/24 21:48:21 alfred Exp $
  38 .\"
  39 .Dd June 4, 1993
  40 .Dt SETBUF 3
  41 .Os
  42 .Sh NAME
  43 .Nm setbuf ,
  44 .Nm setbuffer ,
  45 .Nm setlinebuf ,
  46 .Nm setvbuf
  47 .Nd stream buffering operations
  48 .Sh LIBRARY
  49 .Lb libc
  50 .Sh SYNOPSIS
  51 .In stdio.h
  52 .Ft void
  53 .Fo setbuf
  54 .Fa "FILE *restrict stream"
  55 .Fa "char *restrict buf"
  56 .Fc
  57 .Ft void
  58 .Fo setbuffer
  59 .Fa "FILE *stream"
  60 .Fa "char *buf"
  61 .Fa "int size"
  62 .Fc
  63 .Ft int
  64 .Fo setlinebuf
  65 .Fa "FILE *stream"
  66 .Fc
  67 .Ft int
  68 .Fo setvbuf
  69 .Fa "FILE *restrict stream"
  70 .Fa "char *restrict buf"
  71 .Fa "int type"
  72 .Fa "size_t size"
  73 .Fc
  74 .Sh DESCRIPTION
  75 Three types of buffering are available:
  76 unbuffered, block buffered, and line buffered.
  77 When an output stream is unbuffered, information appears on the
  78 destination file or terminal as soon as written;
  79 when it is block buffered,
  80 many characters are saved up and written as a block;
  81 when it is line buffered,
  82 characters are saved up until a newline is output
  83 or input is read from any stream attached to a terminal device
  84 (typically
  85 .Dv stdin ) .
  86 The function
  87 .Xr fflush 3
  88 may be used to force the block out early.
  89 (See
  90 .Xr fclose 3 . )
  91 .Pp
  92 Normally, all files are block buffered.
  93 When the first
  94 .Tn I/O
  95 operation occurs on a file,
  96 .Xr malloc 3
  97 is called and an optimally-sized buffer is obtained.
  98 If a stream refers to a terminal
  99 (as
 100 .Dv stdout
 101 normally does), it is line buffered.
 102 The standard error stream
 103 .Dv stderr
 104 is always unbuffered.
 105 .Pp
 106 The
 107 .Fn setvbuf
 108 function
 109 may be used to alter the buffering behavior of a stream.
 110 The
 111 .Fa type
 112 argument must be one of the following three macros:
 113 .Bl -tag -width _IOFBF -offset indent
 114 .It Dv _IONBF
 115 unbuffered
 116 .It Dv _IOLBF
 117 line buffered
 118 .It Dv _IOFBF
 119 fully buffered
 120 .El
 121 .Pp
 122 The
 123 .Fa size
 124 argument may be given as zero
 125 to obtain deferred optimal-size buffer allocation as usual.
 126 If it is not zero,
 127 then except for unbuffered files, the
 128 .Fa buf
 129 argument should point to a buffer at least
 130 .Fa size
 131 bytes long;
 132 this buffer will be used instead of the current buffer.
 133 If
 134 .Fa buf
 135 is not NULL, it is the caller's responsibility to
 136 .Xr free 3
 137 this buffer after closing the stream.
 138 (If the
 139 .Fa size
 140 argument
 141 is not zero but
 142 .Fa buf
 143 is
 144 .Dv NULL ,
 145 a buffer of the given size will be allocated immediately,
 146 and released on close.
 147 This is an extension to ANSI C;
 148 portable code should use a size of 0 with any
 149 .Dv NULL
 150 buffer.)
 151 .Pp
 152 The
 153 .Fn setvbuf
 154 function may be used at any time,
 155 but may have peculiar side effects
 156 (such as discarding input or flushing output)
 157 if the stream is ``active''.
 158 Portable applications should call it only once on any given stream,
 159 and before any
 160 .Tn I/O
 161 is performed.
 162 .Pp
 163 The other three calls are, in effect, simply aliases for calls to
 164 .Fn setvbuf .
 165 Except for the lack of a return value, the
 166 .Fn setbuf
 167 function is exactly equivalent to the call
 168 .Pp
 169 .Dl "setvbuf(stream, buf, buf ? _IOFBF : _IONBF, BUFSIZ);"
 170 .Pp
 171 The
 172 .Fn setbuffer
 173 function
 174 is the same, except that the size of the buffer is up to the caller,
 175 rather than being determined by the default
 176 .Dv BUFSIZ .
 177 The
 178 .Fn setlinebuf
 179 function
 180 is exactly equivalent to the call:
 181 .Pp
 182 .Dl "setvbuf(stream, (char *)NULL, _IOLBF, 0);"
 183 .Sh RETURN VALUES
 184 The
 185 .Fn setvbuf
 186 function returns 0 on success, or
 187 .Dv EOF
 188 if the request cannot be honored
 189 (note that the stream is still functional in this case).
 190 .Pp
 191 The
 192 .Fn setlinebuf
 193 function returns what the equivalent
 194 .Fn setvbuf
 195 would have returned.
 196 .Sh SEE ALSO
 197 .Xr fclose 3 ,
 198 .Xr fopen 3 ,
 199 .Xr fread 3 ,
 200 .Xr malloc 3 ,
 201 .Xr printf 3 ,
 202 .Xr puts 3
 203 .Sh STANDARDS
 204 The
 205 .Fn setbuf
 206 and
 207 .Fn setvbuf
 208 functions
 209 conform to
 210 .St -isoC .
 211 .Sh BUGS
 212 The
 213 .Fn setbuffer
 214 and
 215 .Fn setlinebuf
 216 functions are not portable to versions of
 217 .Bx
 218 before
 219 .Bx 4.2 .
 220 On
 221 .Bx 4.2
 222 and
 223 .Bx 4.3
 224 systems,
 225 .Fn setbuf
 226 always uses a suboptimal buffer size and should be avoided.