getopt(3c) 맨 페이지 - 윈디하나의 솔라나라

개요

섹션
맨페이지이름
검색(S)

getopt

Name
     getopt - command option parsing

Synopsis
  SVID3, XPG3
     #include <stdio.h>

     int getopt(int argc, char * const argv[], const char *optstring);


     extern char *optarg;


     extern int optind, opterr, optopt;


  POSIX.2, XPG4, SUS, SUSv2, SUSv3
     #include <unistd.h>

     int getopt(int argc, char * const argv[], const char *optstring);


     extern char *optarg;


     extern int optind, opterr, optopt;

Description
     The getopt() function is a command line parser that  can  be
     used by applications that follow Basic Utility Syntax Guide-
     lines 3, 4, 5, 6, 7, 9, and 10 which parallel those  defined
     by  application portability standards (see intro(1)). It can
     also be used by applications which additionally  follow  the
     Command  Line  Interface  Paradigm  (CLIP)  syntax extension
     guidelines 15, 16, and 17. It partially  enforces  guideline
     18  by  requiring that every option has a short-name, but it
     allows multiple long-names to be associated with an  option.
     The  remaining  guidelines are not addressed by getopt() and
     are the responsibility of the application.


     The argc and argv arguments are the argument count and argu-
     ment  array  as  passed to main (see exec(2)). The optstring
     argument specifies the  acceptable  options.  For  utilities
     wanting  to  conform to the Basic Utility Syntax Guidelines,
     optstring is a string of recognized option  characters.  All
     option  characters allowed by Utility Syntax Guideline 3 are
     allowed in optstring. If a character is followed by a  colon
     (:),  the  option  is  expected  to have an option-argument,
     which can be separated from it by  white  space.   Utilities
     wanting  to  conform  to  the  extended  CLIP guidelines can
     specify long-option equivalents to short options by  follow-
     ing  the  short-option character (and optional colon) with a
     sequence of strings,  each  enclosed  in  parentheses,  that
     specify the long-option aliases.


     The getopt() function returns the short-option character  in
     optstring that corresponds to the next option found in argv.


     The getopt() function places in optind the argv index of the
     next argument to be processed. The optind variable is exter-
     nal and is  initialized  to  1  before  the  first  call  to
     getopt().  The getopt() function sets the variable optarg to
     point to the start of the option-argument as follows:

         o    If the option is a short option and that  character
              is  the last character in the argument, then optarg
              contains the next element of argv,  and  optind  is
              incremented by 2.

         o    If the option is a short option and that  character
              is  not  the  last  character in the argument, then
              optarg points to the string  following  the  option
              character  in  that  argument, and optind is incre-
              mented by 1.

         o    If the option is a long option  and  the  character
              equals  is  not  found in the argument, then optarg
              contains the next element of argv,  and  optind  is
              incremented by 2.

         o    If the option is a long option  and  the  character
              equals is found in the argument, then optarg points
              to the string following  the  equals  character  in
              that argument and optind is incremented by 1.


     In all cases, if the resulting value of optind is  not  less
     than  argc,  this  indicates  a  missing option-argument and
     getopt() returns an error indication.


     When all options have been processed (that  is,  up  to  the
     first  operand), getopt() returns -1. The special option "--
     "(two hyphens) can  be  used  to  delimit  the  end  of  the
     options;  when it is encountered, -1 is returned and "--" is
     skipped. This is useful in delimiting  non-option  arguments
     that begin with "-" (hyphen).

     If getopt() encounters a short-option character or  a  long-
     option  string  not  described  in the opstring argument, it
     returns the question-mark (?) character.  If  it  detects  a
     missing  option-argument,  it also returns the question-mark
     (?) character, unless the first character of  the  optstring
     argument was a colon (:), in which case getopt() returns the
     colon (:) character. For short options,  getopt()  sets  the
     variable  optopt  to  the  option  character that caused the
     error. For long options, optopt is set  to  the  hyphen  (-)
     character  and  the  failing  long  option can be identified
     through argv[optind-1]. If the application has not  set  the
     variable opterr to 0 and the first character of optstring is
     not a colon (:), getopt() also prints a  diagnostic  message
     to stderr.

Return Values
     The getopt() function  returns  the  short-option  character
     associated with the option recognized.


     A colon (:) is returned if getopt() detects a missing  argu-
     ment and the first character of optstring was a colon (:).


     A question mark (?) is returned if  getopt()  encounters  an
     option not specified in optstring or detects a missing argu-
     ment and the first character of optstring was  not  a  colon
     (:).


     Otherwise, getopt() returns -1 when all command line options
     are parsed.

Errors
     No errors are defined.

