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

SYNOPSIS
       scan string format varName ?varName ...?


INTRODUCTION
       This command parses fields from an  input  string  in  the
       same  fashion as the ANSI C sscanf procedure and returns a
       count of the number of conversions performed, or -1 if the
       end  of the input string is reached before any conversions
       have been performed.  String gives the input to be  parsed
       and  format  indicates how to parse it, using % conversion
       specifiers as in sscanf.  Each varName gives the name of a
       variable;  when  a field is scanned from string the result
       is converted back into a string and assigned to the corre-
       sponding variable.


DETAILS ON SCANNING
       Scan  operates by scanning string and format together.  If
       the next character in format is a blank  or  tab  then  it
       matches  any  number  of  white space characters in string
       (including zero).  Otherwise, if it isn't  a  %  character
       then it must match the next character of string.  When a %
       is encountered in format, it indicates the start of a con-
       version  specifier.  A conversion specifier contains up to
       four fields after the %: a *,  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  char-
       acter.   The  fields  that  are present must appear in the
       order given above.

       When scan finds a conversion specifier in format, it first
       skips  any  white-space  characters  in string (unless the
       specifier is [ or c).  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 scan.

       If  the  %  is followed by a decimal number and a $, as in
       ``%2$d'', 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 varName.  If there are any positional specifiers
       in format then all of the specifiers must  be  positional.
       Every  varName  on  the  argument  list must correspond to
       exactly one conversion specifier or an error is generated.

       The following conversion characters are supported:
       d         The  input  field must be a decimal integer.  It
                 is read in and the value is stored in the  vari-
                 able as a decimal string.

       o         The  input field must be an octal integer. It is
                 read in and the value is stored in the  variable
                 as a decimal string.

       x         The  input  field must be a hexadecimal integer.
                 It is read in and the value  is  stored  in  the
                 variable as a decimal string.

       u         The  input field must be a decimal integer.  The
                 value is stored in the variable as  an  unsigned
                 decimal integer string.

       i         The  input  field  must be an integer.  The base
                 (i.e. decimal, octal, or hexadecimal) is  deter-
                 mined  in the same fashion as described in expr.
                 The value is stored in the variable as a decimal
                 string.

       c         A  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.

       s         The input field consists of all  the  characters
                 up  to the next white-space character; the char-
                 acters are copied to the variable.

       e or f or g
                 The input field must be a floating-point  number
                 consisting of an optional sign, a string of dec-
                 imal digits possibly containing a decimal point,
                 and an optional exponent consisting of an e or E
                 followed by an optional sign  and  a  string  of
                 decimal digits.  It is read in and stored in the
                 variable as a floating-point string.

       [chars]   The input field consists of any number of  char-
                 acters  in chars.  The matching string is stored
                 in the variable.  If the first character between
                 the  brackets  is a ] then it is treated as part
                 of chars rather than the closing bracket for the
                 set.   If  chars contains a sequence of the form
                 a-b then any character between a and  b  (inclu-
                 sive)  will match.  If the first or last charac-
                 ter between the brackets is  a  -,  then  it  is
                 treated  as part of chars rather than indicating
                 a range.

       [^chars]  The input field consists of any number of  char-
                 acters  not  in  chars.   The matching string is
                 stored in the variable.  If the character  imme-
                 diately  following  the  ^  is  a  ]  then it is
                 treated as part of the set rather than the clos-
                 ing  bracket  for  the set.  If chars contains a
                 sequence of the  form  a-b  then  any  character
                 between  a  and  b  (inclusive) will be excluded
                 from the set.  If the first  or  last  character
                 between  the brackets is a -, then it is treated
                 as part of chars rather than indicating a range.

       n         No  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 conver-
       sion  is the largest number that makes sense for that par-
       ticular conversion (e.g.  as many decimal digits as possi-
       ble  for  %d, as many octal digits as possible for %o, and
       so on).  The input field for a given conversion terminates
       either when a white-space character is encountered or when
       the maximum field width has been reached, whichever  comes
       first.  If a * is present in the conversion specifier then
       no variable is assigned and the next scan argument is  not
       consumed.


DIFFERENCES FROM ANSI SSCANF
       The behavior of the scan command is the same as the behav-
       ior of the ANSI C sscanf procedure except for the  follow-
       ing differences:

       [1]    %p conversion specifier is not currently supported.

       [2]    For %c conversions a single character value is con-
              verted  to a decimal string, which is then assigned
              to the corresponding varName; no field width may be
              specified for this conversion.

       [3]    The  l,  h,  and  L modifiers are ignored;  integer
              values are always converted as  if  there  were  no
              modifier  present  and  real values are always con-
              verted as if the l modifier were present (i.e. type
              double is used for the internal representation).


KEYWORDS
       conversion specifier, parse, scan
