fscanf man page on YellowDog

Man page or keyword search:  
man Server   18644 pages
apropos Keyword Search (all sections)
Output format
YellowDog logo
[printable version]

FSCANF(P)		   POSIX Programmer's Manual		     FSCANF(P)

NAME
       fscanf, scanf, sscanf - convert formatted input

SYNOPSIS
       #include <stdio.h>

       int fscanf(FILE *restrict stream, const char *restrict format, ... );
       int scanf(const char *restrict format, ... );
       int sscanf(const char *restrict s, const char *restrict format, ... );

DESCRIPTION
       The  fscanf()  function	shall  read  from the named input stream.  The
       scanf() function shall read from the standard input stream  stdin.  The
       sscanf()	 function  shall  read	from the string s. Each function reads
       bytes, interprets them according to a format, and stores the results in
       its  arguments.	Each  expects,	as  arguments, a control string format
       described below, and a set of pointer arguments	indicating  where  the
       converted  input should be stored. The result is undefined if there are
       insufficient arguments for the format.	If  the	 format	 is  exhausted
       while  arguments	 remain,  the  excess arguments shall be evaluated but
       otherwise ignored.

       Conversions can be applied to the nth argument after the format in  the
       argument	 list,	rather than to the next unused argument. In this case,
       the conversion specifier character % (see below)	 is  replaced  by  the
       sequence	  "%n$",   where   n   is  a  decimal  integer	in  the	 range
       [1,{NL_ARGMAX}]. This feature provides for  the	definition  of	format
       strings	that select arguments in an order appropriate to specific lan‐
       guages. In format strings containing the "%n$" form of conversion spec‐
       ifications,  it	is unspecified whether numbered arguments in the argu‐
       ment list can be referenced from the format string more than once.

       The format can contain either form of a	conversion  specification-that
       is, % or "%n$"-but the two forms cannot be mixed within a single format
       string. The only exception to this is that %% or %* can be  mixed  with
       the  "%n$" form. When numbered argument specifications are used, speci‐
       fying the Nth argument requires that all the  leading  arguments,  from
       the first to the ( N-1)th, are pointers.

       The  fscanf() function in all its forms shall allow detection of a lan‐
       guage-dependent radix character in the input string. The radix  charac‐
       ter  is	defined in the program's locale (category LC_NUMERIC ). In the
       POSIX locale, or in a locale where the radix character is not  defined,
       the radix character shall default to a period ( '.' ).

       The  format  is a character string, beginning and ending in its initial
       shift state, if any, composed of zero or more directives.  Each	direc‐
       tive is composed of one of the following: one or more white-space char‐
       acters (	 <space>s,  <tab>s,  <newline>s,  <vertical-tab>s,  or	<form-
       feed>s);	 an  ordinary character (neither '%' nor a white-space charac‐
       ter); or a conversion specification. Each conversion  specification  is
       introduced  by  the  character  '%'    or the character sequence "%n$",
	after which the following appear in sequence:

	* An optional assignment-suppressing character '*' .

	* An optional non-zero decimal	integer	 that  specifies  the  maximum
	  field width.

	* An  option  length modifier that specifies the size of the receiving
	  object.

	* A conversion specifier character that specifies the type of  conver‐
	  sion	to  be	applied. The valid conversion specifiers are described
	  below.

       The fscanf() functions shall execute each directive of  the  format  in
       turn.  If  a  directive	fails,	as  detailed below, the function shall
       return. Failures are described as input failures (due to	 the  unavail‐
       ability	of  input  bytes)  or  matching failures (due to inappropriate
       input).

       A directive composed of one or more  white-space	 characters  shall  be
       executed	 by reading input until no more valid input can be read, or up
       to the first byte which is not a white-space character,	which  remains
       unread.

       A directive that is an ordinary character shall be executed as follows:
       the next byte shall be read from the input and compared with  the  byte
       that comprises the directive; if the comparison shows that they are not
       equivalent, the directive shall fail, and the differing and  subsequent
       bytes  shall  remain  unread.  Similarly,  if  end-of-file, an encoding
       error, or a read error prevents a character from being read, the direc‐
       tive shall fail.

       A  directive that is a conversion specification defines a set of match‐
       ing input sequences, as described below for each conversion  character.
       A conversion specification shall be executed in the following steps.

       Input  white-space  characters  (as  specified  by isspace() ) shall be
       skipped, unless the conversion specification includes a [ , c , C ,  or
       n conversion specifier.

       An  item shall be read from the input, unless the conversion specifica‐
       tion includes an n conversion specifier. An input item shall be defined
       as  the	longest	 sequence  of input bytes (up to any specified maximum
       field width, which may be measured in characters or bytes dependent  on
       the conversion specifier) which is an initial subsequence of a matching
       sequence. The first byte, if any, after the  input  item	 shall	remain
       unread. If the length of the input item is 0, the execution of the con‐
       version specification shall fail; this condition is a matching failure,
       unless  end-of-file, an encoding error, or a read error prevented input
       from the stream, in which case it is an input failure.

       Except in the case of a % conversion specifier, the input item (or,  in
       the  case  of  a %n conversion specification, the count of input bytes)
       shall be converted to a type appropriate to the	conversion  character.
       If the input item is not a matching sequence, the execution of the con‐
       version specification fails; this  condition  is	 a  matching  failure.
       Unless  assignment  suppression	was indicated by a '*' , the result of
       the conversion shall be placed in the object pointed to	by  the	 first
       argument	 following the format argument that has not already received a
       conversion result if the conversion specification is introduced by %  ,
	or  in the nth argument if introduced by the character sequence "%n$".
       If this object does not have an appropriate type, or if the  result  of
       the  conversion cannot be represented in the space provided, the behav‐
       ior is undefined.

       The length modifiers and their meanings are:

       hh     Specifies that a following d , i , o , u , x , X , or n  conver‐
	      sion  specifier  applies	to  an	argument  with type pointer to
	      signed char or unsigned char.

       h      Specifies that a following d , i , o , u , x , X , or n  conver‐
	      sion specifier applies to an argument with type pointer to short
	      or unsigned short.

       l (ell)
	      Specifies that a following d , i , o , u , x , X , or n  conver‐
	      sion  specifier applies to an argument with type pointer to long
	      or unsigned long; that a following a , A , e , E , f , F ,  g  ,
	      or  G  conversion	 specifier  applies  to	 an argument with type
	      pointer to double; or that a following c , s , or	 [  conversion
	      specifier applies to an argument with type pointer to wchar_t.

       ll (ell-ell)

	      Specifies	 that a following d , i , o , u , x , X , or n conver‐
	      sion specifier applies to an argument with type pointer to  long
	      long or unsigned long long.

       j      Specifies	 that a following d , i , o , u , x , X , or n conver‐
	      sion specifier applies to an argument with type pointer to  int‐
	      max_t or uintmax_t.

       z      Specifies	 that a following d , i , o , u , x , X , or n conver‐
	      sion specifier applies to	 an  argument  with  type  pointer  to
	      size_t or the corresponding signed integer type.

       t      Specifies	 that a following d , i , o , u , x , X , or n conver‐
	      sion specifier applies to	 an  argument  with  type  pointer  to
	      ptrdiff_t or the corresponding unsigned type.

       L      Specifies that a following a , A , e , E , f , F , g , or G con‐
	      version specifier applies to an argument with  type  pointer  to
	      long double.

       If  a  length modifier appears with any conversion specifier other than
       as specified above, 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 strtol() with
	      the value 10 for the base argument. In the  absence  of  a  size
	      modifier,	 the  application  shall ensure that the corresponding
	      argument is a pointer to int.

       i      Matches an optionally signed integer, whose format is  the  same
	      as  expected for the subject sequence of strtol() with 0 for the
	      base argument. In the absence of a size modifier,	 the  applica‐
	      tion  shall  ensure that the corresponding argument is a pointer
	      to int.

       o      Matches an optionally signed octal integer, whose format is  the
	      same  as expected for the subject sequence of strtoul() with the
	      value 8 for the base argument. In the absence of	a  size	 modi‐
	      fier,  the application shall ensure that the corresponding argu‐
	      ment is a pointer to unsigned.

       u      Matches an optionally signed decimal integer,  whose  format  is
	      the  same as expected for the subject sequence of strtoul() with
	      the value 10 for the base argument. In the  absence  of  a  size
	      modifier,	 the  application  shall ensure that the corresponding
	      argument is a pointer to unsigned.

       x      Matches an optionally signed hexadecimal integer,	 whose	format
	      is  the  same  as expected for the subject sequence of strtoul()
	      with the value 16 for the base argument. In  the	absence	 of  a
	      size modifier, the application shall ensure that the correspond‐
	      ing argument is a pointer to unsigned.

       a, e, f, g

	      Matches an optionally signed floating-point number, infinity, or
	      NaN,  whose  format  is  the  same  as  expected for the subject
	      sequence of strtod(). In the absence of  a  size	modifier,  the
	      application  shall  ensure  that the corresponding argument is a
	      pointer to float.

       If the fprintf() family of functions generates character string	repre‐
       sentations for infinity and NaN (a symbolic entity encoded in floating-
       point format) to support	 IEEE Std 754-1985,  the  fscanf()  family  of
       functions shall recognize them as input.

       s      Matches a sequence of bytes that are not white-space characters.
	      The application shall ensure that the corresponding argument  is
	      a	 pointer to the initial byte of an array of char, signed char,
	      or unsigned char large enough to accept the sequence and a  ter‐
	      minating	null  character	 code,	which shall be added automati‐
	      cally.

       If an l (ell) qualifier is present, the input is a sequence of  charac‐
       ters  that  begins  in the initial shift state. Each character shall be
       converted to a wide character as if by a call to	 the  mbrtowc()	 func‐
       tion,  with  the conversion state described by an mbstate_t object ini‐
       tialized to zero before the first character is converted. The  applica‐
       tion  shall  ensure  that the corresponding argument is a pointer to an
       array of wchar_t large enough to accept the sequence and the  terminat‐
       ing null wide character, which shall be added automatically.

       [      Matches  a  non-empty  sequence  of bytes from a set of expected
	      bytes (the scanset). The normal skip over white-space characters
	      shall  be	 suppressed in this case. The application shall ensure
	      that the corresponding argument is a pointer to the initial byte
	      of  an array of char, signed char, or unsigned char large enough
	      to accept the sequence and a terminating null byte, which	 shall
	      be added automatically.

       If  an l (ell) qualifier is present, the input is a sequence of charac‐
       ters that begins in the initial shift  state.  Each  character  in  the
       sequence	 shall be converted to a wide character as if by a call to the
       mbrtowc() function, with the conversion state described by an mbstate_t
       object initialized to zero before the first character is converted. The
       application shall ensure that the corresponding argument is  a  pointer
       to an array of wchar_t large enough to accept the sequence and the ter‐
       minating null wide character, which shall be added automatically.

       The conversion specification includes all subsequent bytes in the  for‐
       mat  string up to and including the matching right square bracket ( ']'
       ). The bytes between the square brackets (the  scanlist)	 comprise  the
       scanset,	 unless the byte after the left square bracket is a circumflex
       ( '^' ), in which case the scanset  contains  all  bytes	 that  do  not
       appear  in  the	scanlist  between  the circumflex and the right square
       bracket.	 If the conversion specification begins with "[]" or  "[^]"  ,
       the right square bracket is included in the scanlist and the next right
       square bracket is the matching right square bracket that ends the  con‐
       version specification; otherwise, the first right square bracket is the
       one that ends the conversion specification. If a '-' is in the scanlist
       and  is not the first character, nor the second where the first charac‐
       ter is a '^' , nor the last character, the behavior is  implementation-
       defined.

       c      Matches a sequence of bytes of the number specified by the field
	      width (1 if no field width is present in the conversion specifi‐
	      cation).	The  application  shall	 ensure that the corresponding
	      argument is a pointer to the initial byte of an array  of	 char,
	      signed  char,  or	 unsigned  char	 large	enough	to  accept the
	      sequence. No null byte is added. The  normal  skip  over	white-
	      space characters shall be suppressed in this case.

       If  an  l  (ell) qualifier is present, the input shall be a sequence of
       characters that begins in the initial shift state.  Each	 character  in
       the  sequence  is  converted to a wide character as if by a call to the
       mbrtowc() function, with the conversion state described by an mbstate_t
       object initialized to zero before the first character is converted. The
       application shall ensure that the corresponding argument is  a  pointer
       to an array of wchar_t large enough to accept the resulting sequence of
       wide characters. No null wide character is added.

       p      Matches an implementation-defined set of sequences, which	 shall
	      be  the  same as the set of sequences that is produced by the %p
	      conversion specification of the  corresponding  fprintf()	 func‐
	      tions. The application shall ensure that the corresponding argu‐
	      ment is a pointer to a pointer to void.  The  interpretation  of
	      the input item is implementation-defined. If the input item is a
	      value converted earlier during the same program  execution,  the
	      pointer  that  results shall compare equal to that value; other‐
	      wise, the behavior of the %p conversion specification  is	 unde‐
	      fined.

       n      No input is consumed. The application shall ensure that the cor‐
	      responding argument is a pointer to the integer into which shall
	      be  written  the	number	of bytes read from the input so far by
	      this call to the fscanf() functions. Execution of a  %n  conver‐
	      sion  specification  shall  not  increment  the assignment count
	      returned at the completion of  execution	of  the	 function.  No
	      argument	shall  be converted, but one shall be consumed. If the
	      conversion  specification	 includes  an	assignment-suppressing
	      character or a field width, the behavior is undefined.

       C      Equivalent to lc .

       S      Equivalent to ls .

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

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

       The conversion specifiers A , E , F , G , and  X	 are  also  valid  and
       shall be equivalent to a , e , f , g , and x , respectively.

       If  end-of-file is encountered during input, conversion shall be termi‐
       nated.  If end-of-file occurs before any	 bytes	matching  the  current
       conversion  specification  (except  for %n ) have been read (other than
       leading white-space characters, where permitted), execution of the cur‐
       rent  conversion	 specification	shall terminate with an input failure.
       Otherwise, unless execution of the current conversion specification  is
       terminated  with a matching failure, execution of the following conver‐
       sion specification (if any) shall be terminated with an input failure.

       Reaching the end of the string  in  sscanf()  shall  be	equivalent  to
       encountering end-of-file for fscanf().

       If conversion terminates on a conflicting input, the offending input is
       left unread in the input. Any trailing  white  space  (including	 <new‐
       line>s)	shall be left unread unless matched by a conversion specifica‐
       tion. The success of literal matches and suppressed assignments is only
       directly determinable via the %n conversion specification.

       The  fscanf()  and scanf() functions may mark the st_atime field of the
       file associated with stream for update. The  st_atime  field  shall  be
       marked  for  update  by	the  first  successful	execution  of fgetc(),
       fgets(), fread(), getc(),  getchar(),  gets(),  fscanf(),  or  fscanf()
       using  stream  that  returns  data  not	supplied  by  a	 prior call to
       ungetc().

RETURN VALUE
       Upon successful completion, these functions shall return the number  of
       successfully  matched and assigned input items; this number can be zero
       in the event of an early matching failure. If the input ends before the
       first  matching failure or conversion, EOF shall be returned. If a read
       error occurs, the error indicator for the stream is set, EOF  shall  be
       returned,    and errno shall be set to indicate the error.

ERRORS
       For  the	 conditions  under  which  the fscanf() functions fail and may
       fail, refer to fgetc() or fgetwc() .

       In addition, fscanf() may fail if:

       EILSEQ Input byte sequence does not form a valid character.

       EINVAL There are insufficient arguments.

       The following sections are informative.

EXAMPLES
       The call:

	      int i, n; float x; char name[50];
	      n = scanf("%d%f%s", &i, &x, name);

       with the input line:

	      25 54.32E-1 Hamster

       assigns to n the value 3, to i the value 25, to x the value 5.432,  and
       name contains the string "Hamster" .

       The call:

	      int i; float x; char name[50];
	      (void) scanf("%2d%f%*d %[0123456789]", &i, &x, name);

       with input:

	      56789 0123 56a72

       assigns	56  to i, 789.0 to x, skips 0123, and places the string "56\0"
       in name. The next call to getchar() shall return the character 'a' .

   Reading Data into an Array
       The following call uses fscanf() to read three  floating-point  numbers
       from standard input into the input array.

	      float input[3]; fscanf (stdin, "%f %f %f", input, input+1, input+2);

APPLICATION USAGE
       If  the	application calling fscanf() has any objects of type wint_t or
       wchar_t, it must also  include  the  <wchar.h>  header  to  have	 these
       objects defined.

RATIONALE
       This  function  is  aligned with the ISO/IEC 9899:1999 standard, and in
       doing so a few "obvious" things were not included.   Specifically,  the
       set  of characters allowed in a scanset is limited to single-byte char‐
       acters. In other similar places, multi-byte characters have  been  per‐
       mitted,	but  for alignment with the ISO/IEC 9899:1999 standard, it has
       not been done here. Applications needing this could use the correspond‐
       ing wide-character functions to achieve the desired results.

FUTURE DIRECTIONS
       None.

SEE ALSO
       getc()  ,  printf()  ,  setlocale() , strtod() , strtol() , strtoul() ,
       wcrtomb() , the Base Definitions volume of IEEE Std 1003.1-2001,	 Chap‐
       ter 7, Locale, <langinfo.h>, <stdio.h>, <wchar.h>

COPYRIGHT
       Portions	 of  this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
       --  Portable  Operating	System	Interface (POSIX), The Open Group Base
       Specifications Issue 6, Copyright (C) 2001-2003	by  the	 Institute  of
       Electrical  and	Electronics  Engineers, Inc and The Open Group. In the
       event of any discrepancy between this version and the original IEEE and
       The  Open Group Standard, the original IEEE and The Open Group Standard
       is the referee document. The original Standard can be  obtained	online
       at http://www.opengroup.org/unix/online.html .

IEEE/The Open Group		     2003			     FSCANF(P)
[top]

List of man pages available for YellowDog

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net