6/lib/libc/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$
  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 .Fn setbuf "FILE * restrict stream" "char * restrict buf"
  54 .Ft void
  55 .Fn setbuffer "FILE *stream" "char *buf" "int size"
  56 .Ft int
  57 .Fn setlinebuf "FILE *stream"
  58 .Ft int
  59 .Fn setvbuf "FILE * restrict stream" "char * restrict buf" "int mode" "size_t size"
  60 .Sh DESCRIPTION
  61 The three types of buffering available are unbuffered, block buffered,
  62 and line buffered.
  63 When an output stream is unbuffered, information appears on the
  64 destination file or terminal as soon as written;
  65 when it is block buffered many characters are saved up and written as a block;
  66 when it is line buffered characters are saved up until a newline is
  67 output or input is read from any stream attached to a terminal device
  68 (typically
  69 .Dv stdin ) .
  70 The function
  71 .Xr fflush 3
  72 may be used to force the block out early.
  73 (See
  74 .Xr fclose 3 . )
  75 .Pp
  76 Normally all files are block buffered.
  77 When the first
  78 .Tn I/O
  79 operation occurs on a file,
  80 .Xr malloc 3
  81 is called,
  82 and an optimally-sized buffer is obtained.
  83 If a stream refers to a terminal
  84 (as
  85 .Dv stdout
  86 normally does) it is line buffered.
  87 The standard error stream
  88 .Dv stderr
  89 is always unbuffered.
  90 .Pp
  91 The
  92 .Fn setvbuf
  93 function
  94 may be used to alter the buffering behavior of a stream.
  95 The
  96 .Fa mode
  97 argument must be one of the following three macros:
  98 .Bl -tag -width _IOFBF -offset indent
  99 .It Dv _IONBF
 100 unbuffered
 101 .It Dv _IOLBF
 102 line buffered
 103 .It Dv _IOFBF
 104 fully buffered
 105 .El
 106 .Pp
 107 The
 108 .Fa size
 109 argument may be given as zero
 110 to obtain deferred optimal-size buffer allocation as usual.
 111 If it is not zero,
 112 then except for unbuffered files, the
 113 .Fa buf
 114 argument should point to a buffer at least
 115 .Fa size
 116 bytes long;
 117 this buffer will be used instead of the current buffer.
 118 If
 119 .Fa buf
 120 is not
 121 .Dv NULL ,
 122 it is the caller's responsibility to
 123 .Xr free 3
 124 this buffer after closing the stream.
 125 (If the
 126 .Fa size
 127 argument
 128 is not zero but
 129 .Fa buf
 130 is
 131 .Dv NULL ,
 132 a buffer of the given size will be allocated immediately,
 133 and released on close.
 134 This is an extension to ANSI C;
 135 portable code should use a size of 0 with any
 136 .Dv NULL
 137 buffer.)
 138 .Pp
 139 The
 140 .Fn setvbuf
 141 function may be used at any time,
 142 but may have peculiar side effects
 143 (such as discarding input or flushing output)
 144 if the stream is ``active''.
 145 Portable applications should call it only once on any given stream,
 146 and before any
 147 .Tn I/O
 148 is performed.
 149 .Pp
 150 The other three calls are, in effect, simply aliases for calls to
 151 .Fn setvbuf .
 152 Except for the lack of a return value, the
 153 .Fn setbuf
 154 function is exactly equivalent to the call
 155 .Pp
 156 .Dl "setvbuf(stream, buf, buf ? _IOFBF : _IONBF, BUFSIZ);"
 157 .Pp
 158 The
 159 .Fn setbuffer
 160 function
 161 is the same, except that the size of the buffer is up to the caller,
 162 rather than being determined by the default
 163 .Dv BUFSIZ .
 164 The
 165 .Fn setlinebuf
 166 function
 167 is exactly equivalent to the call:
 168 .Pp
 169 .Dl "setvbuf(stream, (char *)NULL, _IOLBF, 0);"
 170 .Sh RETURN VALUES
 171 The
 172 .Fn setvbuf
 173 function returns 0 on success, or
 174 .Dv EOF
 175 if the request cannot be honored
 176 (note that the stream is still functional in this case).
 177 .Pp
 178 The
 179 .Fn setlinebuf
 180 function returns what the equivalent
 181 .Fn setvbuf
 182 would have returned.
 183 .Sh SEE ALSO
 184 .Xr fclose 3 ,
 185 .Xr fopen 3 ,
 186 .Xr fread 3 ,
 187 .Xr malloc 3 ,
 188 .Xr printf 3 ,
 189 .Xr puts 3
 190 .Sh STANDARDS
 191 The
 192 .Fn setbuf
 193 and
 194 .Fn setvbuf
 195 functions
 196 conform to
 197 .St -isoC .
 198 .Sh BUGS
 199 The
 200 .Fn setbuffer
 201 and
 202 .Fn setlinebuf
 203 functions are not portable to versions of
 204 .Bx
 205 before
 206 .Bx 4.2 .
 207 On
 208 .Bx 4.2
 209 and
 210 .Bx 4.3
 211 systems,
 212 .Fn setbuf
 213 always uses a suboptimal buffer size and should be avoided.