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 *short‐
opts, 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 delimeter. 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_argument.
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, oth‐
erwise 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 argu‐
ment 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 ooption is useful in delimit‐
ing 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 abreviations 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:
· 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. Specifi‐
cally, getopt_clip() does not reorder arguments but returns -1 and
stops processing upon encountering the first operand argument.
·
The environment variable POSIXLY_CORRECT is ignored (the
getopt_clip() function behaves as though it were set.)
· 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.
· 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.
· Long-option abbreviations are not recognized.
· Short options are required to have at least one long-option equiv‐
alent. That is, each character in shortopts must appear as the val
member in one or more option structures. Similarly, 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
equivalent, or a long option does not have at least one
short-option equivalent.
EXAMPLES
Example 1: Exmple 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(5) 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 short‐
opts argument is neither a plus or minus sign),
the POSIX rule that all operands must follow
all options is enforced. Option processing ter‐
minates 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(5) for descriptions of the following attributes:
┌─────────────────────────────┬─────────────────────────────┐
│ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
├─────────────────────────────┼─────────────────────────────┤
│Interface Stability │Evolving │
├─────────────────────────────┼─────────────────────────────┤
│MT-Level │Unsafe │
└─────────────────────────────┴─────────────────────────────┘
SEE ALSOintro(1), getopts(1), getopt(3C), getsubopt(3C), gettext(3C), setlo‐
cale(3C), attributes(5), environ(5), standards(5)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:
· The handling of the hyphen (-) as the first character of the
option string in presence of the environment variable POSIXLY_COR‐
RECT:
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.
· The handling of the hyphen (-) within the shortopts parameter
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 behavior as incor‐
rect, but maintains it for compatibility.
· 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).
· 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).
· 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).
· 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.
· The error messages are different (all).
· The implementations do not permute the argument vector at the same
points in the calling sequence. The aspects normally 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.
SunOS 5.10 10 May 2004 getopt_long(3C)