MAN PAGES FOR QMAIL 1.03

NAME

     subgetopt - get option character from command line

SYNTAX

     #include <subgetopt.h>

     char *sgoptarg;
     int sgoptind;
     int sgoptpos;
     int sgoptdone;
     int sgoptproblem;

     int sgopt(argc,argv,opts);

     int argc;
     char **argv;
     char *opts;

DESCRIPTION

     sgopt returns the next valid command-line  option  character
     from argv.

     Valid option characters are listed in the opts string.  opts
     may  be  empty.   A  character  in opts may be followed by a
     colon, in which case it  takes  an  option  argument.  Avoid
     using the characters ?, :, and - as option characters.

     Below option argument is abbreviated as optarg and  command-
     line argument is abbreviated as cmdarg.

     Options are listed in cmdargs which begin with a minus sign.
     Several  options  which  do not take optargs may be combined
     into one cmdarg.

     An option which takes an optarg may be handled in two  ways.
     If  it  appears at the very end of a cmdarg, then the entire
     next cmdarg is the optarg.  But if there are any  characters
     in the cmdarg after the option character, then those charac-
     ters form the optarg.  The optarg is returned  in  sgoptarg.
     Next  time  sgopt  looks  at  the  cmdarg  which follows the
     optarg.

     If a cmdarg does not begin with a hyphen, or if it is a lone
     hyphen  not followed by any characters, or if it begins with
     two hyphens, then it terminates option processing, and sgopt
     returns  an  appropriate  code.   If  there are two hyphens,
     sgopt will advance attention to the next cmdarg, so  it  can
     be called again to read further options.

PROPER USAGE

     sgoptproblem should be  used  only  when  sgopt  returns  ?.
     sgoptind and sgoptpos are defined all the time.  sgoptarg is
     defined all the time; it  is  null  unless  sgopt  has  just
     returned an option with optarg.

     sgopt is typically used as follows.

     #include <subgetopt.h>

     main(argc,argv) int argc; char **argv; { int opt;

     while ((opt = sgopt(argc,argv,"a:s")) != sgoptdone)
       switch(opt) {
         case 'a':
           printf("opt a with optarg %s\n",sgoptarg); break;
         case 's':
           printf("opt s with no optarg\n"); break;
         case '?':
           if (argv[sgoptind] && (sgoptind < argc))
             printf("illegal opt %c\n",sgoptproblem);
           else
             printf("missing arg, opt %c\n",sgoptproblem);
           exit(1);
       }

     argv += sgoptind;
     while (*argv) printf("argument %s\n",*argv++);
     exit(0);
     }

     The end of the command line is marked by either argc,  or  a
     null pointer in argv, whichever comes first.  Normally these
     two markers coincide, so it is redundant to  test  for  both
     argv[sgoptind]  and  sgoptind  <  argc. The above code shows
     both tests as an illustration.

     Multiple option sets: One useful technique is to call  sgopt
     with  a  primary  opts until it returns EOF, then call sgopt
     with a secondary opts until it returns EOF.   The  user  can
     provide  primary  options,  then  a  double hyphen, and then
     secondary options.  No special handling is needed if some or
     all  of  the options are omitted.  The same technique can be
     used for any number of option sets in series.

     Multiple command lines: Before parsing a new argv, make sure
     to set sgoptind and sgoptpos back to 1 and 0.

PARSING STAGES

     sgopt keeps track of its position in argv with sgoptind  and
     sgoptpos,  which  are  initialized  to 1 and 0.  It looks at
     argv[sgoptind][sgoptpos] and following characters.

     sgopt indicates  that  no  more  options  are  available  by
     returning  sgoptdone, which is initialized to SUBGETOPTDONE,
     which is defined as -1.

     sgopt begins by setting optarg to null.

     Ending conditions: If argv is null, or  sgoptind  is  larger
     than  argc,  or  the  current cmdarg argv[sgoptind] is null,
     then sgopt returns optdone.

     Stage one: If the current character is zero, sgopt moves  to
     the beginning of the next cmdarg.  It then checks the ending
     conditions again.

     Stage two: If the current position is the  begining  of  the
     cmdarg,  sgopt  checks  whether  the  current character is a
     minus sign.  If not it returns optdone.  It  then  moves  to
     the  next character.  If that character is zero, sgopt moves
     back to the beginning of the cmdarg, and returns  sgoptdone.
     If  the character is a minus sign, sgopt moves to the begin-
     ning of the next cmdarg, and returns sgoptdone.

     Stage three: sgopt records the  current  character,  c,  and
     moves to the next character.  There are three possibilities:
     (1) c is an option character without optarg in opts, or  (2)
     c  is an option character with optarg in opts, or (3) c does
     not appear in opts.

     (1) If c appears as an option character  without  optarg  in
     opts, sgopt returns c.

     (2) If c appears as an option character with optarg in opts,
     sgopt  sets  sgoptarg  to the current position, and moves to
     the next cmdarg.  If sgoptarg is nonempty, sgopt returns c.

     Then sgopt sets sgoptarg to  the  current  cmdarg.   If  the
     current  cmdarg is null, or past argc, sgopt sets sgoptprob-
     lem to c and returns ?.  Otherwise sgopt moves to  the  next
     argument and returns c.

     (2) If c does not appear in opts, sgopt sets sgoptproblem to
     c and returns ?.

SYNTAX NOTE

     sgopt is actually a macro abbreviation for  subgetopt.   The
     external  sg  variables  are  also macros for subget.  These
     macros are defined in <subgetopt.h>, unless SUBGETOPTNOSHORT
     is defined when <subgetopt.h> is included.

VERSION

     subgetopt version 0.9, 931129.

AUTHOR

     Placed into the public domain by Daniel J. Bernstein.