man3/setbuf.3

   1 .\" Copyright (c) 1980, 1991 Regents of the University of California.
   2 .\" 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 .\" %%%LICENSE_START(BSD_4_CLAUSE_UCB)
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\" 3. All advertising materials mentioning features or use of this software
  18 .\"    must display the following acknowledgement:
  19 .\"     This product includes software developed by the University of
  20 .\"     California, Berkeley and its contributors.
  21 .\" 4. Neither the name of the University nor the names of its contributors
  22 .\"    may be used to endorse or promote products derived from this software
  23 .\"    without specific prior written permission.
  24 .\"
  25 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  26 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  27 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  28 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  29 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  30 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  31 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  32 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  33 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  34 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  35 .\" SUCH DAMAGE.
  36 .\" %%%LICENSE_END
  37 .\"
  38 .\"     @(#)setbuf.3    6.10 (Berkeley) 6/29/91
  39 .\"
  40 .\" Converted for Linux, Mon Nov 29 14:55:24 1993, faith@cs.unc.edu
  41 .\" Added section to BUGS, Sun Mar 12 22:28:33 MET 1995,
  42 .\"                   Thomas.Koenig@ciw.uni-karlsruhe.de
  43 .\" Correction,  Sun, 11 Apr 1999 15:55:18,
  44 .\"     Martin Vicente <martin@netadmin.dgac.fr>
  45 .\" Correction,  2000-03-03, Andreas Jaeger <aj@suse.de>
  46 .\" Added return value for setvbuf, aeb,
  47 .\"
  48 .TH SETBUF 3  2021-03-22 "Linux" "Linux Programmer's Manual"
  49 .SH NAME
  50 setbuf, setbuffer, setlinebuf, setvbuf \- stream buffering operations
  51 .SH SYNOPSIS
  52 .nf
  53 .B #include <stdio.h>
  54 .PP
  55 .BI "int setvbuf(FILE *restrict " stream ", char *restrict " buf ,
  56 .BI "            int " mode ", size_t " size );
  57 .PP
  58 .BI "void setbuf(FILE *restrict " stream ", char *restrict " buf );
  59 .BI "void setbuffer(FILE *restrict " stream ", char *restrict " buf ,
  60 .BI "            size_t "  size );
  61 .BI "void setlinebuf(FILE *" stream );
  62 .fi
  63 .PP
  64 .RS -4
  65 Feature Test Macro Requirements for glibc (see
  66 .BR feature_test_macros (7)):
  67 .RE
  68 .PP
  69 .BR setbuffer (),
  70 .BR setlinebuf ():
  71 .nf
  72     Since glibc 2.19:
  73         _DEFAULT_SOURCE
  74     Glibc 2.19 and earlier:
  75         _BSD_SOURCE
  76 .fi
  77 .SH DESCRIPTION
  78 The three types of buffering available are unbuffered, block buffered, and
  79 line buffered.
  80 When an output stream is unbuffered, information appears on
  81 the destination file or terminal as soon as written; when it is block
  82 buffered, many characters are saved up and written as a block; when it is
  83 line buffered, characters are saved up until a newline is output or input is
  84 read from any stream attached to a terminal device (typically \fIstdin\fP).
  85 The function
  86 .BR fflush (3)
  87 may be used to force the block out early.
  88 (See
  89 .BR fclose (3).)
  90 .PP
  91 Normally all files are block buffered.
  92 If a stream refers to a terminal (as
  93 .I stdout
  94 normally does), it is line buffered.
  95 The standard error stream
  96 .I stderr
  97 is always unbuffered by default.
  98 .PP
  99 The
 100 .BR setvbuf ()
 101 function may be used on any open stream to change its buffer.
 102 The
 103 .I mode
 104 argument must be one of the following three macros:
 105 .RS
 106 .TP
 107 .B _IONBF
 108 unbuffered
 109 .TP
 110 .B _IOLBF
 111 line buffered
 112 .TP
 113 .B _IOFBF
 114 fully buffered
 115 .RE
 116 .PP
 117 Except for unbuffered files, the
 118 .I buf
 119 argument should point to a buffer at least
 120 .I size
 121 bytes long; this buffer will be used instead of the current buffer.
 122 If the argument
 123 .I buf
 124 is NULL,
 125 only the mode is affected; a new buffer will be allocated on the next read
 126 or write operation.
 127 The
 128 .BR setvbuf ()
 129 function may be used only after opening a stream and before any other
 130 operations have been performed on it.
 131 .PP
 132 The other three calls are, in effect, simply aliases for calls to
 133 .BR setvbuf ().
 134 The
 135 .BR setbuf ()
 136 function is exactly equivalent to the call
 137 .PP
 138 .in +4n
 139 setvbuf(stream, buf, buf ? _IOFBF : _IONBF, BUFSIZ);
 140 .in
 141 .PP
 142 The
 143 .BR setbuffer ()
 144 function is the same, except that the size of the buffer is up to the
 145 caller, rather than being determined by the default
 146 .BR BUFSIZ .
 147 The
 148 .BR setlinebuf ()
 149 function is exactly equivalent to the call:
 150 .PP
 151 .in +4n
 152 setvbuf(stream, NULL, _IOLBF, 0);
 153 .in
 154 .SH RETURN VALUE
 155 The function
 156 .BR setvbuf ()
 157 returns 0 on success.
 158 It returns nonzero on failure
 159 .RI ( mode
 160 is invalid or the request cannot be honored).
 161 It may set
 162 .I errno
 163 on failure.
 164 .PP
 165 The other functions do not return a value.
 166 .SH ATTRIBUTES
 167 For an explanation of the terms used in this section, see
 168 .BR attributes (7).
 169 .ad l
 170 .nh
 171 .TS
 172 allbox;
 173 lbx lb lb
 174 l l l.
 175 Interface       Attribute       Value
 176 T{
 177 .BR setbuf (),
 178 .BR setbuffer (),
 179 .BR setlinebuf (),
 180 .BR setvbuf ()
 181 T}      Thread safety   MT-Safe
 182 .TE
 183 .hy
 184 .ad
 185 .sp 1
 186 .SH CONFORMING TO
 187 The
 188 .BR setbuf ()
 189 and
 190 .BR setvbuf ()
 191 functions conform to C89 and C99.
 192 .SH NOTES
 193 POSIX notes
 194 .\" https://www.austingroupbugs.net/view.php?id=397#c799
 195 .\" 0000397: setbuf and errno
 196 that the value of
 197 .I errno
 198 is unspecified after a call to
 199 .BR setbuf ()
 200 and further notes that, since the value of
 201 .I errno
 202 is not required to be unchanged after a successful call to
 203 .BR setbuf (),
 204 applications should instead use
 205 .BR setvbuf ()
 206 in order to detect errors.
 207 .SH BUGS
 208 .\" The
 209 .\" .BR setbuffer ()
 210 .\" and
 211 .\" .BR setlinebuf ()
 212 .\" functions are not portable to versions of BSD before 4.2BSD, and
 213 .\" are available under Linux since libc 4.5.21.
 214 .\" On 4.2BSD and 4.3BSD systems,
 215 .\" .BR setbuf ()
 216 .\" always uses a suboptimal buffer size and should be avoided.
 217 .\".PP
 218 You must make sure that the space that
 219 .I buf
 220 points to still exists by the time
 221 .I stream
 222 is closed, which also happens at program termination.
 223 For example, the following is invalid:
 224 .PP
 225 .EX
 226 #include <stdio.h>
 227
 228 int
 229 main(void)
 230 {
 231     char buf[BUFSIZ];
 232     setbuf(stdout, buf);
 233     printf("Hello, world!\en");
 234     return 0;
 235 }
 236 .EE
 237 .SH SEE ALSO
 238 .BR stdbuf (1),
 239 .BR fclose (3),
 240 .BR fflush (3),
 241 .BR fopen (3),
 242 .BR fread (3),
 243 .BR malloc (3),
 244 .BR printf (3),
 245 .BR puts (3)