man3/scanf.3

   1 '\" t
   2 .\" Copyright 2022 Alejandro Colomar <alx@kernel.org>
   3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   4 .\"
   5 .TH scanf 3 (date) "Linux man-pages (unreleased)"
   6 .SH NAME
   7 scanf, fscanf, vscanf, vfscanf \- input FILE format conversion
   8 .SH LIBRARY
   9 Standard C library
  10 .RI ( libc ", " \-lc )
  11 .SH SYNOPSIS
  12 .nf
  13 .B #include <stdio.h>
  14 .PP
  15 .BI "int scanf(const char *restrict " format ", ...);"
  16 .BI "int fscanf(FILE *restrict " stream ,
  17 .BI "           const char *restrict " format ", ...);"
  18 .PP
  19 .B #include <stdarg.h>
  20 .PP
  21 .BI "int vscanf(const char *restrict " format ", va_list " ap );
  22 .BI "int vfscanf(FILE *restrict " stream ,
  23 .BI "           const char *restrict " format ", va_list " ap );
  24 .fi
  25 .PP
  26 .RS -4
  27 Feature Test Macro Requirements for glibc (see
  28 .BR feature_test_macros (7)):
  29 .RE
  30 .PP
  31 .BR vscanf (),
  32 .BR vfscanf ():
  33 .nf
  34     _ISOC99_SOURCE || _POSIX_C_SOURCE >= 200112L
  35 .fi
  36 .SH DESCRIPTION
  37 The
  38 .BR scanf ()
  39 family of functions scans input like
  40 .BR sscanf (3),
  41 but read from a
  42 .IR FILE .
  43 It is very difficult to use these functions correctly,
  44 and it is preferable to read entire lines with
  45 .BR fgets (3)
  46 or
  47 .BR getline (3)
  48 and parse them later with
  49 .BR sscanf (3)
  50 or more specialized functions such as
  51 .BR strtol (3).
  52 .PP
  53 The
  54 .BR scanf ()
  55 function reads input from the standard input stream
  56 .I stdin
  57 and
  58 .BR fscanf ()
  59 reads input from the stream pointer
  60 .IR stream .
  61 .PP
  62 The
  63 .BR vfscanf ()
  64 function is analogous to
  65 .BR vfprintf (3)
  66 and reads input from the stream pointer
  67 .I stream
  68 using a variable argument list of pointers (see
  69 .BR stdarg (3).
  70 The
  71 .BR vscanf ()
  72 function is analogous to
  73 .BR vprintf (3)
  74 and reads from the standard input.
  75 .SH RETURN VALUE
  76 On success, these functions return the number of input items
  77 successfully matched and assigned;
  78 this can be fewer than provided for,
  79 or even zero, in the event of an early matching failure.
  80 .PP
  81 The value
  82 .B EOF
  83 is returned if the end of input is reached before either the first
  84 successful conversion or a matching failure occurs.
  85 .B EOF
  86 is also returned if a read error occurs,
  87 in which case the error indicator for the stream (see
  88 .BR ferror (3))
  89 is set, and
  90 .I errno
  91 is set to indicate the error.
  92 .SH ERRORS
  93 .TP
  94 .B EAGAIN
  95 The file descriptor underlying
  96 .I stream
  97 is marked nonblocking, and the read operation would block.
  98 .TP
  99 .B EBADF
 100 The file descriptor underlying
 101 .I stream
 102 is invalid, or not open for reading.
 103 .TP
 104 .B EILSEQ
 105 Input byte sequence does not form a valid character.
 106 .TP
 107 .B EINTR
 108 The read operation was interrupted by a signal; see
 109 .BR signal (7).
 110 .TP
 111 .B EINVAL
 112 Not enough arguments; or
 113 .I format
 114 is NULL.
 115 .TP
 116 .B ENOMEM
 117 Out of memory.
 118 .SH ATTRIBUTES
 119 For an explanation of the terms used in this section, see
 120 .BR attributes (7).
 121 .ad l
 122 .nh
 123 .TS
 124 allbox;
 125 lbx lb lb
 126 l l l.
 127 Interface       Attribute       Value
 128 T{
 129 .BR scanf (),
 130 .BR fscanf (),
 131 .BR vscanf (),
 132 .BR vfscanf ()
 133 T}      Thread safety   MT-Safe locale
 134 .TE
 135 .hy
 136 .ad
 137 .sp 1
 138 .SH STANDARDS
 139 C11, POSIX.1-2008.
 140 .SH HISTORY
 141 C99, POSIX.1-2001.
 142 .SH SEE ALSO
 143 .BR fgets (3),
 144 .BR getline (3),
 145 .BR sscanf (3)