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

개요

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

getopt_long(3c)

Standard C Library Functions                                   getopt_long(3C)



NAME
       getopt_long, getopt_long_only, getopt_clip - parse long command options

SYNOPSIS
       #include <getopt.h>

       int getopt_long(int argc, char * const *argv, const char *shortopts,
            const struct option *longopts, int *indexptr);


       int getopt_long_only(int argc, char * const *argv, const char *shortopts,
            const struct option *longopts, int *indexptr);


       int getopt_clip(int argc, char * const *argv, const char *shortopts,
            const struct option *longopts, int *indexptr);


       extern char *optarg;


       extern int optind, opterr, optopt;

DESCRIPTION
       These  functions are provided as a porting aid for GNU/Freeware/OpenBSD
       utilities. The getopt_long() function is intended to be as closely com‐
       patible with the GNU and OpenBSD implementations as possible, but since
       these public implementations differ in some corner  cases,  it  is  not
       possible  to be fully compatible with both. The differences are enumer‐
       ated in the NOTES section.


       The getopt_long() function is an aid for implementing the  GNU  command
       line argument conventions. See the GNU documentation for the details of
       these conventions (glibc 2.2.3). Note that the GNU conventions are  not
       POSIX-conforming.  Most notably, the GNU conventions allow for optional
       option-arguments and do not enforce that operands must  follow  options
       on the command line.


       The   getopt_clip()   function   provides   an   interface  similar  to
       getopt_long() except that it implements the Sun CLIP convention,  which
       is slightly more restrictive than the GNU/Freeware conventions. CLIP is
       modeled after the GNU/Freeware conventions but removes POSIX violations
       and  syntactic  ambiguities (see Intro(1)). Specifically, getopt_clip()
       is a command line parser that can be used by applications  that  follow
       the  Command Line Interface Paradigm or CLIP syntax guidelines 3, 4, 5,
       6, 7, 9, 10, 15, and 16. The remaining guidelines are not addressed  by
       getopt_clip() and are the responsibility of the application.


       The  getopt_long()  function  is  similar  to getopt(3C) except that it
       accepts options in two forms: words and characters, also referred to as
       long options and short options.


       The  getopt_long()  function can be used in two ways. In the first way,
       every long option understood by the program is mapped to a single char‐
       acter  that  is usually a corresponding short option. The option struc‐
       ture is used only to translate from long options to short  options.  In
       the  second  way,  a  long  option  sets a flag specified in the option
       structure, or stores a pointer to the  command  line  argument  in  the
       address passed to it for options that take arguments. These two methods
       apply individually to each long option. Both methods can be used in the
       same application.


       The  getopt_long()  function  accepts  command  lines  that  interleave
       options and operands. The getopt_long() function reorders the  elements
       of  the  argv  argument  such that when all command line arguments have
       been processed, all operands follow  options  (and  their  option-argu‐
       ments)  in  the  argv array and optind points to the first operand. The
       order of options relative to other options  and  operands  relative  to
       other operands is maintained. The argument "--" is accepted as a delim‐
       iter indicating the end of options. No  argument  reorder  occurs  past
       this  delimiter. Argument reordering can not be unambiguously performed
       in all cases. The getopt_long() function depends on a number of  inter‐
       nal  heuristics  to perform the reordering. The argc and argv arguments
       are the argument count and argument array  as  passed  to  main()  (see
       exec(2)).


       The  shortopts argument contains the short-option characters recognized
       by the command using these functions. If a  letter  is  followed  by  a
       colon  (:),  the  option  is  expected  to have an option-argument that
       should be separated from it by white space. If a character is  followed
       by  two  colons (::), the option takes an optional option-argument. Any
       text after the option name it is returned in optarg; otherwise,  optarg
       is  set  to  0. A whitespace character can never be used to separate an
       optional option-argument from its associated option. If shortopts  con‐
       tains  the  character  "W" followed by a semicolon (;), then -W  foo is
       treated as the long option --foo.


       If the first character of the shortopts argument is the plus sign  (+),
       getopt_long()  enforces  the  POSIX  requirement  that  operands follow
       options on the command line by returning -1 and stopping argument  pro‐
       cessing  upon  encountering  the first operand (or "--"). This behavior
       can also be specified by setting the environment variable  POSIXLY_COR‐
       RECT.


       A hyphen (-) as the first character of the shortopts argument specifies
       that options and operands can be intermixed in  argv  but  no  argument
       reordering  is  performed. Operands are returned as arguments to option
       '\1', and option processing does not stop until "--" or the end of argv
       is found.


       If  the  first  character  of the shortopts argument (after a potential
       plus or minus character) is  a  colon  (:),  a  colon  is  returned  by
       getopt_long()  in response to a missing argument; otherwise, a question
       mark (?) is returned for this condition.


       The longopts argument describes the long options to accept.  It  is  an
       array  of struct option structures, one for each long option. The array
       is terminated with an element containing all zeros.


       The struct option structure contains the following members:

       const char *name    Contains a pointer to the name of the option.


       int has_arg         Specifies whether the option takes an argument. The
                           possible   values,   defined   in  <getopt.h>,  are
                           no_argument, optional_argument, and  required_argu‐
                           ment.


       int *flag           Contains the address of an int variable that is the
                           flag for this option. The value contained in val is
                           stored in this location to indicate that the option
                           was seen. If flag is a null pointer, then the value
                           contained  in  val  is returned when this option is
                           encountered, otherwise zero is returned.


       int val             Contains the value to be  stored  at  the  variable
                           pointed  to by flag or returned by getopt_long() if
                           flag is a null pointer.



       For any long option, getopt_long() returns the index in the array  lon‐
       gopts  of the options definition by storing it in indexptr. The name of
       the option  can  be  retrieved  with  longopts[(*indexptr)].name.  Long
       options  can be distinguished either by the values in their val members
       or by their indices. The indexptr variable can  also  distinguish  long
       options  that  set  flags.  The  value of indexptr after encountering a
       short option is undefined.


       If an option has an argument, the optarg  global  variable  is  set  to
       point to the start of the option argument on return from getopt_long();
       otherwise it is set to null. A long option can take an argument in  one
       of two forms: --option=arg or --option arg. If the long option argument
       is optional, only the "--option=arg" form can be used  to  specify  the
       option   argument.   No  argument  is  specified  by  the  simple  form
       "--option". The form "--option="  specifies  an  empty  string  as  the
       option argument.


       Long-option  names  can be abbreviated if the abbreviation is unique or
       an exact match for some defined option. An exact match takes precedence
       over an abbreviated match. Thus, if foo and foobar are acceptable long-
       option names, then specifying --foo on the command line always  matches
       the former. Specifying --f or --fo would not be accepted as a match for
       either.


       The getopt_long() function places in optind the argv index of the  next
       argument to be processed. The optind global variable is external and is
       initialized to 1 before the  first  call  to  getopt_long().  When  all
       options  have been processed (that is, up to the first non-option argu‐
       ment), getopt_long() 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 option is useful in  delimiting
       non-option arguments that begin with "-" (hyphen).


       If  getopt_long()  encounters a short option character shortopts string
       or a long option not described in the longopts array,  it  returns  the
       question  mark (?) character. It also returns a question mark (?) char‐
       acter in response to a missing option argument unless the first charac‐
       ter  of shortopts is a colon (:) (or the second character, if the first
       character is either a plus (+) or  a  minus  (-)),  in  which  case  it
       returns  a  colon  (:).  In either case, if the application has not set
       opterr to 0 and the first character of shortopts is not  a  colon  (:),
       getopt_long() prints a diagnostic message to stderr.


       The  getopt_long_only()  function  is  equivalent  to the getopt_long()
       function except that it allows the user of the application to pass long
       options  with only a single hyphen (-) instead of "--". The "--" prefix
       is still recognized. However, when a single hyphen (-) is  encountered,
       getopt_long_only()  attempts  to  match this argument to a long option,
       including abbreviations of the long option. If  a  long  option  starts
       with  the same character as a short option, a single hyphen followed by
       that character (and no other characters) will be recognized as a  short
       option.  Use  of  getopt_long_only() is strongly discouraged by Sun and
       GNU for new applications.


       The behavior of getopt_clip() differs from that of getopt_long() in the
       following ways:

           o      The   getopt_clip()   function  does  not  perform  argument
                  reordering. The getopt_clip() function always  enforces  the
                  POSIX  behavior  that all options should precede operands on
                  the  command  line.  Specifically,  getopt_clip()  does  not
                  reorder  arguments  but returns -1 and stops processing upon
                  encountering the first operand argument.


           o      The environment variable  POSIXLY_CORRECT  is  ignored  (the
                  getopt_clip() function behaves as though it were set.)


           o      The  plus and minus characters do not have a special meaning
                  as the first character of the shortopts argument.  They  are
                  treated  as any other character (other than the colon) would
                  be treated.


           o      Optional option-arguments are not allowed. The  behavior  of
                  getopt_clip()  when  optional_argument  is  specified as the
                  value of has_arg in the longopts argument or  double  colons
                  are included in the shortopts argument is unspecified.


           o      Long-option abbreviations are not recognized.


           o      Short  options are required to have at least one long-option
                  equivalent. That is, each character in shortopts must appear
                  as  the  val  member in one or more option structures. Simi‐
                  larly, each long option must have a short option equivalent,
                  meaning  that  the  val member of each option structure must
                  appear in the shortopts string. If  these  requirements  are
                  not met, getopt_clip() returns -1 and sets errno to EINVAL.


