Merging upstream version 6.8.

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

1 files changed, 159 insertions, 0 deletions

diff --git a/man/man3/scanf.3 b/man/man3/scanf.3
new file mode 100644
index 0000000..3855e77
--- /dev/null
+++ b/man/man3/scanf.3
@@ -0,0 +1,159 @@
+'\" t
+.\" Copyright 2022 Alejandro Colomar <alx@kernel.org>
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH scanf 3 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+scanf, fscanf, vscanf, vfscanf \- input FILE format conversion
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <stdio.h>
+.P
+.BI "int scanf(const char *restrict " format ", ...);"
+.BI "int fscanf(FILE *restrict " stream ,
+.BI "           const char *restrict " format ", ...);"
+.P
+.B #include <stdarg.h>
+.P
+.BI "int vscanf(const char *restrict " format ", va_list " ap );
+.BI "int vfscanf(FILE *restrict " stream ,
+.BI "           const char *restrict " format ", va_list " ap );
+.fi
+.P
+.RS -4
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.RE
+.P
+.BR vscanf (),
+.BR vfscanf ():
+.nf
+    _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L
+.fi
+.SH DESCRIPTION
+The
+.BR scanf ()
+family of functions scans formatted input like
+.BR sscanf (3),
+but read from a
+.IR FILE .
+It is very difficult to use these functions correctly,
+and it is preferable to read entire lines with
+.BR fgets (3)
+or
+.BR getline (3)
+and parse them later with
+.BR sscanf (3)
+or more specialized functions such as
+.BR strtol (3).
+.P
+The
+.BR scanf ()
+function reads input from the standard input stream
+.I stdin
+and
+.BR fscanf ()
+reads input from the stream pointer
+.IR stream .
+.P
+The
+.BR vfscanf ()
+function is analogous to
+.BR vfprintf (3)
+and reads input from the stream pointer
+.I stream
+using a variable argument list of pointers (see
+.BR stdarg (3).
+The
+.BR vscanf ()
+function is analogous to
+.BR vprintf (3)
+and reads from the standard input.
+.SH RETURN VALUE
+On success, these functions return the number of input items
+successfully matched and assigned;
+this can be fewer than provided for,
+or even zero, in the event of an early matching failure.
+.P
+The value
+.B EOF
+is returned if the end of input is reached before either the first
+successful conversion or a matching failure occurs.
+.B EOF
+is also returned if a read error occurs,
+in which case the error indicator for the stream (see
+.BR ferror (3))
+is set, and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+.TP
+.B EAGAIN
+The file descriptor underlying
+.I stream
+is marked nonblocking, and the read operation would block.
+.TP
+.B EBADF
+The file descriptor underlying
+.I stream
+is invalid, or not open for reading.
+.TP
+.B EILSEQ
+Input byte sequence does not form a valid character.
+.TP
+.B EINTR
+The read operation was interrupted by a signal; see
+.BR signal (7).
+.TP
+.B EINVAL
+Not enough arguments; or
+.I format
+is NULL.
+.TP
+.B ENOMEM
+Out of memory.
+.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 scanf (),
+.BR fscanf (),
+.BR vscanf (),
+.BR vfscanf ()
+T}	Thread safety	MT-Safe locale
+.TE
+.SH STANDARDS
+C11, POSIX.1-2008.
+.SH HISTORY
+C99, POSIX.1-2001.
+.SH CAVEATS
+These functions make it difficult to
+distinguish newlines from other white space,
+This is especially problematic with line-buffered input,
+like the standard input stream.
+.P
+These functions can't report errors after the last
+non-suppressed conversion specification.
+.SH BUGS
+It is impossible to accurately know
+how many characters these functions have consumed from the input stream,
+since they only report the number of successful conversions.
+For example,
+if the input is "123\en\ a",
+.I scanf(\[dq]%d\ %d\[dq], &a, &b)
+will consume the digits, the newline, and the space, but not the letter a.
+This makes it difficult to recover from invalid input.
+.SH SEE ALSO
+.BR fgets (3),
+.BR getline (3),
+.BR sscanf (3)