glenda.party
term% ls -F
term% cat index.txt
FSCANF(2)                     System Calls Manual                    FSCANF(2)



NAME
       fscanf, scanf, sscanf, vfscanf - scan formatted input

SYNOPSIS
       #include <u.h>
       #include <stdio.h>

       int fscanf(FILE *f, char *format, ...)

       int scanf(char *format, ... )

       int sscanf(char *s, char *format, ...)

       int vfscanf(FILE *stream, char *format, char *args)

DESCRIPTION
       Fscanf reads from the named input stream f (see fopen(2)) under control
       of the string pointed to by format that specifies the admissible  input
       sequences and how they are to be converted for assignment, using subse‐
       quent arguments as pointers to the objects to receive the converted in‐
       put.   If there are insufficient arguments for the format, the behavior
       is undefined.  If the format is exhausted while arguments  remain,  the
       excess arguments are evaluated (as always) but are otherwise ignored.

       Scanf and sscanf are the same, but they read from stdin and the charac‐
       ter string s, respectively.  Vfscanf is like scanf, except the args ar‐
       gument  is  a pointer to an argument in an argument list of the calling
       function and the effect is as if the calling function's  argument  list
       from that point on is passed to the scanf routines.

       The  format  is composed of zero or more directives: one or more white-
       space characters; an ordinary character (not %); or a conversion speci‐
       fication.  Each conversion specification is introduced by the character
       %.  After the %, the following appear in sequence:

              An optional assignment-suppressing character *.

              An optional decimal integer that  specifies  the  maximum  field
              width.

              An optional h, l (ell) or L indicating the size of the receiving
              object.  The conversion specifiers d, i, and n shall be preceded
              by  h if the corresponding argument is a pointer to short rather
              than a pointer to int, or by l if it is a pointer to long.  Sim‐
              ilarly,  the conversion specifiers o, u, and x shall be preceded
              by h if the corresponding argument  is  a  pointer  to  unsigned
              short  rather  than  a  pointer  to unsigned, or by l if it is a
              pointer to unsigned long.  Finally, the conversion specifiers e,
              f, and g shall be preceded by l if the corresponding argument is
              a pointer to double rather than a pointer to float, or by  L  if
              it  is  a pointer to long double.  If an h, l, or L appears with
              any other conversion specifier, the behavior is undefined.

              A character that specifies the type of conversion to be applied.
              The valid conversion specifiers are described below.

       Fscanf  executes  each directive of the format in turn.  If a directive
       fails, as detailed below, fscanf returns.  Failures  are  described  as
       input  failures (due to the unavailability of input), or matching fail‐
       ures (due to inappropriate input).

       A directive composed of white space is executed by reading input up  to
       the first non-white-space character (which remains unread), or until no
       more characters can be read.

       A directive that is an ordinary character is executed  by  reading  the
       next  character from the stream.  If if differs from the one comprising
       the directive, the directive fails, and the  differing  and  subsequent
       characters remain unread.

       A  directive that is a conversion specification defines a set of match‐
       ing input sequences, as described below for each specifier.  A  conver‐
       sion specification is executed in the following steps:

       Input  white-space  characters  (as specified by isspace, see ctype(2))
       are skipped, unless the specification includes a [, c, or n specifier.

       An input item is read from the stream,  unless  the  specification  in‐
       cludes  an  n  specifier.   An input item is defined as the longest se‐
       quence of input characters (up to any specified  maximum  field  width)
       which  is  an  initial  subsequence  of a matching sequence.  The first
       character, if any, after the input item remains unread.  If the  length
       of  the  input item is zero, the execution of the directive fails: this
       condition is a matching failure, unless an error prevented  input  from
       the stream, in which case it is an input failure.

       Except in the case of a % specifier, the input item (or, in the case of
       a %n directive, the count of input characters) is converted to  a  type
       appropriate  to  the  conversion specifier.  If the input item is not a
       matching sequence, the execution of the directive fails: this condition
       is  a matching failure.  Unless assignment suppression was indicated by
       a *, the result of the conversion is placed in the object pointed to by
       the  first  argument following the format argument that has not already
       received a conversion result.  If this object does not have  an  appro‐
       priate  type,  or if the result of the conversion cannot be represented
       in the space provided, the behavior is undefined.

       The following conversion specifiers are valid:

       d     Matches an optionally signed decimal integer, whose format is the
             same  as  expected  for  the  subject sequence of the strtol (see
             atof(2)) function with 10 for the base argument.  The correspond‐
             ing argument shall be a pointer to int.

       i     Matches an optionally signed decimal integer, whose format is the
             same as expected for the subject sequence of the strtol  function
             with  0  for the base argument.  The corresponding argument shall
             be a pointer to int.

       o     Matches an optionally signed octal integer, whose format  is  the
             same  as  expected  for  the subject sequence of the strtoul (see
             atof(2)) function with 8 for the base argument.  The  correspond‐
             ing argument shall be a pointer to unsigned int.

       u     Matches an optionally signed decimal integer, whose format is the
             same as expected for the subject sequence of the strtoul function
             with  10 for the base argument.  The corresponding argument shall
             be a pointer to unsigned int.

       x     Matches an optionally signed hexadecimal integer, whose format is
             the  same  as  expected  for  the subject sequence of the strtoul
             function with 16 for the base argument.  The corresponding  argu‐
             ment shall be a pointer to unsigned int.

       e,f,g Matches  an optionally signed floating-point number, whose format
             is the same as expected for the subject string of the strtod (see
             atof(2)) function.  The corresponding argument shall be a pointer
             to float.

       s     Matches a sequence of  non-white-space  characters.   The  corre‐
             sponding  argument shall be a pointer to the initial character of
             an array large enough to accept the sequence  and  a  terminating
             NUL (0) character, which will be added automatically.

       [     Matches  a nonempty sequence of characters from a set of expected
             characters (the scanset).  The corresponding argument shall be  a
             pointer  to the initial character of an array large enough to ac‐
             cept the sequence and a terminating NUL character, which will  be
             added  automatically.  The conversion specifier includes all sub‐
             sequent characters in the format string, up to and including  the
             matching  right  brace  (]).  The characters between the brackets
             (the scanlist) comprise the scanset, unless the  character  after
             the  left  bracket is a circumflex (^), in which case the scanset
             contains all characters that do not appear in  the  scanlist  be‐
             tween  the  circumflex and the right bracket.  As a special case,
             if the conversion specifier begins with  []  or  [^],  the  right
             bracket  character  is in the scanlist and the next right bracket
             character is the matching right bracket that ends the  specifica‐
             tion.   If a - character is in the scanlist and is not the first,
             nor the second where the first character is a  ^,  nor  the  last
             character, the behavior is implementation-defined (in Plan 9: the
             scanlist includes all characters in the ASCII (sic) range between
             the two characters on either side of the -).

       c     Matches  a  sequence of characters of the number specified by the
             field width (1 if no field width is present  in  the  directive).
             The  corresponding  argument  shall  be  a pointer to the initial
             character of an array large enough to accept  the  sequence.   No
             NUL character is added.

       P     Matches  an implementation-defined set of sequences, which should
             be the same as the set of sequences that may be produced  by  the
             %P  conversion of the fprintf(2) function (in Plan 9, a hexadeci‐
             mal number).  The corresponding argument shall be a pointer to  a
             pointer  to void.  The interpretation of the input item is imple‐
             mentation defined; however, for any input item other than a value
             converted earlier during the same program execution, the behavior
             of the %P conversion is undefined.

       n     No input is consumed.  The  corresponding  argument  shall  be  a
             pointer to integer into which is written the number of characters
             read from the input stream so far by this call to fscanf.  Execu‐
             tion  of  a  %n directive does not increment the assignment count
             returned at the completion of fscanf.

       %     Matches a single %; no conversion or assignment occurs.  The com‐
             plete conversion specification shall be %%.

       If a conversion specification is invalid, the behavior is undefined.

       The  conversion  specifiers  E,  G, and X are also valid and behave the
       same as, respectively, e, g, and x.

       If end-of-file is encountered during input, conversion  is  terminated.
       If end-of-file occurs before any characters matching the current direc‐
       tive have been read (other than leading white space, where  permitted),
       execution  of  the  current directive terminates with an input failure;
       otherwise, unless execution of the current directive is terminated with
       a  matching  failure,  execution of the following directive (if any) is
       terminated with an input failure.

       If conversion terminates on a conflicting input character, the  offend‐
       ing input character is left unread in the input stream.  Trailing white
       space (including newline characters) is left unread unless matched by a
       directive.   The  success of literal matches and suppressed assignments
       is not directly determinable other than via the %n directive.

       The return value from fscanf is the number  of  input  items  assigned,
       which  can be fewer than provided for, or even zero, in the event of an
       early matching failure.  However, if an input failure occurs before any
       conversion, EOF is returned.

SOURCE
       /sys/src/libstdio

SEE ALSO
       fopen(2), fgetc(2)

BUGS
       Does not know about UTF.



                                                                     FSCANF(2)