GNU Info

(libc.info)Getopt Long Options

---

Next: Getopt Long Option Example Prev: Example of Getopt Up: Getopt

---

Enter node , (file) or (file)node

Parsing Long Options with `getopt_long'
---------------------------------------

   To accept GNU-style long options as well as single-character options,
use `getopt_long' instead of `getopt'.  This function is declared in
`getopt.h', not `unistd.h'.  You should make every program accept long
options if it uses any options, for this takes little extra work and
helps beginners remember how to use the program.

 - Data Type: struct option
     This structure describes a single long option name for the sake of
     `getopt_long'.  The argument LONGOPTS must be an array of these
     structures, one for each long option.  Terminate the array with an
     element containing all zeros.

     The `struct option' structure has these fields:

    `const char *name'
          This field is the name of the option.  It is a string.

    `int has_arg'
          This field says whether the option takes an argument.  It is
          an integer, and there are three legitimate values:
          `no_argument', `required_argument' and `optional_argument'.

    `int *flag'
    `int val'
          These fields control how to report or act on the option when
          it occurs.

          If `flag' is a null pointer, then the `val' is a value which
          identifies this option.  Often these values are chosen to
          uniquely identify particular long options.

          If `flag' is not a null pointer, it should be the address of
          an `int' variable which is the flag for this option.  The
          value in `val' is the value to store in the flag to indicate
          that the option was seen.

 - Function: int getopt_long (int ARGC, char *const *ARGV, const char
          *SHORTOPTS, const struct option *LONGOPTS, int *INDEXPTR)
     Decode options from the vector ARGV (whose length is ARGC).  The
     argument SHORTOPTS describes the short options to accept, just as
     it does in `getopt'.  The argument LONGOPTS describes the long
     options to accept (see above).

     When `getopt_long' encounters a short option, it does the same
     thing that `getopt' would do: it returns the character code for the
     option, and stores the options argument (if it has one) in
     `optarg'.

     When `getopt_long' encounters a long option, it takes actions based
     on the `flag' and `val' fields of the definition of that option.

     If `flag' is a null pointer, then `getopt_long' returns the
     contents of `val' to indicate which option it found.  You should
     arrange distinct values in the `val' field for options with
     different meanings, so you can decode these values after
     `getopt_long' returns.  If the long option is equivalent to a short
     option, you can use the short option's character code in `val'.

     If `flag' is not a null pointer, that means this option should just
     set a flag in the program.  The flag is a variable of type `int'
     that you define.  Put the address of the flag in the `flag' field.
     Put in the `val' field the value you would like this option to
     store in the flag.  In this case, `getopt_long' returns `0'.

     For any long option, `getopt_long' tells you the index in the array
     LONGOPTS of the options definition, by storing it into
     `*INDEXPTR'.  You can get the name of the option with
     `LONGOPTS[*INDEXPTR].name'.  So you can distinguish among long
     options either by the values in their `val' fields or by their
     indices.  You can also distinguish in this way among long options
     that set flags.

     When a long option has an argument, `getopt_long' puts the argument
     value in the variable `optarg' before returning.  When the option
     has no argument, the value in `optarg' is a null pointer.  This is
     how you can tell whether an optional argument was supplied.

     When `getopt_long' has no more options to handle, it returns `-1',
     and leaves in the variable `optind' the index in ARGV of the next
     remaining argument.

   Since long option names were used before before the `getopt_long'
options was invented there are program interfaces which require programs
to recognize options like `-option value' instead of `--option value'.
To enable these programs to use the GNU getopt functionality there is
one more function available.

 - Function: int getopt_long_only (int ARGC, char *const *ARGV, const
          char *SHORTOPTS, const struct option *LONGOPTS, int *INDEXPTR)
     The `getopt_long_only' function is equivalent to the `getopt_long'
     function but it allows to specify the user of the application to
     pass long options with only `-' instead of `--'.  The `--' prefix
     is still recognized but instead of looking through the short
     options if a `-' is seen it is first tried whether this parameter
     names a long option.  If not, it is parsed as a short option.

     Assuming `getopt_long_only' is used starting an application with

            app -foo

     the `getopt_long_only' will first look for a long option named
     `foo'.  If this is not found, the short options `f', `o', and
     again `o' are recognized.