| .\" Copyright (c) 1980, 1991 Regents of the University of California. |
| .\" All rights reserved. |
| .\" |
| .\" This code is derived from software contributed to Berkeley by |
| .\" the American National Standards Committee X3, on Information |
| .\" Processing Systems. |
| .\" |
| .\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) |
| .\" Redistribution and use in source and binary forms, with or without |
| .\" modification, are permitted provided that the following conditions |
| .\" are met: |
| .\" 1. Redistributions of source code must retain the above copyright |
| .\" notice, this list of conditions and the following disclaimer. |
| .\" 2. Redistributions in binary form must reproduce the above copyright |
| .\" notice, this list of conditions and the following disclaimer in the |
| .\" documentation and/or other materials provided with the distribution. |
| .\" 3. All advertising materials mentioning features or use of this software |
| .\" must display the following acknowledgement: |
| .\" This product includes software developed by the University of |
| .\" California, Berkeley and its contributors. |
| .\" 4. Neither the name of the University nor the names of its contributors |
| .\" may be used to endorse or promote products derived from this software |
| .\" without specific prior written permission. |
| .\" |
| .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND |
| .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
| .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
| .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE |
| .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL |
| .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS |
| .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) |
| .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT |
| .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY |
| .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF |
| .\" SUCH DAMAGE. |
| .\" %%%LICENSE_END |
| .\" |
| .\" @(#)setbuf.3 6.10 (Berkeley) 6/29/91 |
| .\" |
| .\" Converted for Linux, Mon Nov 29 14:55:24 1993, faith@cs.unc.edu |
| .\" Added section to BUGS, Sun Mar 12 22:28:33 MET 1995, |
| .\" Thomas.Koenig@ciw.uni-karlsruhe.de |
| .\" Correction, Sun, 11 Apr 1999 15:55:18, |
| .\" Martin Vicente <martin@netadmin.dgac.fr> |
| .\" Correction, 2000-03-03, Andreas Jaeger <aj@suse.de> |
| .\" Added return value for setvbuf, aeb, |
| .\" |
| .TH SETBUF 3 2017-09-15 "Linux" "Linux Programmer's Manual" |
| .SH NAME |
| setbuf, setbuffer, setlinebuf, setvbuf \- stream buffering operations |
| .SH SYNOPSIS |
| .nf |
| .B #include <stdio.h> |
| .PP |
| .BI "void setbuf(FILE *" stream ", char *" buf ); |
| .PP |
| .BI "void setbuffer(FILE *" stream ", char *" buf ", size_t " size ); |
| .PP |
| .BI "void setlinebuf(FILE *" stream ); |
| .PP |
| .BI "int setvbuf(FILE *" stream ", char *" buf ", int " mode \ |
| ", size_t " size ); |
| .fi |
| .PP |
| .in -4n |
| Feature Test Macro Requirements for glibc (see |
| .BR feature_test_macros (7)): |
| .in |
| .PP |
| .BR setbuffer (), |
| .BR setlinebuf (): |
| Since glibc 2.19: |
| _DEFAULT_SOURCE |
| Glibc 2.19 and earlier: |
| _BSD_SOURCE |
| .SH DESCRIPTION |
| The three types of buffering available are unbuffered, block buffered, and |
| line buffered. |
| When an output stream is unbuffered, information appears on |
| the destination file or terminal as soon as written; when it is block |
| buffered many characters are saved up and written as a block; when it is |
| line buffered characters are saved up until a newline is output or input is |
| read from any stream attached to a terminal device (typically \fIstdin\fP). |
| The function |
| .BR fflush (3) |
| may be used to force the block out early. |
| (See |
| .BR fclose (3).) |
| .PP |
| Normally all files are block buffered. |
| If a stream refers to a terminal (as |
| .I stdout |
| normally does), it is line buffered. |
| The standard error stream |
| .I stderr |
| is always unbuffered by default. |
| .PP |
| The |
| .BR setvbuf () |
| function may be used on any open stream to change its buffer. |
| The |
| .I mode |
| argument must be one of the following three macros: |
| .RS |
| .TP |
| .B _IONBF |
| unbuffered |
| .TP |
| .B _IOLBF |
| line buffered |
| .TP |
| .B _IOFBF |
| fully buffered |
| .RE |
| .PP |
| Except for unbuffered files, the |
| .I buf |
| argument should point to a buffer at least |
| .I size |
| bytes long; this buffer will be used instead of the current buffer. |
| If the argument |
| .I buf |
| is NULL, |
| only the mode is affected; a new buffer will be allocated on the next read |
| or write operation. |
| The |
| .BR setvbuf () |
| function may be used only after opening a stream and before any other |
| operations have been performed on it. |
| .PP |
| The other three calls are, in effect, simply aliases for calls to |
| .BR setvbuf (). |
| The |
| .BR setbuf () |
| function is exactly equivalent to the call |
| .PP |
| .in +4n |
| setvbuf(stream, buf, buf ? _IOFBF : _IONBF, BUFSIZ); |
| .in |
| .PP |
| The |
| .BR setbuffer () |
| function is the same, except that the size of the buffer is up to the |
| caller, rather than being determined by the default |
| .BR BUFSIZ . |
| The |
| .BR setlinebuf () |
| function is exactly equivalent to the call: |
| .PP |
| .in +4n |
| setvbuf(stream, NULL, _IOLBF, 0); |
| .in |
| .SH RETURN VALUE |
| The function |
| .BR setvbuf () |
| returns 0 on success. |
| It returns nonzero on failure |
| .RI ( mode |
| is invalid or the request cannot be honored). |
| It may set |
| .I errno |
| on failure. |
| .PP |
| The other functions do not return a value. |
| .SH ATTRIBUTES |
| For an explanation of the terms used in this section, see |
| .BR attributes (7). |
| .TS |
| allbox; |
| lbw23 lb lb |
| l l l. |
| Interface Attribute Value |
| T{ |
| .BR setbuf (), |
| .BR setbuffer (), |
| .br |
| .BR setlinebuf (), |
| .BR setvbuf () |
| T} Thread safety MT-Safe |
| .TE |
| .SH CONFORMING TO |
| The |
| .BR setbuf () |
| and |
| .BR setvbuf () |
| functions conform to C89 and C99. |
| .SH BUGS |
| .\" The |
| .\" .BR setbuffer () |
| .\" and |
| .\" .BR setlinebuf () |
| .\" functions are not portable to versions of BSD before 4.2BSD, and |
| .\" are available under Linux since libc 4.5.21. |
| .\" On 4.2BSD and 4.3BSD systems, |
| .\" .BR setbuf () |
| .\" always uses a suboptimal buffer size and should be avoided. |
| .PP |
| You must make sure that the space that |
| .I buf |
| points to still exists by the time |
| .I stream |
| is closed, which also happens at program termination. |
| For example, the following is invalid: |
| .PP |
| .EX |
| #include <stdio.h> |
| |
| int |
| main(void) |
| { |
| char buf[BUFSIZ]; |
| setbuf(stdin, buf); |
| printf("Hello, world!\\n"); |
| return 0; |
| } |
| .EE |
| .SH SEE ALSO |
| .BR stdbuf (1), |
| .BR fclose (3), |
| .BR fflush (3), |
| .BR fopen (3), |
| .BR fread (3), |
| .BR malloc (3), |
| .BR printf (3), |
| .BR puts (3) |