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
       input.   If there are insufficient arguments for the format, the behav‐
       ior 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
       argument 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
       includes an n specifier.  An input  item  is  defined  as  the  longest
       sequence  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
             accept  the  sequence and a terminating NUL character, which will
             be added automatically.  The conversion  specifier  includes  all
             subsequent  characters  in the format string, up to and including
             the matching right brace (]).  The characters between the  brack‐
             ets  (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 scan‐
             list between 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
             specification.  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)