|
Packit |
7cfc04 |
.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de)
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.\" %%%LICENSE_START(VERBATIM)
|
|
Packit |
7cfc04 |
.\" Permission is granted to make and distribute verbatim copies of this
|
|
Packit |
7cfc04 |
.\" manual provided the copyright notice and this permission notice are
|
|
Packit |
7cfc04 |
.\" preserved on all copies.
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.\" Permission is granted to copy and distribute modified versions of this
|
|
Packit |
7cfc04 |
.\" manual under the conditions for verbatim copying, provided that the
|
|
Packit |
7cfc04 |
.\" entire resulting derived work is distributed under the terms of a
|
|
Packit |
7cfc04 |
.\" permission notice identical to this one.
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.\" Since the Linux kernel and libraries are constantly changing, this
|
|
Packit |
7cfc04 |
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
|
Packit |
7cfc04 |
.\" responsibility for errors or omissions, or for damages resulting from
|
|
Packit |
7cfc04 |
.\" the use of the information contained herein. The author(s) may not
|
|
Packit |
7cfc04 |
.\" have taken the same level of care in the production of this manual,
|
|
Packit |
7cfc04 |
.\" which is licensed free of charge, as they might when working
|
|
Packit |
7cfc04 |
.\" professionally.
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
Packit |
7cfc04 |
.\" the source, must acknowledge the copyright and authors of this work.
|
|
Packit |
7cfc04 |
.\" %%%LICENSE_END
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.\" Modified Sat Jul 24 19:27:50 1993 by Rik Faith (faith@cs.unc.edu)
|
|
Packit |
7cfc04 |
.\" Modified Mon Aug 30 22:02:34 1995 by Jim Van Zandt <jrv@vanzandt.mv.com>
|
|
Packit |
7cfc04 |
.\" longindex is a pointer, has_arg can take 3 values, using consistent
|
|
Packit |
7cfc04 |
.\" names for optstring and longindex, "\n" in formats fixed. Documenting
|
|
Packit |
7cfc04 |
.\" opterr and getopt_long_only. Clarified explanations (borrowing heavily
|
|
Packit |
7cfc04 |
.\" from the source code).
|
|
Packit |
7cfc04 |
.\" Modified 8 May 1998 by Joseph S. Myers (jsm28@cam.ac.uk)
|
|
Packit |
7cfc04 |
.\" Modified 990715, aeb: changed `EOF' into `-1' since that is what POSIX
|
|
Packit |
7cfc04 |
.\" says; moreover, EOF is not defined in <unistd.h>.
|
|
Packit |
7cfc04 |
.\" Modified 2002-02-16, joey: added information about nonexistent
|
|
Packit |
7cfc04 |
.\" option character and colon as first option character
|
|
Packit |
7cfc04 |
.\" Modified 2004-07-28, Michael Kerrisk <mtk.manpages@gmail.com>
|
|
Packit |
7cfc04 |
.\" Added text to explain how to order both '[-+]' and ':' at
|
|
Packit |
7cfc04 |
.\" the start of optstring
|
|
Packit |
7cfc04 |
.\" Modified 2006-12-15, mtk, Added getopt() example program.
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.TH GETOPT 3 2017-09-15 "GNU" "Linux Programmer's Manual"
|
|
Packit |
7cfc04 |
.SH NAME
|
|
Packit |
7cfc04 |
getopt, getopt_long, getopt_long_only,
|
|
Packit |
7cfc04 |
optarg, optind, opterr, optopt \- Parse command-line options
|
|
Packit |
7cfc04 |
.SH SYNOPSIS
|
|
Packit |
7cfc04 |
.nf
|
|
Packit |
7cfc04 |
.B #include <unistd.h>
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.BI "int getopt(int " argc ", char * const " argv[] ,
|
|
Packit |
7cfc04 |
.BI " const char *" optstring );
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.BI "extern char *" optarg ;
|
|
Packit |
7cfc04 |
.BI "extern int " optind ", " opterr ", " optopt ;
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.B #include <getopt.h>
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.BI "int getopt_long(int " argc ", char * const " argv[] ,
|
|
Packit |
7cfc04 |
.BI " const char *" optstring ,
|
|
Packit |
7cfc04 |
.BI " const struct option *" longopts ", int *" longindex );
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.BI "int getopt_long_only(int " argc ", char * const " argv[] ,
|
|
Packit |
7cfc04 |
.BI " const char *" optstring ,
|
|
Packit |
7cfc04 |
.BI " const struct option *" longopts ", int *" longindex );
|
|
Packit |
7cfc04 |
.fi
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.in -4n
|
|
Packit |
7cfc04 |
Feature Test Macro Requirements for glibc (see
|
|
Packit |
7cfc04 |
.BR feature_test_macros (7)):
|
|
Packit |
7cfc04 |
.ad l
|
|
Packit |
7cfc04 |
.in
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.BR getopt ():
|
|
Packit |
7cfc04 |
_POSIX_C_SOURCE\ >=\ 2 || _XOPEN_SOURCE
|
|
Packit |
7cfc04 |
.br
|
|
Packit |
7cfc04 |
.BR getopt_long (),
|
|
Packit |
7cfc04 |
.BR getopt_long_only ():
|
|
Packit |
7cfc04 |
_GNU_SOURCE
|
|
Packit |
7cfc04 |
.ad b
|
|
Packit |
7cfc04 |
.SH DESCRIPTION
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.BR getopt ()
|
|
Packit |
7cfc04 |
function parses the command-line arguments.
|
|
Packit |
7cfc04 |
Its arguments
|
|
Packit |
7cfc04 |
.I argc
|
|
Packit |
7cfc04 |
and
|
|
Packit |
7cfc04 |
.I argv
|
|
Packit |
7cfc04 |
are the argument count and array as passed to the
|
|
Packit |
7cfc04 |
.IR main ()
|
|
Packit |
7cfc04 |
function on program invocation.
|
|
Packit |
7cfc04 |
An element of \fIargv\fP that starts with \(aq\-\(aq
|
|
Packit |
7cfc04 |
(and is not exactly "\-" or "\-\-")
|
|
Packit |
7cfc04 |
is an option element.
|
|
Packit |
7cfc04 |
The characters of this element
|
|
Packit |
7cfc04 |
(aside from the initial \(aq\-\(aq) are option characters.
|
|
Packit |
7cfc04 |
If
|
|
Packit |
7cfc04 |
.BR getopt ()
|
|
Packit |
7cfc04 |
is called repeatedly, it returns successively each of the option characters
|
|
Packit |
7cfc04 |
from each of the option elements.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
The variable
|
|
Packit |
7cfc04 |
.I optind
|
|
Packit |
7cfc04 |
is the index of the next element to be processed in
|
|
Packit |
7cfc04 |
.IR argv .
|
|
Packit |
7cfc04 |
The system initializes this value to 1.
|
|
Packit |
7cfc04 |
The caller can reset it to 1 to restart scanning of the same
|
|
Packit |
7cfc04 |
.IR argv ,
|
|
Packit |
7cfc04 |
or when scanning a new argument vector.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
If
|
|
Packit |
7cfc04 |
.BR getopt ()
|
|
Packit |
7cfc04 |
finds another option character, it returns that
|
|
Packit |
7cfc04 |
character, updating the external variable \fIoptind\fP and a static
|
|
Packit |
7cfc04 |
variable \fInextchar\fP so that the next call to
|
|
Packit |
7cfc04 |
.BR getopt ()
|
|
Packit |
7cfc04 |
can
|
|
Packit |
7cfc04 |
resume the scan with the following option character or
|
|
Packit |
7cfc04 |
\fIargv\fP-element.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
If there are no more option characters,
|
|
Packit |
7cfc04 |
.BR getopt ()
|
|
Packit |
7cfc04 |
returns \-1.
|
|
Packit |
7cfc04 |
Then \fIoptind\fP is the index in \fIargv\fP of the first
|
|
Packit |
7cfc04 |
\fIargv\fP-element that is not an option.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.I optstring
|
|
Packit |
7cfc04 |
is a string containing the legitimate option characters.
|
|
Packit |
7cfc04 |
If such a
|
|
Packit |
7cfc04 |
character is followed by a colon, the option requires an argument, so
|
|
Packit |
7cfc04 |
.BR getopt ()
|
|
Packit |
7cfc04 |
places a pointer to the following text in the same
|
|
Packit |
7cfc04 |
\fIargv\fP-element, or the text of the following \fIargv\fP-element, in
|
|
Packit |
7cfc04 |
.IR optarg .
|
|
Packit |
7cfc04 |
Two colons mean an option takes
|
|
Packit |
7cfc04 |
an optional arg; if there is text in the current \fIargv\fP-element
|
|
Packit |
7cfc04 |
(i.e., in the same word as the option name itself, for example, "\-oarg"),
|
|
Packit |
7cfc04 |
then it is returned in \fIoptarg\fP, otherwise \fIoptarg\fP is set to zero.
|
|
Packit |
7cfc04 |
This is a GNU extension.
|
|
Packit |
7cfc04 |
If
|
|
Packit |
7cfc04 |
.I optstring
|
|
Packit |
7cfc04 |
contains
|
|
Packit |
7cfc04 |
.B W
|
|
Packit |
7cfc04 |
followed by a semicolon, then
|
|
Packit |
7cfc04 |
.B \-W foo
|
|
Packit |
7cfc04 |
is treated as the long option
|
|
Packit |
7cfc04 |
.BR \-\-foo .
|
|
Packit |
7cfc04 |
(The
|
|
Packit |
7cfc04 |
.B \-W
|
|
Packit |
7cfc04 |
option is reserved by POSIX.2 for implementation extensions.)
|
|
Packit |
7cfc04 |
This behavior is a GNU extension, not available with libraries before
|
|
Packit |
7cfc04 |
glibc 2.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
By default,
|
|
Packit |
7cfc04 |
.BR getopt ()
|
|
Packit |
7cfc04 |
permutes the contents of \fIargv\fP as it
|
|
Packit |
7cfc04 |
scans, so that eventually all the nonoptions are at the end.
|
|
Packit |
7cfc04 |
Two other modes are also implemented.
|
|
Packit |
7cfc04 |
If the first character of
|
|
Packit |
7cfc04 |
\fIoptstring\fP is \(aq+\(aq or the environment variable
|
|
Packit |
7cfc04 |
.B POSIXLY_CORRECT
|
|
Packit |
7cfc04 |
is set, then option processing stops as soon as a nonoption argument is
|
|
Packit |
7cfc04 |
encountered.
|
|
Packit |
7cfc04 |
If the first character of \fIoptstring\fP is \(aq\-\(aq, then
|
|
Packit |
7cfc04 |
each nonoption \fIargv\fP-element is handled as if it were the argument of
|
|
Packit |
7cfc04 |
an option with character code 1. (This is used by programs that were
|
|
Packit |
7cfc04 |
written to expect options and other \fIargv\fP-elements in any order
|
|
Packit |
7cfc04 |
and that care about the ordering of the two.)
|
|
Packit |
7cfc04 |
The special argument "\-\-" forces an end of option-scanning regardless
|
|
Packit |
7cfc04 |
of the scanning mode.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
While processing the option list,
|
|
Packit |
7cfc04 |
.BR getopt ()
|
|
Packit |
7cfc04 |
can detect two kinds of errors:
|
|
Packit |
7cfc04 |
(1) an option character that was not specified in
|
|
Packit |
7cfc04 |
.IR optstring
|
|
Packit |
7cfc04 |
and (2) a missing option argument
|
|
Packit |
7cfc04 |
(i.e., an option at the end of the command line without an expected argument).
|
|
Packit |
7cfc04 |
Such errors are handled and reported as follows:
|
|
Packit |
7cfc04 |
.IP * 3
|
|
Packit |
7cfc04 |
By default,
|
|
Packit |
7cfc04 |
.BR getopt ()
|
|
Packit |
7cfc04 |
prints an error message on standard error,
|
|
Packit |
7cfc04 |
places the erroneous option character in
|
|
Packit |
7cfc04 |
.IR optopt ,
|
|
Packit |
7cfc04 |
and returns \(aq?\(aq as the function result.
|
|
Packit |
7cfc04 |
.IP *
|
|
Packit |
7cfc04 |
If the caller has set the global variable
|
|
Packit |
7cfc04 |
.IR opterr
|
|
Packit |
7cfc04 |
to zero, then
|
|
Packit |
7cfc04 |
.BR getopt ()
|
|
Packit |
7cfc04 |
does not print an error message.
|
|
Packit |
7cfc04 |
The caller can determine that there was an error by testing whether
|
|
Packit |
7cfc04 |
the function return value is \(aq?\(aq.
|
|
Packit |
7cfc04 |
(By default,
|
|
Packit |
7cfc04 |
.IR opterr
|
|
Packit |
7cfc04 |
has a nonzero value.)
|
|
Packit |
7cfc04 |
.IP *
|
|
Packit |
7cfc04 |
If the first character
|
|
Packit |
7cfc04 |
(following any optional \(aq+\(aq or \(aq\-\(aq described above)
|
|
Packit |
7cfc04 |
of \fIoptstring\fP
|
|
Packit |
7cfc04 |
is a colon (\(aq:\(aq), then
|
|
Packit |
7cfc04 |
.BR getopt ()
|
|
Packit |
7cfc04 |
likewise does not print an error message.
|
|
Packit |
7cfc04 |
In addition, it returns \(aq:\(aq instead of \(aq?\(aq to
|
|
Packit |
7cfc04 |
indicate a missing option argument.
|
|
Packit |
7cfc04 |
This allows the caller to distinguish the two different types of errors.
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.SS getopt_long() and getopt_long_only()
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.BR getopt_long ()
|
|
Packit |
7cfc04 |
function works like
|
|
Packit |
7cfc04 |
.BR getopt ()
|
|
Packit |
7cfc04 |
except that it also accepts long options, started with two dashes.
|
|
Packit |
7cfc04 |
(If the program accepts only long options, then
|
|
Packit |
7cfc04 |
.I optstring
|
|
Packit |
7cfc04 |
should be specified as an empty string (""), not NULL.)
|
|
Packit |
7cfc04 |
Long option names may be abbreviated if the abbreviation is
|
|
Packit |
7cfc04 |
unique or is an exact match for some defined option.
|
|
Packit |
7cfc04 |
A long option
|
|
Packit |
7cfc04 |
may take a parameter, of the form
|
|
Packit |
7cfc04 |
.B \-\-arg=param
|
|
Packit |
7cfc04 |
or
|
|
Packit |
7cfc04 |
.BR "\-\-arg param" .
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.I longopts
|
|
Packit |
7cfc04 |
is a pointer to the first element of an array of
|
|
Packit |
7cfc04 |
.I struct option
|
|
Packit |
7cfc04 |
declared in
|
|
Packit |
7cfc04 |
.I <getopt.h>
|
|
Packit |
7cfc04 |
as
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.in +4n
|
|
Packit |
7cfc04 |
.EX
|
|
Packit |
7cfc04 |
struct option {
|
|
Packit |
7cfc04 |
const char *name;
|
|
Packit |
7cfc04 |
int has_arg;
|
|
Packit |
7cfc04 |
int *flag;
|
|
Packit |
7cfc04 |
int val;
|
|
Packit |
7cfc04 |
};
|
|
Packit |
7cfc04 |
.EE
|
|
Packit |
7cfc04 |
.in
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
The meanings of the different fields are:
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.I name
|
|
Packit |
7cfc04 |
is the name of the long option.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.I has_arg
|
|
Packit |
7cfc04 |
is:
|
|
Packit |
7cfc04 |
\fBno_argument\fP (or 0) if the option does not take an argument;
|
|
Packit |
7cfc04 |
\fBrequired_argument\fP (or 1) if the option requires an argument; or
|
|
Packit |
7cfc04 |
\fBoptional_argument\fP (or 2) if the option takes an optional argument.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.I flag
|
|
Packit |
7cfc04 |
specifies how results are returned for a long option.
|
|
Packit |
7cfc04 |
If \fIflag\fP
|
|
Packit |
7cfc04 |
is NULL, then
|
|
Packit |
7cfc04 |
.BR getopt_long ()
|
|
Packit |
7cfc04 |
returns \fIval\fP.
|
|
Packit |
7cfc04 |
(For example, the calling program may set \fIval\fP to the equivalent short
|
|
Packit |
7cfc04 |
option character.)
|
|
Packit |
7cfc04 |
Otherwise,
|
|
Packit |
7cfc04 |
.BR getopt_long ()
|
|
Packit |
7cfc04 |
returns 0, and
|
|
Packit |
7cfc04 |
\fIflag\fP points to a variable which is set to \fIval\fP if the
|
|
Packit |
7cfc04 |
option is found, but left unchanged if the option is not found.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
\fIval\fP
|
|
Packit |
7cfc04 |
is the value to return, or to load into the variable pointed
|
|
Packit |
7cfc04 |
to by \fIflag\fP.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
The last element of the array has to be filled with zeros.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
If \fIlongindex\fP is not NULL, it
|
|
Packit |
7cfc04 |
points to a variable which is set to the index of the long option relative to
|
|
Packit |
7cfc04 |
.IR longopts .
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.BR getopt_long_only ()
|
|
Packit |
7cfc04 |
is like
|
|
Packit |
7cfc04 |
.BR getopt_long (),
|
|
Packit |
7cfc04 |
but \(aq\-\(aq as well
|
|
Packit |
7cfc04 |
as "\-\-" can indicate a long option.
|
|
Packit |
7cfc04 |
If an option that starts with \(aq\-\(aq
|
|
Packit |
7cfc04 |
(not "\-\-") doesn't match a long option, but does match a short option,
|
|
Packit |
7cfc04 |
it is parsed as a short option instead.
|
|
Packit |
7cfc04 |
.SH RETURN VALUE
|
|
Packit |
7cfc04 |
If an option was successfully found, then
|
|
Packit |
7cfc04 |
.BR getopt ()
|
|
Packit |
7cfc04 |
returns the option character.
|
|
Packit |
7cfc04 |
If all command-line options have been parsed, then
|
|
Packit |
7cfc04 |
.BR getopt ()
|
|
Packit |
7cfc04 |
returns \-1.
|
|
Packit |
7cfc04 |
If
|
|
Packit |
7cfc04 |
.BR getopt ()
|
|
Packit |
7cfc04 |
encounters an option character that was not in
|
|
Packit |
7cfc04 |
.IR optstring ,
|
|
Packit |
7cfc04 |
then \(aq?\(aq is returned.
|
|
Packit |
7cfc04 |
If
|
|
Packit |
7cfc04 |
.BR getopt ()
|
|
Packit |
7cfc04 |
encounters an option with a missing argument,
|
|
Packit |
7cfc04 |
then the return value depends on the first character in
|
|
Packit |
7cfc04 |
.IR optstring :
|
|
Packit |
7cfc04 |
if it is \(aq:\(aq, then \(aq:\(aq is returned; otherwise \(aq?\(aq is returned.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.BR getopt_long ()
|
|
Packit |
7cfc04 |
and
|
|
Packit |
7cfc04 |
.BR getopt_long_only ()
|
|
Packit |
7cfc04 |
also return the option
|
|
Packit |
7cfc04 |
character when a short option is recognized.
|
|
Packit |
7cfc04 |
For a long option, they
|
|
Packit |
7cfc04 |
return \fIval\fP if \fIflag\fP is NULL, and 0 otherwise.
|
|
Packit |
7cfc04 |
Error and \-1 returns are the same as for
|
|
Packit |
7cfc04 |
.BR getopt (),
|
|
Packit |
7cfc04 |
plus \(aq?\(aq for an
|
|
Packit |
7cfc04 |
ambiguous match or an extraneous parameter.
|
|
Packit |
7cfc04 |
.SH ENVIRONMENT
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B POSIXLY_CORRECT
|
|
Packit |
7cfc04 |
If this is set, then option processing stops as soon as a nonoption
|
|
Packit |
7cfc04 |
argument is encountered.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B _<PID>_GNU_nonoption_argv_flags_
|
|
Packit |
7cfc04 |
This variable was used by
|
|
Packit |
7cfc04 |
.BR bash (1)
|
|
Packit |
7cfc04 |
2.0 to communicate to glibc which arguments are the results of
|
|
Packit |
7cfc04 |
wildcard expansion and so should not be considered as options.
|
|
Packit |
7cfc04 |
This behavior was removed in
|
|
Packit |
7cfc04 |
.BR bash (1)
|
|
Packit |
7cfc04 |
version 2.01, but the support remains in glibc.
|
|
Packit |
7cfc04 |
.SH ATTRIBUTES
|
|
Packit |
7cfc04 |
For an explanation of the terms used in this section, see
|
|
Packit |
7cfc04 |
.BR attributes (7).
|
|
Packit |
7cfc04 |
.TS
|
|
Packit |
7cfc04 |
allbox;
|
|
Packit |
7cfc04 |
lbw24 lb lb
|
|
Packit |
7cfc04 |
l l l.
|
|
Packit |
7cfc04 |
Interface Attribute Value
|
|
Packit |
7cfc04 |
T{
|
|
Packit |
7cfc04 |
.BR getopt (),
|
|
Packit |
7cfc04 |
.BR getopt_long (),
|
|
Packit |
7cfc04 |
.BR getopt_long_only ()
|
|
Packit |
7cfc04 |
T} Thread safety MT-Unsafe race:getopt env
|
|
Packit |
7cfc04 |
.TE
|
|
Packit |
7cfc04 |
.SH CONFORMING TO
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR getopt ():
|
|
Packit |
7cfc04 |
POSIX.1-2001, POSIX.1-2008, and POSIX.2,
|
|
Packit |
7cfc04 |
provided the environment variable
|
|
Packit |
7cfc04 |
.B POSIXLY_CORRECT
|
|
Packit |
7cfc04 |
is set.
|
|
Packit |
7cfc04 |
Otherwise, the elements of \fIargv\fP aren't really
|
|
Packit |
7cfc04 |
.IR const ,
|
|
Packit |
7cfc04 |
because we permute them.
|
|
Packit |
7cfc04 |
We pretend they're
|
|
Packit |
7cfc04 |
.I const
|
|
Packit |
7cfc04 |
in the prototype to be compatible with other systems.
|
|
Packit |
7cfc04 |
.IP
|
|
Packit |
7cfc04 |
The use of \(aq+\(aq and \(aq\-\(aq in
|
|
Packit |
7cfc04 |
.I optstring
|
|
Packit |
7cfc04 |
is a GNU extension.
|
|
Packit |
7cfc04 |
.IP
|
|
Packit |
7cfc04 |
On some older implementations,
|
|
Packit |
7cfc04 |
.BR getopt ()
|
|
Packit |
7cfc04 |
was declared in
|
|
Packit |
7cfc04 |
.IR <stdio.h> .
|
|
Packit |
7cfc04 |
SUSv1 permitted the declaration to appear in either
|
|
Packit |
7cfc04 |
.I <unistd.h>
|
|
Packit |
7cfc04 |
or
|
|
Packit |
7cfc04 |
.IR <stdio.h> .
|
|
Packit |
7cfc04 |
POSIX.1-1996 marked the use of
|
|
Packit |
7cfc04 |
.I <stdio.h>
|
|
Packit |
7cfc04 |
for this purpose as LEGACY.
|
|
Packit |
7cfc04 |
POSIX.1-2001 does not require the declaration to appear in
|
|
Packit |
7cfc04 |
.IR <stdio.h> .
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR getopt_long "() and " getopt_long_only ():
|
|
Packit |
7cfc04 |
These functions are GNU extensions.
|
|
Packit |
7cfc04 |
.SH NOTES
|
|
Packit |
7cfc04 |
A program that scans multiple argument vectors,
|
|
Packit |
7cfc04 |
or rescans the same vector more than once,
|
|
Packit |
7cfc04 |
and wants to make use of GNU extensions such as \(aq+\(aq
|
|
Packit |
7cfc04 |
and \(aq\-\(aq at the start of
|
|
Packit |
7cfc04 |
.IR optstring ,
|
|
Packit |
7cfc04 |
or changes the value of
|
|
Packit |
7cfc04 |
.B POSIXLY_CORRECT
|
|
Packit |
7cfc04 |
between scans,
|
|
Packit |
7cfc04 |
must reinitialize
|
|
Packit |
7cfc04 |
.BR getopt ()
|
|
Packit |
7cfc04 |
by resetting
|
|
Packit |
7cfc04 |
.I optind
|
|
Packit |
7cfc04 |
to 0, rather than the traditional value of 1.
|
|
Packit |
7cfc04 |
(Resetting to 0 forces the invocation of an internal initialization
|
|
Packit |
7cfc04 |
routine that rechecks
|
|
Packit |
7cfc04 |
.B POSIXLY_CORRECT
|
|
Packit |
7cfc04 |
and checks for GNU extensions in
|
|
Packit |
7cfc04 |
.IR optstring .)
|
|
Packit |
7cfc04 |
.SH EXAMPLE
|
|
Packit |
7cfc04 |
.SS getopt()
|
|
Packit |
7cfc04 |
The following trivial example program uses
|
|
Packit |
7cfc04 |
.BR getopt ()
|
|
Packit |
7cfc04 |
to handle two program options:
|
|
Packit |
7cfc04 |
.IR \-n ,
|
|
Packit |
7cfc04 |
with no associated value; and
|
|
Packit |
7cfc04 |
.IR "\-t val" ,
|
|
Packit |
7cfc04 |
which expects an associated value.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.EX
|
|
Packit |
7cfc04 |
#include <unistd.h>
|
|
Packit |
7cfc04 |
#include <stdlib.h>
|
|
Packit |
7cfc04 |
#include <stdio.h>
|
|
Packit |
7cfc04 |
|
|
Packit |
7cfc04 |
int
|
|
Packit |
7cfc04 |
main(int argc, char *argv[])
|
|
Packit |
7cfc04 |
{
|
|
Packit |
7cfc04 |
int flags, opt;
|
|
Packit |
7cfc04 |
int nsecs, tfnd;
|
|
Packit |
7cfc04 |
|
|
Packit |
7cfc04 |
nsecs = 0;
|
|
Packit |
7cfc04 |
tfnd = 0;
|
|
Packit |
7cfc04 |
flags = 0;
|
|
Packit |
7cfc04 |
while ((opt = getopt(argc, argv, "nt:")) != \-1) {
|
|
Packit |
7cfc04 |
switch (opt) {
|
|
Packit |
7cfc04 |
case \(aqn\(aq:
|
|
Packit |
7cfc04 |
flags = 1;
|
|
Packit |
7cfc04 |
break;
|
|
Packit |
7cfc04 |
case \(aqt\(aq:
|
|
Packit |
7cfc04 |
nsecs = atoi(optarg);
|
|
Packit |
7cfc04 |
tfnd = 1;
|
|
Packit |
7cfc04 |
break;
|
|
Packit |
7cfc04 |
default: /* \(aq?\(aq */
|
|
Packit |
7cfc04 |
fprintf(stderr, "Usage: %s [\-t nsecs] [\-n] name\\n",
|
|
Packit |
7cfc04 |
argv[0]);
|
|
Packit |
7cfc04 |
exit(EXIT_FAILURE);
|
|
Packit |
7cfc04 |
}
|
|
Packit |
7cfc04 |
}
|
|
Packit |
7cfc04 |
|
|
Packit |
7cfc04 |
printf("flags=%d; tfnd=%d; nsecs=%d; optind=%d\\n",
|
|
Packit |
7cfc04 |
flags, tfnd, nsecs, optind);
|
|
Packit |
7cfc04 |
|
|
Packit |
7cfc04 |
if (optind >= argc) {
|
|
Packit |
7cfc04 |
fprintf(stderr, "Expected argument after options\\n");
|
|
Packit |
7cfc04 |
exit(EXIT_FAILURE);
|
|
Packit |
7cfc04 |
}
|
|
Packit |
7cfc04 |
|
|
Packit |
7cfc04 |
printf("name argument = %s\\n", argv[optind]);
|
|
Packit |
7cfc04 |
|
|
Packit |
7cfc04 |
/* Other code omitted */
|
|
Packit |
7cfc04 |
|
|
Packit |
7cfc04 |
exit(EXIT_SUCCESS);
|
|
Packit |
7cfc04 |
}
|
|
Packit |
7cfc04 |
.EX
|
|
Packit |
7cfc04 |
.SS getopt_long()
|
|
Packit |
7cfc04 |
The following example program illustrates the use of
|
|
Packit |
7cfc04 |
.BR getopt_long ()
|
|
Packit |
7cfc04 |
with most of its features.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.EE
|
|
Packit |
7cfc04 |
#include <stdio.h> /* for printf */
|
|
Packit |
7cfc04 |
#include <stdlib.h> /* for exit */
|
|
Packit |
7cfc04 |
#include <getopt.h>
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
int
|
|
Packit |
7cfc04 |
main(int argc, char **argv)
|
|
Packit |
7cfc04 |
{
|
|
Packit |
7cfc04 |
int c;
|
|
Packit |
7cfc04 |
int digit_optind = 0;
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
while (1) {
|
|
Packit |
7cfc04 |
int this_option_optind = optind ? optind : 1;
|
|
Packit |
7cfc04 |
int option_index = 0;
|
|
Packit |
7cfc04 |
static struct option long_options[] = {
|
|
Packit |
7cfc04 |
{"add", required_argument, 0, 0 },
|
|
Packit |
7cfc04 |
{"append", no_argument, 0, 0 },
|
|
Packit |
7cfc04 |
{"delete", required_argument, 0, 0 },
|
|
Packit |
7cfc04 |
{"verbose", no_argument, 0, 0 },
|
|
Packit |
7cfc04 |
{"create", required_argument, 0, \(aqc\(aq},
|
|
Packit |
7cfc04 |
{"file", required_argument, 0, 0 },
|
|
Packit |
7cfc04 |
{0, 0, 0, 0 }
|
|
Packit |
7cfc04 |
};
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
c = getopt_long(argc, argv, "abc:d:012",
|
|
Packit |
7cfc04 |
long_options, &option_index);
|
|
Packit |
7cfc04 |
if (c == \-1)
|
|
Packit |
7cfc04 |
break;
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
switch (c) {
|
|
Packit |
7cfc04 |
case 0:
|
|
Packit |
7cfc04 |
printf("option %s", long_options[option_index].name);
|
|
Packit |
7cfc04 |
if (optarg)
|
|
Packit |
7cfc04 |
printf(" with arg %s", optarg);
|
|
Packit |
7cfc04 |
printf("\\n");
|
|
Packit |
7cfc04 |
break;
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
case \(aq0\(aq:
|
|
Packit |
7cfc04 |
case \(aq1\(aq:
|
|
Packit |
7cfc04 |
case \(aq2\(aq:
|
|
Packit |
7cfc04 |
if (digit_optind != 0 && digit_optind != this_option_optind)
|
|
Packit |
7cfc04 |
printf("digits occur in two different argv\-elements.\\n");
|
|
Packit |
7cfc04 |
digit_optind = this_option_optind;
|
|
Packit |
7cfc04 |
printf("option %c\\n", c);
|
|
Packit |
7cfc04 |
break;
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
case \(aqa\(aq:
|
|
Packit |
7cfc04 |
printf("option a\\n");
|
|
Packit |
7cfc04 |
break;
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
case \(aqb\(aq:
|
|
Packit |
7cfc04 |
printf("option b\\n");
|
|
Packit |
7cfc04 |
break;
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
case \(aqc\(aq:
|
|
Packit |
7cfc04 |
printf("option c with value \(aq%s\(aq\\n", optarg);
|
|
Packit |
7cfc04 |
break;
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
case \(aqd\(aq:
|
|
Packit |
7cfc04 |
printf("option d with value \(aq%s\(aq\\n", optarg);
|
|
Packit |
7cfc04 |
break;
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
case \(aq?\(aq:
|
|
Packit |
7cfc04 |
break;
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
default:
|
|
Packit |
7cfc04 |
printf("?? getopt returned character code 0%o ??\\n", c);
|
|
Packit |
7cfc04 |
}
|
|
Packit |
7cfc04 |
}
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
if (optind < argc) {
|
|
Packit |
7cfc04 |
printf("non\-option ARGV\-elements: ");
|
|
Packit |
7cfc04 |
while (optind < argc)
|
|
Packit |
7cfc04 |
printf("%s ", argv[optind++]);
|
|
Packit |
7cfc04 |
printf("\\n");
|
|
Packit |
7cfc04 |
}
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
exit(EXIT_SUCCESS);
|
|
Packit |
7cfc04 |
}
|
|
Packit |
7cfc04 |
.EE
|
|
Packit |
7cfc04 |
.SH SEE ALSO
|
|
Packit |
7cfc04 |
.BR getopt (1),
|
|
Packit |
7cfc04 |
.BR getsubopt (3)
|
|
Packit |
7cfc04 |
.SH COLOPHON
|
|
Packit |
7cfc04 |
This page is part of release 4.15 of the Linux
|
|
Packit |
7cfc04 |
.I man-pages
|
|
Packit |
7cfc04 |
project.
|
|
Packit |
7cfc04 |
A description of the project,
|
|
Packit |
7cfc04 |
information about reporting bugs,
|
|
Packit |
7cfc04 |
and the latest version of this page,
|
|
Packit |
7cfc04 |
can be found at
|
|
Packit |
7cfc04 |
\%https://www.kernel.org/doc/man\-pages/.
|