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  2017-09-15 "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 "void setbuf(FILE *" stream ", char *" buf );
  56 .PP
  57 .BI "void setbuffer(FILE *" stream ", char *" buf ", size_t "  size );
  58 .PP
  59 .BI "void setlinebuf(FILE *" stream );
  60 .PP
  61 .BI "int setvbuf(FILE *" stream ", char *" buf ", int " mode \
  62 ", size_t " size );
  63 .fi
  64 .PP
  65 .in -4n
  66 Feature Test Macro Requirements for glibc (see
  67 .BR feature_test_macros (7)):
  68 .in
  69 .PP
  70 .BR setbuffer (),
  71 .BR setlinebuf ():
  72     Since glibc 2.19:
  73         _DEFAULT_SOURCE
  74     Glibc 2.19 and earlier:
  75         _BSD_SOURCE
  76 .SH DESCRIPTION
  77 The three types of buffering available are unbuffered, block buffered, and
  78 line buffered.
  79 When an output stream is unbuffered, information appears on
  80 the destination file or terminal as soon as written; when it is block
  81 buffered many characters are saved up and written as a block; when it is
  82 line buffered characters are saved up until a newline is output or input is
  83 read from any stream attached to a terminal device (typically \fIstdin\fP).
  84 The function
  85 .BR fflush (3)
  86 may be used to force the block out early.
  87 (See
  88 .BR fclose (3).)
  89 .PP
  90 Normally all files are block buffered.
  91 If a stream refers to a terminal (as
  92 .I stdout
  93 normally does), it is line buffered.
  94 The standard error stream
  95 .I stderr
  96 is always unbuffered by default.
  97 .PP
  98 The
  99 .BR setvbuf ()
 100 function may be used on any open stream to change its buffer.
 101 The
 102 .I mode
 103 argument must be one of the following three macros:
 104 .RS
 105 .TP
 106 .B _IONBF
 107 unbuffered
 108 .TP
 109 .B _IOLBF
 110 line buffered
 111 .TP
 112 .B _IOFBF
 113 fully buffered
 114 .RE
 115 .PP
 116 Except for unbuffered files, the
 117 .I buf
 118 argument should point to a buffer at least
 119 .I size
 120 bytes long; this buffer will be used instead of the current buffer.
 121 If the argument
 122 .I buf
 123 is NULL,
 124 only the mode is affected; a new buffer will be allocated on the next read
 125 or write operation.
 126 The
 127 .BR setvbuf ()
 128 function may be used only after opening a stream and before any other
 129 operations have been performed on it.
 130 .PP
 131 The other three calls are, in effect, simply aliases for calls to
 132 .BR setvbuf ().
 133 The
 134 .BR setbuf ()
 135 function is exactly equivalent to the call
 136 .PP
 137 .in +4n
 138 setvbuf(stream, buf, buf ? _IOFBF : _IONBF, BUFSIZ);
 139 .in
 140 .PP
 141 The
 142 .BR setbuffer ()
 143 function is the same, except that the size of the buffer is up to the
 144 caller, rather than being determined by the default
 145 .BR BUFSIZ .
 146 The
 147 .BR setlinebuf ()
 148 function is exactly equivalent to the call:
 149 .PP
 150 .in +4n
 151 setvbuf(stream, NULL, _IOLBF, 0);
 152 .in
 153 .SH RETURN VALUE
 154 The function
 155 .BR setvbuf ()
 156 returns 0 on success.
 157 It returns nonzero on failure
 158 .RI ( mode
 159 is invalid or the request cannot be honored).
 160 It may set
 161 .I errno
 162 on failure.
 163 .PP
 164 The other functions do not return a value.
 165 .SH ATTRIBUTES
 166 For an explanation of the terms used in this section, see
 167 .BR attributes (7).
 168 .TS
 169 allbox;
 170 lbw23 lb lb
 171 l l l.
 172 Interface       Attribute       Value
 173 T{
 174 .BR setbuf (),
 175 .BR setbuffer (),
 176 .br
 177 .BR setlinebuf (),
 178 .BR setvbuf ()
 179 T}      Thread safety   MT-Safe
 180 .TE
 181 .SH CONFORMING TO
 182 The
 183 .BR setbuf ()
 184 and
 185 .BR setvbuf ()
 186 functions conform to C89 and C99.
 187 .SH BUGS
 188 .\" The
 189 .\" .BR setbuffer ()
 190 .\" and
 191 .\" .BR setlinebuf ()
 192 .\" functions are not portable to versions of BSD before 4.2BSD, and
 193 .\" are available under Linux since libc 4.5.21.
 194 .\" On 4.2BSD and 4.3BSD systems,
 195 .\" .BR setbuf ()
 196 .\" always uses a suboptimal buffer size and should be avoided.
 197 .PP
 198 You must make sure that the space that
 199 .I buf
 200 points to still exists by the time
 201 .I stream
 202 is closed, which also happens at program termination.
 203 For example, the following is invalid:
 204 .PP
 205 .EX
 206 #include <stdio.h>
 207
 208 int
 209 main(void)
 210 {
 211     char buf[BUFSIZ];
 212     setbuf(stdin, buf);
 213     printf("Hello, world!\\n");
 214     return 0;
 215 }
 216 .EE
 217 .SH SEE ALSO
 218 .BR stdbuf (1),
 219 .BR fclose (3),
 220 .BR fflush (3),
 221 .BR fopen (3),
 222 .BR fread (3),
 223 .BR malloc (3),
 224 .BR printf (3),
 225 .BR puts (3)