int getopt(int argc, char * const argv[], const char *optstring); extern char *optarg; extern int optind, opterr, optopt; |
GNU supports the following extensions of getopt:
int getopt_long(int argc, char * const argv[],
const char *optstring,
const struct option *longopts, int *longindex);
int getopt_long_only(int argc, char * const argv[],
const char *optstring,
const struct option *longopts, int *longindex); |
The getopt() function parses command line arguments. GNU and POSIX specifications for this function vary in the following areas.
GNU specifies that:
an element of argv that starts with "-" (and is not exactly "-" or "--") is an option element.
characters of an option element, aside from the initial "-", are option characters.
POSIX specifies that:
applications using getopt() must obey the following syntax guidelines:
(1) option name is a single alphanumeric character from the portable character set
(2) option is preceded by the "-" delimiter character
(3) options without option-arguments should be accepted when grouped behind one "-" delimiter
(4) each option and option-argument is a separate argument
(5) option-arguments are not optional
(6) all options should precede operands on the command line
(7) the argument "--" is accepted as a delimiter indicating the end of options and the consideration of subsequent arguments, if any, as operands
historical implementations of getopt() support other characters as options as an allowed extension, but applications that use extensions are not maximally portable.
support for multi-byte option characters is only possible when such characters can be represented as type int.
applications that call any utility with a first operand starting with "-" should usually specify "--" to mark the end of the options. Standard utilities that do not support this guideline indicate that fact in the OPTIONS section of the utility description.
GNU specifies that:
if a character is followed by two colons, the option takes an optional arg; if there is text in the current argv-element, it is returned in optarg, otherwise optarg is set to zero.
if optstring contains W followed by a semi-colon, then -W foo is treated as the long option --foo. (Not available with libraries before GNU libc 2.)
getopt_long() works like getopt() except that it also accepts "long options", or, options that are preface with two dashes instead of one.
long option names may be abbreviated if the abbreviation is unique or an exact match for some defined option.
a long option may take a parameter, of the form --arg=param or --arg param.
getopt_long_only() works like getopt_long(), except that both "-" and "--" indicate long option. If an option that starts with "-" (not "--") doesn't match a long option, but does match a short option, it is parsed instead as a short option.
POSIX specifies that:
the -W option is reserved for implementation extensions.
GNU specifies the following getopt() return values:
the next option character is returned, if found successfully.
colon character (":") is returned if a parameter is missing for one of the options.
question mark ("?") is returned if an unknown option character is encountered.
"-1" is returned for the end of the option list.
GNU specifies the following getopt_long() and getopt_long_only() return values:
when short option is recognized, the option character is returned.
when long option is recognized, val is returned if flag is NULL, otherwise, 0 is returned.
error and -1 returns are the same as for getopt().
question mark ("?") is returned for an ambiguous match or an extraneous parameter.
POSIX specifies the following getopt() return values:
the next option character is returned, if found successfully.
colon character (":") is returned if a parameter is missing for one of the options and the first character of opstring is ":".
question mark ("?") is returned if an unknown option character not in optstring is encountered, or if getopt() detects a missing argument and the first character of optstring is not ":".
"-1" is returned for the end of the option list.
GNU specifies that:
if the variable POSIXLY_CORRECT is set, option processing stops as soon as a non-option argument is encountered.
if POSIXLY_CORRECT is set, GNU getopt() conforms to POSIX.2.
the variable _[PID]_GNU_nonoption_argv_flags_ was used by bash 2.0 to communicate to GNU libc which arguments resulted from wildcard expansion and so should not be considered as options. This behavior was removed in bash version 2.01, but the support remains in GNU libc.