GETOPT(3C-SVR4)     RISC/os Reference Manual      GETOPT(3C-SVR4)



NAME
     getopt - get option letter from argument vector

SYNOPSIS
     #include <stdlib.h>

     int getopt (int argc, char * const *argv, const char *opt-
     string);

     extern char *optarg;

     extern int optind, opterr, optopt;

DESCRIPTION
     getopt returns the next option letter in argv that matches a
     letter in optstring.  It supports all the rules of the com-
     mand syntax standard [see intro(1)].  Since all new commands
     are intended to adhere to the command syntax standard, they
     should use getopts(1), getopt(3C), or getsubopts(3C) to
     parse positional parameters and check for options that are
     legal for that command.

     optstring must contain the option letters the command using
     getopt will recognize; if a letter is followed by a colon,
     the option is expected to have an argument, or group of
     arguments, which may be separated from it by white space.
     optarg is set to point to the start of the option argument
     on return from getopt.

     getopt places in optind the argv index of the next argument
     to be processed.  optind is external and is initialized to 1
     before the first call to getopt.  When all options have been
     processed (i.e., up to the first non-option argument),
     getopt returns EOF. The special option ``--'' (two hyphens)
     may be used to delimit the end of the options; when it is
     encountered, EOF is returned and ``--'' is skipped. This is
     useful in delimiting non-option arguments that begin with
     ``-'' (hyphen).

EXAMPLE
     The following code fragment shows how one might process the
     options and arguments for a command that takes: mutually
     exclusive options a and b, exactly one of which is required;
     an optional option i which takes an option-argument; and at
     least two arguments.

     main(int argc, char *argv[] /*, char envp[]*/)
               /* envp is unused in this example */
     {
         int             opt, aflg=0, bflg=0, iflg=0, errflg=0, retval ;
         char            *cmdname, *ifile, *ofile ;
         FILE            *infile, *outfile ;



                        Printed 11/19/92                   Page 1

GETOPT(3C-SVR4)     RISC/os Reference Manual      GETOPT(3C-SVR4)



         extern int      optind, opterr, errno ;
         extern char     *optarg ;

         setlabel("UX:example");
         cmdname = argv[0] ;
         opterr = 0 ;    /* inhibit getopt err msg */
         while ( (opt=getopt(argc,argv,"abi:")) != EOF ) {
             switch ( opt ) {
             case 'a' :
                 aflg += 1 ; break ;
             case 'b' :
                 bflg += 1 ; break ;
             case 'i' :
                 iflg += 1 ; ifile = optarg ; break ;
             default :   /* includes '?' case */
                 errflg += 1 ; break ;
             }
         }
         if ( errflg>0 || aflg+bflg!=1 || iflg>1 || argc-optind<2 ) {
             usage_err_exit(cmdname) ;
         }
         if ( iflg == 0 ) {
             infile = stdin ;
         } else if ( (infile=fopen(ifile,"r")) == NULL ) {
             open_err_exit(cmdname,ifile,errno) ;
         }
         for ( ; optind<argc ; optind+=1 ) {
             if ( (outfile=fopen(ofile=argv[optind],"r+")) == NULL ) {
                 open_err_exit(cmdname,ofile,errno) ;
             }
             if ( (retval=do_work(aflg,bflg,infile,outfile)) != 0 ) {
                 work_err_exit(cmdname,ofile,retval) ;
             }
             if ( fclose(outfile) != 0 ) {
                 close_err_exit(cmdname,ofile,errno) ;
             }
         }
         exit(0) ;
     }

SEE ALSO
     getsubopt(3C), pfmt(3C), setlabel(3C).
     getopts(1), intro(1) in the User's Reference Manual.

DIAGNOSTICS
     getopt prints an error message on the standard error and
     returns a ``?''  (question mark) when it encounters an
     option letter not included in optstring or no argument after
     an option that expects one.  This error message may be dis-
     abled by setting opterr to 0.  The value of the character
     that caused the error is in optopt.




 Page 2                 Printed 11/19/92

GETOPT(3C-SVR4)     RISC/os Reference Manual      GETOPT(3C-SVR4)



     The message is printed in the standard error format.
     getopt() supports localized output messages.  If the
     appropriate translated system messages are installed on the
     system, they are selected by the latest call to setlocale()
     (using the LC_ALL or LC_MESSAGES categories).

     The label defined by a call to setlabel() will be used if
     available, otherwise the name of the utility (argv[0]) will
     be used.

NOTES
     The library routine getopt does not fully check for manda-
     tory arguments.  That is, given an option string a:b and the
     input -a -b, getopt assumes that -b is the mandatory argu-
     ment to the option -a and not that -a is missing a mandatory
     argument.

     It is a violation of the command syntax standard [see
     intro(1)] for options with arguments to be grouped with
     other options, as in cmd -aboxxx file, where a and b are
     options, o is an option that requires an argument, and xxx
     is the argument to o.  Although this syntax is permitted in
     the current implementation, it should not be used because it
     may not be supported in future releases. The correct syntax
     is cmd -ab -oxxx file.






























                        Printed 11/19/92                   Page 3