'\" t
.\" Copyright 2022 Alejandro Colomar <alx@kernel.org>
.\" SPDX-License-Identifier: Linux-man-pages-copyleft
.\"
.TH scanf 3 2023-12-09 "Linux man-pages 6.7"
.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)