scanf(3) — Linux manual page

NAME | LIBRARY | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | ATTRIBUTES | STANDARDS | HISTORY | CAVEATS | BUGS | SEE ALSO | COLOPHON

scanf(3)                Library Functions Manual                scanf(3)

NAME         top

       scanf, fscanf, vscanf, vfscanf - input FILE format conversion

LIBRARY         top

       Standard C library (libc, -lc)

SYNOPSIS         top

       #include <stdio.h>

       int scanf(const char *restrict format, ...);
       int fscanf(FILE *restrict stream,
                  const char *restrict format, ...);

       #include <stdarg.h>

       int vscanf(const char *restrict format, va_list ap);
       int vfscanf(FILE *restrict stream,
                  const char *restrict format, va_list ap);

   Feature Test Macro Requirements for glibc (see
   feature_test_macros(7)):

       vscanf(), vfscanf():
           _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L

DESCRIPTION         top

       The scanf() family of functions scans formatted input like
       sscanf(3), but read from a FILE.  It is very difficult to use
       these functions correctly, and it is preferable to read entire
       lines with fgets(3) or getline(3) and parse them later with
       sscanf(3) or more specialized functions such as strtol(3).

       The scanf() function reads input from the standard input stream
       stdin and fscanf() reads input from the stream pointer stream.

       The vfscanf() function is analogous to vfprintf(3) and reads
       input from the stream pointer stream using a variable argument
       list of pointers (see stdarg(3).  The vscanf() function is
       analogous to vprintf(3) and reads from the standard input.

RETURN VALUE         top

       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.

       The value EOF is returned if the end of input is reached before
       either the first successful conversion or a matching failure
       occurs.  EOF is also returned if a read error occurs, in which
       case the error indicator for the stream (see ferror(3)) is set,
       and errno is set to indicate the error.

ERRORS         top

       EAGAIN The file descriptor underlying stream is marked
              nonblocking, and the read operation would block.

       EBADF  The file descriptor underlying stream is invalid, or not
              open for reading.

       EILSEQ Input byte sequence does not form a valid character.

       EINTR  The read operation was interrupted by a signal; see
              signal(7).

       EINVAL Not enough arguments; or format is NULL.

       ENOMEM Out of memory.

ATTRIBUTES         top

       For an explanation of the terms used in this section, see
       attributes(7).
       ┌──────────────────────────────┬───────────────┬────────────────┐
       │ Interface                    Attribute     Value          │
       ├──────────────────────────────┼───────────────┼────────────────┤
       │ scanf(), fscanf(), vscanf(), │ Thread safety │ MT-Safe locale │
       │ vfscanf()                    │               │                │
       └──────────────────────────────┴───────────────┴────────────────┘

STANDARDS         top

       C11, POSIX.1-2008.

HISTORY         top

       C99, POSIX.1-2001.

CAVEATS         top

       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.

       These functions can't report errors after the last non-suppressed
       conversion specification.

BUGS         top

       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\n a", scanf("%d %d", &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.

SEE ALSO         top

       fgets(3), getline(3), sscanf(3)

COLOPHON         top

       This page is part of the man-pages (Linux kernel and C library
       user-space interface documentation) project.  Information about
       the project can be found at 
       ⟨https://www.kernel.org/doc/man-pages/⟩.  If you have a bug report
       for this manual page, see
       ⟨https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/CONTRIBUTING⟩.
       This page was obtained from the tarball man-pages-6.9.1.tar.gz
       fetched from
       ⟨https://mirrors.edge.kernel.org/pub/linux/docs/man-pages/⟩ on
       2024-06-26.  If you discover any rendering problems in this HTML
       version of the page, or you believe there is a better or more up-
       to-date source for the page, or you have corrections or
       improvements to the information in this COLOPHON (which is not
       part of the original manual page), send a mail to
       man-pages@man7.org

Linux man-pages 6.9.1          2024-06-15                       scanf(3)

Pages that refer to this page: curs_scanw(3x)fgetc(3)FILE(3type)getline(3)gets(3)intmax_t(3type)intN_t(3type)intptr_t(3type)lber-decode(3)pmfstring(3)printf(3)ptrdiff_t(3type)puts(3)size_t(3type)stdarg(3)stdio(3)strptime(3)void(3type)proc_pid_stat(5)locale(7)system_data_types(7)