From 399644e47874bff147afb19c89228901ac39340e Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Mon, 15 Apr 2024 21:40:15 +0200 Subject: Adding upstream version 6.05.01. Signed-off-by: Daniel Baumann --- man3/setbuf.3 | 228 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 228 insertions(+) create mode 100644 man3/setbuf.3 (limited to 'man3/setbuf.3') diff --git a/man3/setbuf.3 b/man3/setbuf.3 new file mode 100644 index 0000000..ad998c3 --- /dev/null +++ b/man3/setbuf.3 @@ -0,0 +1,228 @@ +'\" 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 +.\" Correction, 2000-03-03, Andreas Jaeger +.\" Added return value for setvbuf, aeb, +.\" +.TH setbuf 3 2023-07-20 "Linux man-pages 6.05.01" +.SH NAME +setbuf, setbuffer, setlinebuf, setvbuf \- stream buffering operations +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int setvbuf(FILE *restrict " stream ", char " buf "[restrict ." size ], +.BI " int " mode ", size_t " size ); +.PP +.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 +.PP +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.PP +.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).) +.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; +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 +.sp 1 +.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. +.\".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 +.\" [[invalid]] SRC BEGIN (setbuf.c) +.EX +#include +\& +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) -- cgit v1.2.3