Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 227 insertions, 0 deletions

diff --git a/man/man3/setbuf.3 b/man/man3/setbuf.3
new file mode 100644
index 0000000..38400e4
--- /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 2024-05-02 "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)