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 characters 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 beginning  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  sgoptproblem  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.

                                                                                     subgetopt(3)