Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages

Plan 9 - man page for fscanf (plan9 section 2)

FSCANF(2)			       System Calls Manual				FSCANF(2)

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

SYNOPSIS
       #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 subsequent arguments as pointers to the objects to receive
       the converted input.  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  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  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 con-
	      version 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 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 conver-
	      sion 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  unavailabil-
       ity of input), or matching failures (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 matching input  sequences,
       as described below for each specifier.  A conversion specification is executed in the fol-
       lowing 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 speci-
       fier.  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 fol-
       lowing  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 format is the same as expected for
	     the subject sequence of the strtoul (see atof(2)) function with 8 for the base argu-
	     ment.  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 argu-
	     ment.  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  corre-
	     sponding 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 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 char-
	     acters  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 con-
	     tains all characters that do not appear in the scanlist 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 char-
	     acter  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) func-
	     tion (in Plan 9, a hexadecimal number).   The  corresponding  argument  shall  be	a
	     pointer  to  a pointer to void.  The interpretation of the input item is implementa-
	     tion defined; however, for any input item other than a value converted earlier  dur-
	     ing 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.  Execution 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  complete  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 directive 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 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 sup-
       pressed 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)


All times are GMT -4. The time now is 01:33 AM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
UNIX.COM Login
Username:
Password:  
Show Password