RETURN VALUES
       For  short options (other than -W when W; is in shortopts), these func‐
       tions return the next option character specified on the  command  line.
       For  long  options,  the value returned by these functions depends upon
       the value of the flag structure element for the identified  option.  If
       flag  is NULL, the value contained in the val structure element for the
       long option encountered on the command  line  is  returned.  Otherwise,
       these functions return 0 (and the value specified in the val member for
       the long option is stored into the location pointed to by  flag).  When
       W;  is  in  shortopts and -W is encountered in the command line and the
       option argument to -W matches a long-option name, the return state from
       these functions is as if the long option had been encountered. However,
       if no argument is specified to the long option, optarg is  set  to  the
       option  argument  of -W (the long-option name or unique prefix). If the
       option argument of -W does not match a long option (or unique  prefix),
       the return state is as for any other short option.


       A colon (:) is returned if getopt_long() detects a missing argument and
       the first character of shortopts (other than a possible initial "+"  or
       "-") was a colon (':').


       A  question  mark (?) is returned if getopt_long() encounters an option
       letter not included in shortopts or detects a missing argument and  the
       first character of shortopts (other than a possible initial "+" or "-")
       was not a colon (:).


       The getopt_clip() function expects all short options  to  have  one  or
       more  long-option  equivalent  and  all  long options to have one short
       option equivalent (see NOTES for details). If  proper  equivalents  are
       not found, getopt_clip() returns -1 and sets errno to EINVAL.

