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



PPRROOLLOOGG
       This manual page is part of the POSIX Programmer's Manual.  The OS
       implementation of this interface may differ (consult the corresponding
       OS manual page for details of OS behavior), or the interface may not be
       implemented on OS.


NNAAMMEE
       fscanf, scanf, sscanf -- convert formatted input

SSYYNNOOPPSSIISS
       #include <stdio.h>

       int fscanf(FILE *restrict _s_t_r_e_a_m, const char *restrict _f_o_r_m_a_t, ...);
       int scanf(const char *restrict _f_o_r_m_a_t, ...);
       int sscanf(const char *restrict _s, const char *restrict _f_o_r_m_a_t, ...);

DDEESSCCRRIIPPTTIIOONN
       The functionality described on this reference page is aligned with the
       ISO C standard. Any conflict between the requirements described here
       and the ISO C standard is unintentional. This volume of POSIX.1-2008
       defers to the ISO C standard.

       The _f_s_c_a_n_f() function shall read from the named input _s_t_r_e_a_m.  The
       _s_c_a_n_f() function shall read from the standard input stream _s_t_d_i_n.  The
       _s_s_c_a_n_f() 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 _f_o_r_m_a_t
       described below, and a set of _p_o_i_n_t_e_r 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 _f_o_r_m_a_t 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
       languages. In format strings containing the "%_n$" form of conversion
       specifications, it is unspecified whether numbered arguments in the
       argument list can be referenced from the format string more than once.

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

       The _f_s_c_a_n_f() function in all its forms shall allow detection of a
       language-dependent radix character in the input string. The radix
       character is defined in the current locale (category _L_C___N_U_M_E_R_I_C).  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
       directive is composed of one of the following: one or more white-space
       characters (<space>, <tab>, <newline>, <vertical-tab>, or <form-feed>);
       an ordinary character (neither ''%%'' nor a white-space character); 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 optional assignment-allocation character ''mm''.

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

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

       The _f_s_c_a_n_f() 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
       unavailability 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
       directive shall fail.

       A directive that is a conversion specification defines a set of
       matching 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 _i_s_s_p_a_c_e()) shall be
       skipped, unless the conversion specification includes a [[, cc, CC, or nn
       conversion specifier.

       An item shall be read from the input, unless the conversion
       specification includes an nn 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 conversion 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 %%nn 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
       conversion 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 _f_o_r_m_a_t 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
       behavior is undefined.

       The %%cc, %%ss, and %%[[ conversion specifiers shall accept an optional
       assignment-allocation character ''mm'', which shall cause a memory buffer
       to be allocated to hold the string converted including a terminating
       null character. In such a case, the argument corresponding to the
       conversion specifier should be a reference to a pointer variable that
       will receive a pointer to the allocated buffer. The system shall
       allocate a buffer as if _m_a_l_l_o_c() had been called. The application shall
       be responsible for freeing the memory after usage. If there is
       insufficient memory to allocate a buffer, the function shall set _e_r_r_n_o
       to [[EENNOOMMEEMM]] and a conversion error shall result. If the function
       returns EOF, any memory successfully allocated for parameters using
       assignment-allocation character ''mm'' by this call shall be freed before
       the function returns.

       The length modifiers and their meanings are:

       hh      Specifies that a following dd, ii, oo, uu, xx, XX, or nn conversion
               specifier applies to an argument with type pointer to ssiiggnneedd
               cchhaarr or uunnssiiggnneedd cchhaarr.

       h       Specifies that a following dd, ii, oo, uu, xx, XX, or nn conversion
               specifier applies to an argument with type pointer to sshhoorrtt or
               uunnssiiggnneedd sshhoorrtt.

       l (ell) Specifies that a following dd, ii, oo, uu, xx, XX, or nn conversion
               specifier applies to an argument with type pointer to lloonngg or
               uunnssiiggnneedd lloonngg; that a following aa, AA, ee, EE, ff, FF, gg, or GG
               conversion specifier applies to an argument with type pointer
               to ddoouubbllee; or that a following cc, ss, or [[ conversion specifier
               applies to an argument with type pointer to wwcchhaarr__tt.  If the
               ''mm'' assignment-allocation character is specified, the
               conversion applies to an argument with the type pointer to a
               pointer to wwcchhaarr__tt.

       ll (ell-ell)
               Specifies that a following dd, ii, oo, uu, xx, XX, or nn conversion
               specifier applies to an argument with type pointer to lloonngg lloonngg
               or uunnssiiggnneedd lloonngg lloonngg.

       j       Specifies that a following dd, ii, oo, uu, xx, XX, or nn conversion
               specifier applies to an argument with type pointer to iinnttmmaaxx__tt
               or uuiinnttmmaaxx__tt.

       z       Specifies that a following dd, ii, oo, uu, xx, XX, or nn conversion
               specifier applies to an argument with type pointer to ssiizzee__tt or
               the corresponding signed integer type.

       t       Specifies that a following dd, ii, oo, uu, xx, XX, or nn conversion
               specifier applies to an argument with type pointer to ppttrrddiiffff__tt
               or the corresponding uunnssiiggnneedd type.

       L       Specifies that a following aa, AA, ee, EE, ff, FF, gg, or GG conversion
               specifier applies to an argument with type pointer to lloonngg
               ddoouubbllee.

       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 _s_t_r_t_o_l() with
               the value 10 for the _b_a_s_e argument. In the absence of a size
               modifier, the application shall ensure that the corresponding
               argument is a pointer to iinntt.

       i       Matches an optionally signed integer, whose format is the same
               as expected for the subject sequence of _s_t_r_t_o_l() with 0 for the
               _b_a_s_e argument. In the absence of a size modifier, the
               application shall ensure that the corresponding argument is a
               pointer to iinntt.

       o       Matches an optionally signed octal integer, whose format is the
               same as expected for the subject sequence of _s_t_r_t_o_u_l() with the
               value 8 for the _b_a_s_e argument. In the absence of a size
               modifier, the application shall ensure that the corresponding
               argument is a pointer to uunnssiiggnneedd.

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

       x       Matches an optionally signed hexadecimal integer, whose format
               is the same as expected for the subject sequence of _s_t_r_t_o_u_l()
               with the value 16 for the _b_a_s_e argument. In the absence of a
               size modifier, the application shall ensure that the
               corresponding argument is a pointer to uunnssiiggnneedd.

       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 _s_t_r_t_o_d().  In the absence of a size modifier, the
               application shall ensure that the corresponding argument is a
               pointer to ffllooaatt.

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

       s       Matches a sequence of bytes that are not white-space
               characters. If the ''mm'' assignment-allocation character is not
               specified, the application shall ensure that the corresponding
               argument is a pointer to the initial byte of an array of cchhaarr,
               ssiiggnneedd cchhaarr, or uunnssiiggnneedd cchhaarr large enough to accept the
               sequence and a terminating null character code, which shall be
               added automatically.  Otherwise, the application shall ensure
               that the corresponding argument is a pointer to a pointer to a
               cchhaarr.

               If an ll (ell) qualifier is present, the input is a sequence of
               characters that begins in the initial shift state. Each
               character shall be converted to a wide character as if by a
               call to the _m_b_r_t_o_w_c() function, with the conversion state
               described by an mmbbssttaattee__tt object initialized to zero before the
               first character is converted.  If the ''mm'' assignment-allocation
               character is not specified, the application shall ensure that
               the corresponding argument is a pointer to an array of wwcchhaarr__tt
               large enough to accept the sequence and the terminating null
               wide character, which shall be added automatically.  Otherwise,
               the application shall ensure that the corresponding argument is
               a pointer to a pointer to a wwcchhaarr__tt.

       [       Matches a non-empty sequence of bytes from a set of expected
               bytes (the _s_c_a_n_s_e_t).  The normal skip over white-space
               characters shall be suppressed in this case. If the ''mm''
               assignment-allocation character is not specified, the
               application shall ensure that the corresponding argument is a
               pointer to the initial byte of an array of cchhaarr, ssiiggnneedd cchhaarr,
               or uunnssiiggnneedd cchhaarr large enough to accept the sequence and a
               terminating null byte, which shall be added automatically.
               Otherwise, the application shall ensure that the corresponding
               argument is a pointer to a pointer to a cchhaarr.

               If an ll (ell) qualifier is present, the input is a sequence of
               characters 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 _m_b_r_t_o_w_c() function, with the
               conversion state described by an mmbbssttaattee__tt object initialized
               to zero before the first character is converted.  If the ''mm''
               assignment-allocation character is not specified, the
               application shall ensure that the corresponding argument is a
               pointer to an array of wwcchhaarr__tt large enough to accept the
               sequence and the terminating null wide character, which shall
               be added automatically.
               Otherwise, the application shall ensure that the corresponding
               argument is a pointer to a pointer to a wwcchhaarr__tt.

               The conversion specification includes all subsequent bytes in
               the _f_o_r_m_a_t string up to and including the matching <right-
               square-bracket> ('']]'').  The bytes between the square brackets
               (the _s_c_a_n_l_i_s_t) 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 conversion 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
               character 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
               specification). No null byte is added. The normal skip over
               white-space characters shall be suppressed in this case. If the
               ''mm'' assignment-allocation character is not specified, the
               application shall ensure that the corresponding argument is a
               pointer to the initial byte of an array of cchhaarr, ssiiggnneedd cchhaarr,
               or uunnssiiggnneedd cchhaarr large enough to accept the sequence.
               Otherwise, the application shall ensure that the corresponding
               argument is a pointer to a pointer to a cchhaarr.

               If an ll (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 _m_b_r_t_o_w_c() function, with the conversion
               state described by an mmbbssttaattee__tt object initialized to zero
               before the first character is converted.  No null wide
               character is added. If the ''mm'' assignment-allocation character
               is not specified, the application shall ensure that the
               corresponding argument is a pointer to an array of wwcchhaarr__tt
               large enough to accept the resulting sequence of wide
               characters.  Otherwise, the application shall ensure that the
               corresponding argument is a pointer to a pointer to a wwcchhaarr__tt.

       p       Matches an implementation-defined set of sequences, which shall
               be the same as the set of sequences that is produced by the %%pp
               conversion specification of the corresponding _f_p_r_i_n_t_f()
               functions. The application shall ensure that the corresponding
               argument is a pointer to a pointer to vvooiidd.  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;
               otherwise, the behavior of the %%pp conversion specification is
               undefined.

       n       No input is consumed. The application shall ensure that the
               corresponding 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 _f_s_c_a_n_f() functions. Execution of a %%nn
               conversion 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 llcc.

       S       Equivalent to llss.

       %       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 AA, EE, FF, GG, and XX are also valid and shall be
       equivalent to aa, ee, ff, gg, and xx, respectively.

       If end-of-file is encountered during input, conversion shall be
       terminated. If end-of-file occurs before any bytes matching the current
       conversion specification (except for %%nn) have been read (other than
       leading white-space characters, where permitted), execution of the
       current 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
       conversion specification (if any) shall be terminated with an input
       failure.

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

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

       The _f_s_c_a_n_f() and _s_c_a_n_f() functions may mark the last data access
       timestamp of the file associated with _s_t_r_e_a_m for update. The last data
       access timestamp shall be marked for update by the first successful
       execution of _f_g_e_t_c(), _f_g_e_t_s(), _f_r_e_a_d(), _g_e_t_c(), _g_e_t_c_h_a_r(), _g_e_t_d_e_l_i_m(),
       _g_e_t_l_i_n_e(), _g_e_t_s(), _f_s_c_a_n_f(), or _s_c_a_n_f() using _s_t_r_e_a_m that returns data
       not supplied by a prior call to _u_n_g_e_t_c().

RREETTUURRNN VVAALLUUEE
       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 conversion (if any) has completed, and without a matching failure
       having occurred, EOF shall be returned. If an error occurs before the
       first conversion (if any) has completed, and without a matching failure
       having occurred, EOF shall be returned and _e_r_r_n_o shall be set to
       indicate the error.  If a read error occurs, the error indicator for
       the stream shall be set.

EERRRROORRSS
       For the conditions under which the _f_s_c_a_n_f() functions fail and may
       fail, refer to _f_g_e_t_c() or _f_g_e_t_w_c().

       In addition, the _f_s_c_a_n_f() function shall fail if:

       EEIILLSSEEQQ Input byte sequence does not form a valid character.

       EENNOOMMEEMM Insufficient storage space is available.

       In addition, the _f_s_c_a_n_f() function may fail if:

       EEIINNVVAALL There are insufficient arguments.

       _T_h_e _f_o_l_l_o_w_i_n_g _s_e_c_t_i_o_n_s _a_r_e _i_n_f_o_r_m_a_t_i_v_e_.

EEXXAAMMPPLLEESS
       The call:

           iinntt ii,, nn;; ffllooaatt xx;; cchhaarr nnaammee[[5500]];;
           nn == ssccaannff((""%%dd%%ff%%ss"",, &&ii,, &&xx,, nnaammee));;

       with the input line:

           2255 5544..3322EE--11 HHaammsstteerr

       assigns to _n the value 3, to _i the value 25, to _x the value 5.432, and
       _n_a_m_e contains the string ""HHaammsstteerr"".

       The call:

           iinntt ii;; ffllooaatt xx;; cchhaarr nnaammee[[5500]];;
           ((vvooiidd)) ssccaannff((""%%22dd%%ff%%**dd %%[[00112233445566778899]]"",, &&ii,, &&xx,, nnaammee));;

       with input:

           5566778899 00112233 5566aa7722

       assigns 56 to _i, 789.0 to _x, skips 0123, and places the string ""5566\\00""
       in _n_a_m_e.  The next call to _g_e_t_c_h_a_r() shall return the character ''aa''.

   RReeaaddiinngg DDaattaa iinnttoo aann AArrrraayy
       The following call uses _f_s_c_a_n_f() to read three floating-point numbers
       from standard input into the _i_n_p_u_t array.

           ffllooaatt iinnppuutt[[33]];; ffssccaannff ((ssttddiinn,, ""%%ff %%ff %%ff"",, iinnppuutt,, iinnppuutt++11,, iinnppuutt++22));;

AAPPPPLLIICCAATTIIOONN UUSSAAGGEE
       If the application calling _f_s_c_a_n_f() has any objects of type wwiinntt__tt or
       wwcchhaarr__tt, it must also include the _<_w_c_h_a_r_._h_> header to have these
       objects defined.

       For functions that allocate memory as if by _m_a_l_l_o_c(), the application
       should release such memory when it is no longer required by a call to
       _f_r_e_e().  For _f_s_c_a_n_f(), this is memory allocated via use of the ''mm''
       assignment-allocation character.

RRAATTIIOONNAALLEE
       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
       characters.  In other similar places, multi-byte characters have been
       permitted, but for alignment with the ISO/IEC 9899:1999 standard, it
       has not been done here. Applications needing this could use the
       corresponding wide-character functions to achieve the desired results.

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       None.

SSEEEE AALLSSOO
       _S_e_c_t_i_o_n _2_._5, _S_t_a_n_d_a_r_d _I_/_O _S_t_r_e_a_m_s, _f_p_r_i_n_t_f(), _g_e_t_c(), _s_e_t_l_o_c_a_l_e(),
       _s_t_r_t_o_d(), _s_t_r_t_o_l(), _s_t_r_t_o_u_l(), _w_c_r_t_o_m_b()

       The Base Definitions volume of POSIX.1-2008, _C_h_a_p_t_e_r _7, _L_o_c_a_l_e,
       <<llaannggiinnffoo..hh>>, <<ssttddiioo..hh>>, <<wwcchhaarr..hh>>

CCOOPPYYRRIIGGHHTT
       Portions of this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
       -- Portable Operating System Interface (POSIX), The Open Group Base
       Specifications Issue 7, Copyright (C) 2013 by the Institute of
       Electrical and Electronics Engineers, Inc and The Open Group.  (This is
       POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) 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.unix.org/online.html .

       Any typographical or formatting errors that appear in this page are
       most likely to have been introduced during the conversion of the source
       files to man page format. To report such errors, see
       https://www.kernel.org/doc/man-pages/reporting_bugs.html .



IEEE/The Open Group                  2013                            FSCANF(3)
