subgetopt(3)           C Library Functions           subgetopt(3)

     subgetopt - get option character from command line

     #include <subgetopt.h>

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

     int sgopt(argc,argv,opts);

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

     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

     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.

     sgoptproblem  should  be  used  only  when  sgopt returns ?.
     sgoptind and sgoptpos are defined all the time.  sgoptarg is

SunOS 5.5                 Last change:                          1

subgetopt(3)           C Library Functions           subgetopt(3)

     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);
             printf("missing arg, opt %c\n",sgoptproblem);

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

     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 sec-
     ondary 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.

     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,

SunOS 5.5                 Last change:                          2

subgetopt(3)           C Library Functions           subgetopt(3)

     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 cur-
     rent cmdarg is null, or past argc, sgopt  sets  sgoptproblem
     to c and returns ?.  Otherwise sgopt moves to the next argu-
     ment and returns c.

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

     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.

     subgetopt version 0.9, 931129.

     Placed into the public domain by Daniel J. Bernstein.

SunOS 5.5                 Last change:                          3