Schily's LIBRARY FUNCTIONS                             GETARGS(3)


NAME

     getargs() - parses arguments until a non-flag is reached


SYNOPSIS

     int getargs(pac, pav, fmt, a1, ..., an)
          int *pac;       /* pointer to arg count */
          char *(*pav)[]; /* pointer to address of arg vector */
          char *fmt;      /* format string */
          type *a1;       /* pointer to result 1 (corresponding */
                          /* to the first descriptor in fmt) */
          type *an;       /* pointer to result n (corresponding */
                          /* to the nth descriptor in fmt) */


DESCRIPTION

     getargs() looks at each argument that begins with '-',  '+',
     or  has an '=' in it and trys to find a matching description
     in fmt.  If  a  match  is  found,  the  corresponding  value
     pointed  at by a1 to an is set to the value according to the
     conversion specification.

     If a match is not found, getargs() returns  the  error  code
     -1,  with  *pav[0] pointing to the bad argument. If an argu-
     ment that does not begin with '-' or '+' or contain  an  '='
     is found, getargs() returns +1, again with av[0] pointing to
     the non-flag argument.

     In the description, it is assumed that pac=&ac and  pav=&av,
     where ac and av are the two arguments passed to main().  The
     pointers are necessary so that getargs() can update  ac  and
     av  as  it  verifies  each argument and reflects the current
     position back to the user.

     Descriptors are composed of standard characters, which  must
     match, followed by a conversion character.

     Legal conversions and their meanings are:

     #s or #S
          Short integer

          The remainder of the current  argument,  or  if  it  is
          empty,  the  next  existing  argument is converted to a
          short integer value. An error in conversion results  in
          a NOMATCH situation.

     #l or #L
          Long integer

          The remainder of the current  argument,  or  if  it  is
          empty,  the  next  existing  argument is converted to a
          long integer value. An error in conversion results in a
          NOMATCH situation.

Joerg Schilling    Last change: 15. Juli 1988                   1


Schily's LIBRARY FUNCTIONS                             GETARGS(3)

     #i or #I
          Integer

          The remainder of the current argument,  or,  if  it  is
          empty,  the  next  existing argument is converted to an
          int value. An error in conversion results in a  NOMATCH
          situation.

     ?    Character

          The next character  in  the  current  argument  is  the
          result. If there is no next char, the result is '\0'.

     *    String

          A pointer to the remainder of the current  argument  is
          returned. If there are no more data in the argument the
          next argument is used, and if there is  no  next  argu-
          ment, a NOMATCH situation exists.

     &    Function

          The address argument is a pointer to a function to call
          with  a  pointer  to the current argument. The function
          must   return   one   of   these   values:    YES = +1,
          NOMATCH = -1, ERROR = -2.

          Because the argument just after the address argument is
          passed  as  a  second  argument to the function, common
          routines can have their  results  in  different  places
          depending on which switch is invoked.

          Note: If a flag is found multiple times,  the  function
          is called each time.

     If no conversion is specified, the flag is assumed to  be  a
     Boolean indicator and the corresponding value is set to TRUE
     (+1).

     Descriptors are separated by a ',' (without  whitespace)  in
     the format string. They correspond in order to the resultant
     pointers, a1...an.

     It is an error to expect more than  one  conversion  from  a
     single match (e.g., "x#*" to attempt to get both the numeri-
     cal value and the actual string for the x flag); a -2  error
     will result if this is attempted.

     Although Boolean flags must appear exactly as they do in the
     format  string, the format string does not contain the lead-
     ing '-'.

Joerg Schilling    Last change: 15. Juli 1988                   2


Schily's LIBRARY FUNCTIONS                             GETARGS(3)

     Flags, where conversion is to take place, may appear  either
     as:

     -fvalue
     f=value
     f= value
     -f=value
     -f= value

     where f is the matching flag string. No additional effort is
     required to get these different ways of specifying values.


RETURNS

     +1   if an argument does not appear to be a flag.

     0    when all the arguments have been examined.

     -1   signifying a bad flag argument.

     -2   signifying a bad descriptor.


EXAMPLES


SEE ALSO

     getallargs(3), getfiles(3).


NOTES

     getargs() assumes the first argument is at av[0].   Commands
     are invoked by the system with the command name in av[0] and
     the first argument in av[1], so they must increment  av  and
     decrement ac before calling getargs().

     getargs() should only be  used  when  the  position  of  the
     switches  influences  how  an  argument  is processed (e.g.,
     format and pr commands), or when all switches must be before
     all  the arguments (e.g, write command). In other cases, use
     getallargs().


BUGS

     none


AUTHOR

     Joerg Schilling
     Seestr. 110
     D-13353 Berlin
     Germany

     Mail bugs and suggestions to:

Joerg Schilling    Last change: 15. Juli 1988                   3


Schily's LIBRARY FUNCTIONS                             GETARGS(3)

     schilling@fokus.gmd.de     or     js@cs.tu-berlin.de      or
     joerg@schily.isdn.cs.tu-berlin.de

Joerg Schilling    Last change: 15. Juli 1988                   4


Man(1) output converted with man2html


FhG Schily's Home VED powered