1.\" $OpenBSD: setvbuf.3,v 1.4 2014/11/26 18:16:32 schwarze Exp $ 2.\" 3.\" Copyright (c) 1980, 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" This code is derived from software contributed to Berkeley by 7.\" the American National Standards Committee X3, on Information 8.\" Processing Systems. 9.\" 10.\" Redistribution and use in source and binary forms, with or without 11.\" modification, are permitted provided that the following conditions 12.\" are met: 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in the 17.\" documentation and/or other materials provided with the distribution. 18.\" 3. Neither the name of the University nor the names of its contributors 19.\" may be used to endorse or promote products derived from this software 20.\" without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.Dd $Mdocdate: November 26 2014 $ 35.Dt SETVBUF 3 36.Os 37.Sh NAME 38.Nm setvbuf 39.Nd stream buffering operations 40.Sh SYNOPSIS 41.In stdio.h 42.Ft int 43.Fn setvbuf "FILE *stream" "char *buf" "int mode" "size_t size" 44.Sh DESCRIPTION 45The three types of stream buffering available are unbuffered, block buffered, 46and line buffered. 47When an output stream is unbuffered, information appears on the 48destination file or terminal as soon as written; 49when it is block buffered, many characters are saved up and written as a block; 50when line buffered, characters are saved up until a newline 51.Pq Ql \en 52is output or input is read from any stream attached to a terminal device 53(typically 54.Em stdin ) . 55.Pp 56The 57.Xr fflush 3 58function may be used to force the block out early. 59.Pp 60Normally, all files are block buffered. 61When the first I/O operation occurs on a file, 62.Xr malloc 3 63is called, 64and an optimally sized buffer is obtained. 65If a stream refers to a terminal 66(as 67.Em stdout 68normally does), it is line buffered. 69.Pp 70The standard error stream 71.Em stderr 72is initially unbuffered. 73.Pp 74The 75.Fn setvbuf 76function may be used to alter the buffering behavior of a stream. 77The 78.Fa mode 79parameter must be one of the following three macros: 80.Pp 81.Bl -tag -width _IOFBF -offset indent -compact 82.It Dv _IONBF 83unbuffered 84.It Dv _IOLBF 85line buffered 86.It Dv _IOFBF 87fully buffered 88.El 89.Pp 90The 91.Fa size 92parameter may be given as zero 93to obtain deferred optimal-size buffer allocation as usual. 94If it is not zero, then except for unbuffered files, the 95.Fa buf 96argument should point to a buffer at least 97.Fa size 98bytes long; 99this buffer will be used instead of the current buffer. 100(If the 101.Fa size 102argument 103is not zero but 104.Fa buf 105is 106.Dv NULL , 107a buffer of the given size will be allocated immediately, 108and released on close. 109This is an extension to ANSI C; 110portable code should use a size of 0 with any 111.Dv NULL 112buffer.) 113.Pp 114The 115.Fn setvbuf 116function may be used at any time, 117but may have peculiar side effects 118(such as discarding input or flushing output) 119if the stream is 120.Dq active . 121Portable applications should call it only once on any given stream, 122and before any I/O is performed. 123.Sh RETURN VALUES 124Upon successful completion, a value of 0 is returned. 125If 126.Fa mode 127is invalid or if the request cannot be honored, a non-zero value is returned, 128possibly setting 129.Va errno 130to indicate the error. 131The stream is not modified in the error case. 132.Sh ERRORS 133The 134.Fn setvbuf 135function will fail if: 136.Bl -tag -width Er 137.It Bq Er EBADF 138The 139.Fa stream 140specified is not associated with a valid file descriptor. 141.El 142.Sh SEE ALSO 143.Xr fclose 3 , 144.Xr fopen 3 , 145.Xr fread 3 , 146.Xr malloc 3 , 147.Xr printf 3 , 148.Xr puts 3 , 149.Xr setbuf 3 150.Sh STANDARDS 151The 152.Fn setvbuf 153function conforms to 154.St -isoC-99 . 155.Sh HISTORY 156The 157.Fn setvbuf 158function first appeared in 159.Bx 4.4 . 160