diff options
Diffstat (limited to 'man/man3/setbuf.3')
| -rw-r--r-- | man/man3/setbuf.3 | 227 |
1 files changed, 227 insertions, 0 deletions
diff --git a/man/man3/setbuf.3 b/man/man3/setbuf.3 new file mode 100644 index 000000000..8604d4754 --- /dev/null +++ b/man/man3/setbuf.3 @@ -0,0 +1,227 @@ +'\" t +.\" 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. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" @(#)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 (date) "Linux man-pages (unreleased)" +.SH NAME +setbuf, setbuffer, setlinebuf, setvbuf \- stream buffering operations +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <stdio.h> +.P +.BI "int setvbuf(FILE *restrict " stream ", char " buf "[restrict ." size ], +.BI " int " mode ", size_t " size ); +.P +.BI "void setbuf(FILE *restrict " stream ", char *restrict " buf ); +.BI "void setbuffer(FILE *restrict " stream ", char " buf "[restrict ." size ], +.BI " size_t " size ); +.BI "void setlinebuf(FILE *" stream ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR setbuffer (), +.BR setlinebuf (): +.nf + Since glibc 2.19: + _DEFAULT_SOURCE + glibc 2.19 and earlier: + _BSD_SOURCE +.fi +.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).) +.P +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. +.P +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 +.P +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. +.P +The other three calls are, in effect, simply aliases for calls to +.BR setvbuf (). +The +.BR setbuf () +function is exactly equivalent to the call +.P +.in +4n +setvbuf(stream, buf, buf ? _IOFBF : _IONBF, BUFSIZ); +.in +.P +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: +.P +.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. +.P +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; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR setbuf (), +.BR setbuffer (), +.BR setlinebuf (), +.BR setvbuf () +T} Thread safety MT-Safe +.TE +.SH STANDARDS +.TP +.BR setbuf () +.TQ +.BR setvbuf () +C11, POSIX.1-2008. +.SH HISTORY +.TP +.BR setbuf () +.TQ +.BR setvbuf () +C89, POSIX.1-2001. +.SH CAVEATS +POSIX notes +.\" https://www.austingroupbugs.net/view.php?id=397#c799 +.\" 0000397: setbuf and errno +that the value of +.I errno +is unspecified after a call to +.BR setbuf () +and further notes that, since the value of +.I errno +is not required to be unchanged after a successful call to +.BR setbuf (), +applications should instead use +.BR setvbuf () +in order to detect errors. +.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. +.\".P +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: +.P +.\" SRC BEGIN (setbuf.c) +.EX +#include <stdio.h> +\& +int +main(void) +{ + char buf[BUFSIZ]; +\& + setbuf(stdout, buf); + printf("Hello, world!\en"); + return 0; +} +.EE +.\" SRC END +.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) |