Standard C Library Functions getopt_long(3C)
NAME
getopt_long, getopt_long_only, getopt_clip - parse long com-
mand optionsSYNOPSIS
#include
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 *indexptrextern char *optarg; extern int optind, opterr, optopt;DESCRIPTION
These functions are provided as a porting aid forGNU/Freeware/OpenBSD utilities. The getopt_long() function
is intended to be as closely compatible with the GNU and OpenBSD implementations as possible, but since these publicimplementations differ in some corner cases, it is not pos-
sible to be fully compatible with both. The differences are enumerated in the NOTES section.The getopt_long() function is an aid for implementing the
GNU command line argument conventions. See the GNU documen-
tation 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 conven-
tion, which is slightly more restrictive than theGNU/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.SunOS 5.11 Last change: 10 May 2004 1
Standard C Library Functions getopt_long(3C)
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 character that is usually a corresponding short option. The option structure 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 inter-
leave 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 operandsfollow options (and their option-arguments) in the argv
array and optind points to the first operand. The order of options relative to other options and operands relative toother operands is maintained. The argument "--" is accepted
as a delimiter indicating the end of options. No argument reorder occurs past this delimeter. Argument reordering can not be unambiguously performed in all cases. Thegetopt_long() function depends on a number of internal
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 havean option-argument that should be separated from it by white
space. If a character is followed by two colons (::), theoption 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 toseparate an optional option-argument from its associated
option. If shortopts contains the character "W" followed bya semicolon (;), then -W foo is treated as the long option
--foo.
If the first character of the shortopts argument is the plussign (+), getopt_long() enforces the POSIX requirement that
operands follow options on the command line by returning -1
and stopping argument processing upon encountering the firstSunOS 5.11 Last change: 10 May 2004 2
Standard C Library Functions getopt_long(3C)
operand (or "--"). This behavior can also be specified by
setting the environment variable POSIXLY_CORRECT.
A hyphen (-) as the first character of the shortopts argu-
ment specifies that options and operands can be intermixed in argv but no argument reordering is performed. Operandsare returned as arguments to option `\1', and option pro-
cessing 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 colonis returned by getopt_long() in response to a missing argu-
ment; 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 eachlong option. The array is terminated with an element con-
taining 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, definedin
, 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 returnedwhen this option is encountered, other-
wise zero is returned. int val Contains the value to be stored at the variable pointed to by flag or returnedby getopt_long() if flag is a null
pointer.SunOS 5.11 Last change: 10 May 2004 3
Standard C Library Functions getopt_long(3C)
For any long option, getopt_long() returns the index in the
array longopts of the options definition by storing it in indexptr. The name of the option can be retrieved withlongopts[(*indexptr)].name. Long options can be dis-
tinguished 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 returnfrom 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 thesimple 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, iffoo and foobar are acceptable long-option names, then speci-
fying --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 thefirst call to getopt_long(). When all options have been pro-
cessed (that is, up to the first non-option argument),
getopt_long() returns -1. The special option "--" (two
hyphens) can be used to delimit the end of the options; whenit is encountered, -1 is returned and "-" is skipped. This
ooption is useful in delimiting non-option arguments that
begin with "-" (hyphen).
If getopt_long() encounters a short option character shor-
topts string or a long option not described in the longopts array, it returns the question mark (?) character. It alsoreturns a question mark (?) character in response to a miss-
ing option argument unless the first character of shortoptsis a colon (:) (or the second character, if the first char-
acter 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 isnot a colon (:), getopt_long() prints a diagnostic message
SunOS 5.11 Last change: 10 May 2004 4
Standard C Library Functions getopt_long(3C)
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, asingle hyphen followed by that character (and no other char-
acters) will be recognized as a short option. Use ofgetopt_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 argu-
ment 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 shor-
topts argument is unspecified.o Long-option abbreviations are not recognized.
o Short options are required to have at least onelong-option equivalent. 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 areSunOS 5.11 Last change: 10 May 2004 5
Standard C Library Functions getopt_long(3C)
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 functions 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 longoption encountered on the command line is returned. Other-
wise, these functions return 0 (and the value specified inthe val member for the long option is stored into the loca-
tion 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 apossible 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 (otherthan 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). Ifproper 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 haveat least one short-option equivalent.
EXAMPLES
Example 1 Exmple using getopt().SunOS 5.11 Last change: 10 May 2004 6
Standard C Library Functions getopt_long(3C)
#include
#include
/* 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;SunOS 5.11 Last change: 10 May 2004 7
Standard C Library Functions getopt_long(3C)
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 environmentvariables that affect the execution of getopt_long(): LANG,
LC_ALL, and LC_MESSAGES.
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.SunOS 5.11 Last change: 10 May 2004 8
Standard C Library Functions getopt_long(3C)
LC_CTYPE Determine the locale for the interpreta-
tion of sequences of bytes as characters in shortopts and the longopts[].name structure members.USAGE
The getopt_long() function does not fully check for manda-
tory arguments because there is no unambiguous algorithm todo 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 mandatory argu-
ment. Indeed, the only time a missing option argument can be reliably detected is when the option is the final option onthe command line and is not followed by any command argu-
ments.ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Interface Stability | Committed ||_____________________________|_____________________________|
| MT-Level | Unsafe |
|_____________________________|_____________________________|
SEE ALSO
Intro(1), getopts(1), getopt(3C), getsubopt(3C),gettext(3C), setlocale(3C), attributes(5), environ(5), stan-
dards(5) NOTESUse of getopt_long() is discouraged for applications tar-
geted strictly for Solaris. It should be used only for applications targeted at Solaris and platforms that adhereto the GNU command line conventions. The getopt_long_only()
function is provided by Solaris and GNU for legacy applica-
tions 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 charac-
ter of the option string in presence of theSunOS 5.11 Last change: 10 May 2004 9
Standard C Library Functions getopt_long(3C)
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
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 asincorrect, but maintains it for com-
patibility. o The return value in the event of a missing argumentif 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).
SunOS 5.11 Last change: 10 May 2004 10
Standard C Library Functions getopt_long(3C)
o The setting of optarg for long options without anargument 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 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 argumentvector before -1 is returned.
SunOS 5.11 Last change: 10 May 2004 11