Examples
     Example 1 Parsing Command Line Options


     The following code fragment shows how you might process  the
     arguments for a utility that can take the mutually-exclusive
     options a and b and the options  f  and  o,  both  of  which
     require arguments:


       #include <unistd.h>

       int
       main(int argc, char *argv[ ])
       {
           int c;
           int bflg, aflg, errflg;
           char *ifile;
           char *ofile;
            . . .
           while ((c = getopt(argc, argv, ":abf:o:")) != -1) {
               switch(c) {
               case `a':
                   if (bflg)
                       errflg++;
                   else
                       aflg++;
                   break;
               case `b':
                   if (aflg)
                       errflg++;
                   else {
                       bflg++;
                       bproc();
                   }
                   break;
               case `f':
                   ifile = optarg;
                   break;
               case `o':
                   ofile = optarg;
                   break;
               case `:':   /* -f or -o without operand */
                   fprintf(stderr,
                          "Option -%c requires an operand\n", optopt);
                   errflg++;
                   break;
               case `?':
                   fprintf(stderr,
                          "Unrecognized option: -%c\n", optopt);
                   errflg++;
               }
           }
           if (errflg) {
               fprintf(stderr, "usage: . . . ");
               exit(2);
           }
           for ( ; optind < argc; optind++) {
               if (access(argv[optind], R_OK)) {
           . . .
       }



     This code accepts any of the following as equivalent:


       cmd -ao arg path path
       cmd -a -o arg path path
       cmd -o arg -a path path
       cmd -a -o arg -- path path
       cmd -a -oarg path path
       cmd -aoarg path path


     Example 2 Check Options and Arguments.


     The following example parses a set of command  line  options
     and  prints  messages to standard output for each option and
     argument that it encounters.


       #include <unistd.h>
       #include <stdio.h>
       ...
       int c;
       char *filename;
       extern char *optarg;
       extern int optind, optopt, opterr;
       ...
       while ((c = getopt(argc, argv, ":abf:")) != -1) {
           switch(c) {
           case `a':
                printf("a is set\n");
                break;
           case `b':
                printf("b is set\n");
                break;
           case `f':
                filename = optarg;
                printf("filename is %s\n", filename);
                break;
           case `:':
                printf("-%c without filename\n", optopt);
                break;
           case `?':
                printf("unknown arg %c\n", optopt);
                break;
           }
       }



     This example can be expanded to be CLIP-compliant by substi-
     tuting the following string for the optstring argument:


       :a(ascii)b(binary)f:(in-file)o:(out-file)V(version)?(help)

     and by replacing the `?' case processing with:


       case `V':
           fprintf(stdout, "cmd 1.1\n");
           exit(0);
       case `?':
           if (optopt == `?') {
               print_help();
               exit(0);
           }
           if (optopt == `-')
               fprintf(stderr,
                   "unrecognized option: %s\n", argv[optind-1]);
           else
               fprintf(stderr,
                   "unrecognized option: -%c\n", optopt);
           errflg++;
           break;



     and by replacing the `:' case processing with:


       case `:':   /* -f or -o without operand */
           if (optopt == `-')
               fprintf(stderr,
                   "Option %s requires an operand\n", argv[optind-1]);
           else
               fprintf(stderr,
                   "Option -%c requires an operand\n", optopt);
           errflg++;
           break;



     While not encouraged by  the  CLIP  specification,  multiple
     long-option  aliases  can  also  be assigned as shown in the
     following example:


       :a(ascii)b(binary):(in-file)(input)o:(outfile)(output)V(version)?(help)

Environment Variables
     See environ(5) for descriptions of the following environment
     variables  that  affect  the  execution  of  getopt(): LANG,
     LC_ALL, and LC_MESSAGES.

     LC_CTYPE
                 Determine the locale for the  interpretation  of
                 sequences of bytes as characters in optstring.

Usage
     The getopt() function does not  fully  check  for  mandatory
     arguments  because  there  is no unambiguous algorithm to do
     so. Given an option string a:b and the input -a -b, getopt()
     assumes  that  -b is the mandatory argument to the -a option
     and not that -a is missing a  mandatory  argument.   Indeed,
     the  only  time  a  missing  option-argument can be reliably
     detected is when the option is the final option on the  com-
     mand line and is not followed by any command arguments.


     It is a violation of the Basic Utility Command syntax  stan-
     dard (see Intro(1)) for options with arguments to be grouped
     with other options, as in cmd -abo filename , where a and  b
     are  options,  o is an option that requires an argument, and
     filename is the argument to o. Although this syntax is  per-
     mitted  in the current implementation, it should not be used
     because it may not be supported  in  future  releases.   The
     correct syntax to use is:

       cmd -ab -o filename

Attributes
     See attributes(5) for descriptions of the  following  attri-
     butes:



     tab() box; cw(2.75i) |cw(2.75i) lw(2.75i) |lw(2.75i)  ATTRI-
     BUTE  TYPEATTRIBUTE  VALUE  _ Interface StabilityCommitted _
     MT-LevelUnsafe _ StandardSee below.



     For the Basic Utility Command syntax is Standard, see  stan-
     dards(5).

See Also
     Intro(1), getopt(1), getopts(1), getsubopt(3C), gettext(3C),
     setlocale(3C), attributes(5), environ(5), standards(5)
맨 페이지 내용의 저작권은 맨 페이지 작성자에게 있습니다.
RSS ATOM XHTML 1.0 CSS3