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

개요

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

getopt(3c)

Standard C Library Functions                                        getopt(3C)



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, optreset;

   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 Guidelines 3, 4, 5, 6, 7,
       9, and 10 which parallel those defined by application portability stan‐
       dards (see intro(1)). It can also be used by applications  which  addi‐
       tionally  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 appli‐
       cation.


       The argc and argv arguments are the argument count and  argument  array
       as  passed  to main (see exec(2)). The optstring argument specifies the
       acceptable options. For utilities wanting to conform to the Basic Util‐
       ity Syntax Guidelines, optstring is a string of recognized option char‐
       acters. 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
       following  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 argu‐
       ment  to  be processed. The optind variable is external and is initial‐
       ized to 1 before the first call to getopt().


       To restart scanning of the same argument vector or to initialize  scan‐
       ning  of  a  new argument vector, the caller must set optreset to 1 and
       optind to an appropriate value. For example, optind can be set to 1  to
       restart  scanning from the first argument. The external variable optre‐
       set is initialized to 0 before the first call to the getopt()  function
       and gets reset to 0 after optreset is used to restart scanning.


       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 incremented 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 fol‐
                  lowing  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  oper‐
       and),  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 optstring 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 opt‐
       string 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 argument 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 argument 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 substituting 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(7) 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 manda‐
       tory argument to the -a option and not that -a is missing  a  mandatory
       argument.  Indeed, the only time a missing option-argument can be reli‐
       ably detected is when the option is the final  option  on  the  command
       line and is not followed by any command arguments.


       It  is  a  violation  of the Basic Utility Command syntax standard (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 permitted 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(7) for descriptions of the following attributes:


       tab()  box; cw(2.75i) |cw(2.75i) lw(2.75i) |lw(2.75i) ATTRIBUTE TYPEAT‐
       TRIBUTE VALUE _ Interface StabilityCommitted _ MT-LevelUnsafe  _  Stan‐
       dardSee below.



       For the Basic Utility Command syntax is Standard, see standards(7).

SEE ALSO
       getopt(1),  getopts(1),  Intro(1),  getsubopt(3C),  gettext(3C), setlo‐
       cale(3C), attributes(7), environ(7), standards(7)



Oracle Solaris 11.4               17 Aug 2018                       getopt(3C)
맨 페이지 내용의 저작권은 맨 페이지 작성자에게 있습니다.
RSS ATOM XHTML 5 CSS3