FSCANF(2)                                               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 speci-
          fies the admissible input sequences and how they are to be
          converted for assignment, using subsequent 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 argu-
          ments 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 character 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 specification.  Each conversion specifica-
          tion 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.  Similarly, the con-
               version specifiers o, u, and x shall be preceded by h

     Page 1                       Plan 9             (printed 3/19/24)

     FSCANF(2)                                               FSCANF(2)

               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.  Fail-
          ures are described as input failures (due to the unavail-
          ability of input), or matching failures (due to inappropri-
          ate 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 matching input sequences, as described below for each
          specifier.  A conversion 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 specifica-
          tion includes an n specifier.  An input item is defined as
          the longest sequence of input characters (up to any speci-
          fied 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 condi-
          tion 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 speci-
          fier.  If the input item is not a matching sequence, the
          execution of the directive fails: this condition is a

     Page 2                       Plan 9             (printed 3/19/24)

     FSCANF(2)                                               FSCANF(2)

          matching failure.  Unless assignment suppression was indi-
          cated 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 appropriate 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 corresponding 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 for-
                mat is the same as expected for the subject sequence
                of the strtoul (see atof(2)) function with 8 for the
                base argument.  The corresponding 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 argument 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 cor-
                responding argument shall be a pointer to float.

          s     Matches a sequence of non-white-space characters.  The
                corresponding argument shall be a pointer to the ini-
                tial 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

     Page 3                       Plan 9             (printed 3/19/24)

     FSCANF(2)                                               FSCANF(2)

                of expected characters (the scanset). The correspond-
                ing argument shall be a pointer to the initial charac-
                ter 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 charac-
                ters between the brackets (the scanlist) comprise the
                scanset, unless the character after the left bracket
                is a circumflex (^), in which case the scanset con-
                tains 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 speci-
                fied by the field width (1 if no field width is pre-
                sent 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 hexadecimal number).  The cor-
                responding 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 unde-
                fined.

          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. Execution of a %n direc-
                tive does not increment the assignment count returned
                at the completion of fscanf.

          %     Matches a single %; no conversion or assignment
                occurs.  The complete conversion specification shall
                be %%.

     Page 4                       Plan 9             (printed 3/19/24)

     FSCANF(2)                                               FSCANF(2)

          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 directive have been read (other than
          leading white space, where permitted), execution of the cur-
          rent 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 offending 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.

     Page 5                       Plan 9             (printed 3/19/24)