1mNAME0m
       scan - Parse string using conversion specifiers in the style of sscanf

1mSYNOPSIS0m
       1mscan 4m22mstring24m 4mformat24m ?4mvarName24m 4mvarName24m 4m...24m?


1mINTRODUCTION0m
       This  command parses fields from an input string in the same fashion as
       the ANSI C 1msscanf 22mprocedure and returns a count of the number  of  con-
       versions  performed,  or  -1  if the end of the input string is reached
       before any conversions have been performed.  4mString24m gives the input  to
       be  parsed  and  4mformat24m  indicates  how to parse it, using 1m% 22mconversion
       specifiers as in 1msscanf22m.  Each 4mvarName24m gives the name  of  a  variable;
       when a field is scanned from 4mstring24m the result is converted back into a
       string and assigned to the corresponding variable.  If no 4mvarName24m vari-
       ables are specified, then 1mscan 22mworks in an inline manner, returning the
       data that would otherwise be stored in the variables as a list.  In the
       inline  case,  an  empty  string  is returned when the end of the input
       string is reached before any conversions have been performed.


1mDETAILS ON SCANNING0m
       1mScan 22moperates by scanning 4mstring24m and  4mformat24m  together.   If  the  next
       character  in  4mformat24m  is  a blank or tab then it matches any number of
       white space characters in 4mstring24m (including zero).   Otherwise,  if  it
       isn't  a  1m%  22mcharacter then it must match the next character of 4mstring24m.
       When a 1m% 22mis encountered in 4mformat24m, it indicates the start of a  conver-
       sion  specifier.   A  conversion  specifier  contains up to four fields
       after the 1m%22m: a 1m*22m, which indicates that the converted  value  is  to  be
       discarded instead of assigned to a variable; a XPG3 position specifier;
       a number indicating a maximum field width; and a conversion  character.
       All  of  these fields are optional except for the conversion character.
       The fields that are present must appear in the order given above.

       When 1mscan 22mfinds a conversion specifier in 4mformat24m, it  first  skips  any
       white-space  characters  in  4mstring24m  (unless  the specifier is 1m[ 22mor 1mc22m).
       Then it converts the next input characters according to the  conversion
       specifier and stores the result in the variable given by the next argu-
       ment to 1mscan22m.

       If the 1m% 22mis followed by a decimal number and a 1m$22m, as in ``1m%2$d22m'',  then
       the  variable  to  use  is not taken from the next sequential argument.
       Instead, it is taken from the argument indicated by the number, where 1
       corresponds  to  the first 4mvarName24m.  If there are any positional speci-
       fiers in 4mformat24m then all of the specifiers must be  positional.   Every
       4mvarName24m  on the argument list must correspond to exactly one conversion
       specifier or an error is generated, or in the inline case, any position
       can be specified at most once and the empty positions will be filled in
       with empty strings.

       The following conversion characters are supported:

       1md         22mThe input field must be a decimal integer.  It is read in and
                 the value is stored in the variable as a decimal string.

       1mo         22mThe  input  field must be an octal integer. It is read in and
                 the value is stored in the variable as a decimal string.   If
                 the  value  exceeds  MAX_INT (017777777777 on platforms using
                 32-bit integers), it will be truncated to a  signed  integer.
                 Hence, 037777777777 will appear as -1 on a 32-bit machine.

       1mx         22mThe  input field must be a hexadecimal integer. It is read in
                 and the value is stored in the variable as a decimal  string.
                 If  the  value exceeds MAX_INT (0x7FFFFFFF on platforms using
                 32-bit integers), it will be truncated to a  signed  integer.
                 Hence, 0xFFFFFFFF will appear as -1 on a 32-bit machine.

       1mu         22mThe  input  field  must  be  a decimal integer.  The value is
                 stored in the variable as an unsigned decimal integer string.

       1mi         22mThe  input field must be an integer.  The base (i.e. decimal,
                 octal, or hexadecimal) is determined in the same  fashion  as
                 described  in 1mexpr22m.  The value is stored in the variable as a
                 decimal string.

       1mc         22mA single character is read in and its binary value is  stored
                 in  the variable as a decimal string.  Initial white space is
                 not skipped in this case, so the input field may be a  white-
                 space  character.  This conversion is different from the ANSI
                 standard in that the input field always consists of a  single
                 character and no field width may be specified.

       1ms         22mThe input field consists of all the characters up to the next
                 white-space character; the characters are copied to the vari-
                 able.

       1me 22mor 1mf 22mor 1mg0m
                 The input field must be a floating-point number consisting of
                 an optional sign, a string of decimal  digits  possibly  con-
                 taining  a decimal point, and an optional exponent consisting
                 of an 1me 22mor 1mE 22mfollowed by an optional sign  and  a  string  of
                 decimal  digits.  It is read in and stored in the variable as
                 a floating-point string.

       1m[4m22mchars24m1m]   22mThe input field consists  of  any  number  of  characters  in
                 4mchars24m.   The  matching  string is stored in the variable.  If
                 the first character between the brackets is a 1m]  22mthen  it  is
                 treated  as part of 4mchars24m rather than the closing bracket for
                 the set.  If 4mchars24m contains a sequence of the form  4ma24m1m-4m22mb24m  then
                 any character between 4ma24m and 4mb24m (inclusive) will match.  If the
                 first or last character between the brackets is a 1m-22m, then  it
                 is treated as part of 4mchars24m rather than indicating a range.

       1m[^4m22mchars24m1m]  22mThe  input  field consists of any number of characters not in
                 4mchars24m.  The matching string is stored in  the  variable.   If
                 the  character  immediately following the 1m^ 22mis a 1m] 22mthen it is
                 treated as part of the set rather than  the  closing  bracket
                 for  the  set.   If 4mchars24m contains a sequence of the form 4ma24m1m-4m22mb0m
                 then any character  between  4ma24m  and  4mb24m  (inclusive)  will  be
                 excluded  from  the  set.   If  the  first  or last character
                 between the brackets is a 1m-22m, then it is treated  as  part  of
                 4mchars24m rather than indicating a range.

       1mn         22mNo  input  is  consumed  from the input string.  Instead, the
                 total number of chacters scanned from the input string so far
                 is stored in the variable.

       The  number  of  characters read from the input for a conversion is the
       largest number that makes sense for that  particular  conversion  (e.g.
       as many decimal digits as possible for 1m%d22m, as many octal digits as pos-
       sible for 1m%o22m, and so on).  The input field for a given conversion  ter-
       minates  either when a white-space character is encountered or when the
       maximum field width has been reached, whichever comes first.  If a 1m* 22mis
       present  in  the  conversion specifier then no variable is assigned and
       the next scan argument is not consumed.


1mDIFFERENCES FROM ANSI SSCANF0m
       The behavior of the 1mscan 22mcommand is the same as  the  behavior  of  the
       ANSI C 1msscanf 22mprocedure except for the following differences:

       [1]    1m%p 22mconversion specifier is not currently supported.

       [2]    For  1m%c  22mconversions  a single character value is converted to a
              decimal string, which is then assigned to the corresponding 4mvar-0m
              4mName24m; no field width may be specified for this conversion.

       [3]    The  1ml22m,  1mh22m,  and  1mL  22mmodifiers  are ignored;  integer values are
              always converted as if there were no modifier present  and  real
              values  are  always  converted as if the 1ml 22mmodifier were present
              (i.e. type 1mdouble 22mis used for the internal representation).

       [4]    If the end of the input string is reached before any conversions
              have been performed and no variables are given, and empty string
              is returned.


1mSEE ALSO0m
       format(n), sscanf(3)


1mKEYWORDS0m