ERRORS
       The getopt_clip() function will fail if:

       EINVAL    A short option does not have at least one long-option equiva‐
                 lent, or a long option does not  have  at  least  one  short-
                 option equivalent.


EXAMPLES
       Example 1 Example using getopt().


         #include <unistd.h>
         #include <getopt.h>

         /* Flag set by `--verbose'. */
         static int verbose_flag;

         int
         main (int argc, char **argv)
         {
           int c;

           while (1) {
             static struct option long_options[] = {
               /* These options set a flag. */
               {"verbose", no_argument, &verbose_flag, 1},
               {"brief",   no_argument, &verbose_flag, 0},
               /* The following options don't set a flag. */
               {"add",     no_argument, NULL, 'a'},
               {"append",  no_argument, NULL, 'b'},
               {"delete",  required_argument, NULL, 'd'},
               {"create",  required_argument, NULL, 'c'},
               {"file",    required_argument, NULL, 'f'},
               {0, 0, 0, 0}
             };
             /* getopt_long stores the option index here. */
             int option_index = 0;

             c = getopt_long (argc, argv, "abc:d:f:",
                              long_options, &option_index);

             /* Detect the end of the options. */
             if (c == -1)
               break;

             switch (c) {
               case 0:
                 /* (In this example) only options which set */
                 /* a flag return zero, so do nothing. */
                 break;

               case 'a':
                 puts ("option --add (-a)\n");
                 break;

               case 'b':
                 puts ("option --append (-b)\n");
                 break;

               case 'c':
                 printf ("option --create (-c) with value `%s'\n", optarg);
                 break;

               case 'd':
                 printf ("option --delete (-d) with value `%s'\n", optarg);
                 break;

               case 'f':
                 printf ("option --file (-f) with value `%s'\n", optarg);
                 break;

               case '?':
                 /* getopt_long already printed an error message. */
                 break;

               default:
                 abort ();
             }
           }

           /* Instead of reporting `--verbose'
              and `--brief' as they are encountered,
              we report the final status resulting from them. */
           if (verbose_flag)
             puts ("verbose flag is set");

           /* Print any remaining command line arguments (not options). */
           if (optind < argc) {
               printf ("non-option ARGV-elements: ");
               while (optind < argc)
                 printf ("%s ", argv[optind++]);
               putchar ('\n');
             }

           exit (0);
         }




