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