ENVIRONMENT VARIABLES
       See  environ(7) for descriptions of the following environment variables
       that affect the execution of getopt_long(): LANG, LC_ALL,  and  LC_MES‐
       SAGES.

       POSIXLY_CORRECT    When  set  (and the first character of the shortopts
                          argument is neither a plus or minus sign), the POSIX
                          rule  that  all  operands must follow all options is
                          enforced.  Option  processing  terminates  when  the
                          first  operand  is  encountered.  The  getopt_clip()
                          function ignores the setting of POSIXLY_CORRECT  and
                          always behaves as if it were set.


       LC_CTYPE           Determine  the  locale  for  the  interpretation  of
                          sequences of bytes as characters  in  shortopts  and
                          the longopts[].name structure members.


USAGE
       The getopt_long() 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_long() assumes that -b is the
       mandatory argument to the -a option and not that -a is missing a manda‐
       tory  argument.  Indeed, the only time a missing option argument can be
       reliably detected is when the option is the final option on the command
       line and is not followed by any command arguments.

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


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

NOTES
       Use  of getopt_long() is discouraged for applications targeted strictly
       for Solaris. It should  be  used  only  for  applications  targeted  at
       Solaris  and platforms that adhere to the GNU command line conventions.
       The getopt_long_only() function is provided  by  Solaris  and  GNU  for
       legacy  applications and its use is discouraged by both current conven‐
       tions.


       The differences between the Solaris/GNU and OpenBSD versions  of  these
       functions are as follows:

           o      The handling of the hyphen (-) as the first character of the
                  option  string  in  presence  of  the  environment  variable
                  POSIXLY_CORRECT:

                  Solaris/GNU    Operands  are returned as arguments to option
                                 '\1', and option  processing  does  not  stop
                                 until "--" or the end of argv is found.


                  OpenBSD        obeys  POSIXLY_CORRECT and stops at the first
                                 non-option.



           o      The handling of the hyphen (-) within the shortopts  parame‐
                  ter string when not the first character.

                  Solaris/GNU    treats  a  single  hyphen  (-) on the command
                                 line as an operand.


                  OpenBSD        treats a single hyphen  (-)  on  the  command
                                 line as an option. BSD recognizes this behav‐
                                 ior as incorrect, but maintains it  for  com‐
                                 patibility.



           o      The  return  value in the event of a missing argument if the
                  first character after "+" or "-" in the option string is not
                  a colon (:)

                  Solaris/GNU    returns "?".


                  OpenBSD        returns ":" (since OpenBSD's getopt does).



           o      The setting optopt for long options with flag != NULL:

                  Solaris/GNU    sets optopt to val.


                  OpenBSD        sets  optopt  to  0 (since val would never be
                                 returned).



           o      The setting of optarg for long options without  an  argument
                  that are invoked with -W (W; in option string):

                  Solaris/GNU    sets  optarg to the option name (the argument
                                 of -W).


                  OpenBSD        sets optarg to NULL (the argument of the long
                                 option).



           o      The  handling  of  -W with an argument that is not (a prefix
                  to) a known long option (W; in option string):

                  Solaris/GNU    returns 'W' with optarg set  to  the  unknown
                                 option.


                  OpenBSD        treats  as  an  error  (unknown  option)  and
                                 returns "?" with optopt set to 0  and  optarg
                                 set to NULL.



           o      The error messages are different (all).


           o      The  implementations  do  not permute the argument vector at
                  the same points in the calling sequence.  The  aspects  nor‐
                  mally  used  by  the  caller (ordering after -1 is returned,
                  value of optind relative to current positions) are the same.
                  Applications  should  not  depend  upon  the ordering of the
                  argument vector before -1 is returned.




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