mirror of https://github.com/mkerrisk/man-pages
344 lines
12 KiB
Groff
344 lines
12 KiB
Groff
.\" (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de)
|
|
.\"
|
|
.\" Permission is granted to make and distribute verbatim copies of this
|
|
.\" manual provided the copyright notice and this permission notice are
|
|
.\" preserved on all copies.
|
|
.\"
|
|
.\" Permission is granted to copy and distribute modified versions of this
|
|
.\" manual under the conditions for verbatim copying, provided that the
|
|
.\" entire resulting derived work is distributed under the terms of a
|
|
.\" permission notice identical to this one.
|
|
.\"
|
|
.\" Since the Linux kernel and libraries are constantly changing, this
|
|
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
|
.\" responsibility for errors or omissions, or for damages resulting from
|
|
.\" the use of the information contained herein. The author(s) may not
|
|
.\" have taken the same level of care in the production of this manual,
|
|
.\" which is licensed free of charge, as they might when working
|
|
.\" professionally.
|
|
.\"
|
|
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
.\" the source, must acknowledge the copyright and authors of this work.
|
|
.\" License.
|
|
.\" Modified Sat Jul 24 19:27:50 1993 by Rik Faith (faith@cs.unc.edu)
|
|
.\" Modified Mon Aug 30 22:02:34 1995 by Jim Van Zandt <jrv@vanzandt.mv.com>
|
|
.\" longindex is a pointer, has_arg can take 3 values, using consistent
|
|
.\" names for optstring and longindex, "\n" in formats fixed. Documenting
|
|
.\" opterr and getopt_long_only. Clarified explanations (borrowing heavily
|
|
.\" from the source code).
|
|
.\" Modified 8 May 1998 by Joseph S. Myers (jsm28@cam.ac.uk)
|
|
.\" Modified 990715, aeb: changed `EOF' into `-1' since that is what POSIX
|
|
.\" says; moreover, EOF is not defined in <unistd.h>.
|
|
.\" Modified 2002-02-16, joey: added information about non-existing
|
|
.\" option character and colon as first option character
|
|
.\" Modified 2004-07-28, Michael Kerrisk <mtk-manpages@gmx.net>
|
|
.\" Added text to explain how to order both '[-+]' and ':' at
|
|
.\" the start of optstring
|
|
.\"
|
|
.TH GETOPT 3 2004-07-28 "GNU" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
getopt \- Parse command-line options
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.B #include <unistd.h>
|
|
.sp
|
|
.BI "int getopt(int " argc ", char * const " argv[] ,
|
|
.BI " const char *" optstring );
|
|
.sp
|
|
.BI "extern char *" optarg ;
|
|
.BI "extern int " optind ", " opterr ", " optopt ;
|
|
.sp
|
|
.B #define _GNU_SOURCE
|
|
.br
|
|
.B #include <getopt.h>
|
|
.sp
|
|
.BI "int getopt_long(int " argc ", char * const " argv[] ,
|
|
.BI " const char *" optstring ,
|
|
.BI " const struct option *" longopts ", int *" longindex );
|
|
.sp
|
|
.BI "int getopt_long_only(int " argc ", char * const " argv[] ,
|
|
.BI " const char *" optstring ,
|
|
.BI " const struct option *" longopts ", int *" longindex );
|
|
.fi
|
|
.SH DESCRIPTION
|
|
The
|
|
.BR getopt ()
|
|
function parses the command-line arguments. Its arguments
|
|
.I argc
|
|
and
|
|
.I argv
|
|
are the argument count and array as passed to the
|
|
.IR main ()
|
|
function on program invocation.
|
|
An element of \fIargv\fP that starts with '\-'
|
|
(and is not exactly "\-" or "\-\-")
|
|
is an option element. The characters of this element
|
|
(aside from the initial '\-') are option characters. If \fBgetopt\fP()
|
|
is called repeatedly, it returns successively each of the option characters
|
|
from each of the option elements.
|
|
.PP
|
|
If \fBgetopt\fP() finds another option character, it returns that
|
|
character, updating the external variable \fIoptind\fP and a static
|
|
variable \fInextchar\fP so that the next call to \fBgetopt\fP() can
|
|
resume the scan with the following option character or
|
|
\fIargv\fP-element.
|
|
.PP
|
|
If there are no more option characters, \fBgetopt\fP() returns \-1.
|
|
Then \fIoptind\fP is the index in \fIargv\fP of the first
|
|
\fIargv\fP-element that is not an option.
|
|
.PP
|
|
.I optstring
|
|
is a string containing the legitimate option characters. If such a
|
|
character is followed by a colon, the option requires an argument, so
|
|
\fBgetopt\fP() places a pointer to the following text in the same
|
|
\fIargv\fP-element, or the text of the following \fIargv\fP-element, in
|
|
.IR optarg .
|
|
Two colons mean an option takes
|
|
an optional arg; if there is text in the current \fIargv\fP-element,
|
|
it is returned in \fIoptarg\fP, otherwise \fIoptarg\fP is set to zero.
|
|
This is a GNU extension. If
|
|
.I optstring
|
|
contains
|
|
.B W
|
|
followed by a semicolon, then
|
|
.B \-W foo
|
|
is treated as the long option
|
|
.BR \-\-foo .
|
|
(The
|
|
.B \-W
|
|
option is reserved by POSIX.2 for implementation extensions.)
|
|
This behaviour is a GNU extension, not available with libraries before
|
|
GNU libc 2.
|
|
.PP
|
|
By default, \fBgetopt\fP() permutes the contents of \fIargv\fP as it
|
|
scans, so that eventually all the non-options are at the end. Two
|
|
other modes are also implemented. If the first character of
|
|
\fIoptstring\fP is '+' or the environment variable POSIXLY_CORRECT is
|
|
set, then option processing stops as soon as a non-option argument is
|
|
encountered. If the first character of \fIoptstring\fP is '\-', then
|
|
each non-option \fIargv\fP-element is handled as if it were the argument of
|
|
an option with character code 1. (This is used by programs that were
|
|
written to expect options and other \fIargv\fP-elements in any order
|
|
and that care about the ordering of the two.)
|
|
The special argument "\-\-" forces an end of option-scanning regardless
|
|
of the scanning mode.
|
|
.PP
|
|
If \fBgetopt\fP() does not recognize an option character, it prints an
|
|
error message to stderr, stores the character in \fIoptopt\fP, and
|
|
returns '?'. The calling program may prevent the error message by
|
|
setting \fIopterr\fP to 0.
|
|
.PP
|
|
If \fBgetopt\fP() finds an option character in \fIargv\fP that was not
|
|
included in \fIoptstring\fP, or if it detects a missing option argument,
|
|
it returns '?' and sets the external variable \fIoptopt\fP to the
|
|
actual option character. If the first character
|
|
(following any optional '+'or '\-' described above)
|
|
of \fIoptstring\fP
|
|
is a colon (':'), then \fBgetopt\fP() returns ':' instead of '?' to
|
|
indicate a missing option argument. If an error was detected, and
|
|
the first character of \fIoptstring\fP is not a colon, and
|
|
the external variable \fIopterr\fP is non-zero (which is the default),
|
|
\fBgetopt\fP() prints an error message.
|
|
.PP
|
|
The
|
|
.BR getopt_long ()
|
|
function works like
|
|
.BR getopt ()
|
|
except that it also accepts long options, started out by two dashes.
|
|
Long option names may be abbreviated if the abbreviation is
|
|
unique or is an exact match for some defined option. A long option
|
|
may take a parameter, of the form
|
|
.B \-\-arg=param
|
|
or
|
|
.BR "\-\-arg param" .
|
|
.PP
|
|
.I longopts
|
|
is a pointer to the first element of an array of
|
|
.I struct option
|
|
declared in
|
|
.I <getopt.h>
|
|
as
|
|
.nf
|
|
.sp
|
|
.in 10
|
|
struct option {
|
|
.in 14
|
|
const char *name;
|
|
int has_arg;
|
|
int *flag;
|
|
int val;
|
|
.in 10
|
|
};
|
|
.fi
|
|
.PP
|
|
The meanings of the different fields are:
|
|
.TP
|
|
.I name
|
|
is the name of the long option.
|
|
.TP
|
|
.I has_arg
|
|
is:
|
|
\fBno_argument\fP (or 0) if the option does not take an argument;
|
|
\fBrequired_argument\fP (or 1) if the option requires an argument; or
|
|
\fBoptional_argument\fP (or 2) if the option takes an optional argument.
|
|
.TP
|
|
.I flag
|
|
specifies how results are returned for a long option. If \fIflag\fP
|
|
is NULL, then \fBgetopt_long\fP() returns \fIval\fP. (For
|
|
example, the calling program may set \fIval\fP to the equivalent short
|
|
option character.) Otherwise, \fBgetopt_long\fP() returns 0, and
|
|
\fIflag\fP points to a variable which is set to \fIval\fP if the
|
|
option is found, but left unchanged if the option is not found.
|
|
.TP
|
|
\fIval\fP
|
|
is the value to return, or to load into the variable pointed
|
|
to by \fIflag\fP.
|
|
.PP
|
|
The last element of the array has to be filled with zeroes.
|
|
.PP
|
|
If \fIlongindex\fP is not NULL, it
|
|
points to a variable which is set to the index of the long option relative to
|
|
.IR longopts .
|
|
.PP
|
|
\fBgetopt_long_only\fP() is like \fBgetopt_long\fP(), but '\-' as well
|
|
as '\-\-' can indicate a long option. If an option that starts with '\-'
|
|
(not '\-\-') doesn't match a long option, but does match a short option,
|
|
it is parsed as a short option instead.
|
|
.SH "RETURN VALUE"
|
|
If an option was successfully found, then
|
|
.BR getopt ()
|
|
returns the option character.
|
|
If all command-line options have been parsed, then
|
|
.BR getopt ()
|
|
returns \-1.
|
|
If
|
|
.BR getopt ()
|
|
encounters an option character that was not in
|
|
.IR optstring ,
|
|
then '?' is returned.
|
|
If
|
|
.BR getopt ()
|
|
encounters an option with a missing argument,
|
|
then the return value depends on the first character in
|
|
.IR optstring :
|
|
if it is ':', then ':' is returned; otherwise '?' is returned.
|
|
.PP
|
|
\fBgetopt_long\fP() and \fBgetopt_long_only\fP() also return the option
|
|
character when a short option is recognized. For a long option, they
|
|
return \fIval\fP if \fIflag\fP is NULL, and 0 otherwise. Error
|
|
and \-1 returns are the same as for \fBgetopt\fP() (), plus '?' for an
|
|
ambiguous match or an extraneous parameter.
|
|
.SH "ENVIRONMENT VARIABLES"
|
|
.TP
|
|
.SM
|
|
.B POSIXLY_CORRECT
|
|
If this is set, then option processing stops as soon as a non-option
|
|
argument is encountered.
|
|
.TP
|
|
.SM
|
|
.B _<PID>_GNU_nonoption_argv_flags_
|
|
This variable was used by
|
|
.B bash
|
|
2.0 to communicate to GNU libc which arguments are the results of
|
|
wildcard expansion and so should not be considered as options. This
|
|
behaviour was removed in
|
|
.B bash
|
|
version 2.01, but the support remains in GNU libc.
|
|
.SH EXAMPLE
|
|
The following example program illustrates the use of
|
|
.BR getopt_long ()
|
|
with most of its features.
|
|
.nf
|
|
.sp
|
|
#include <stdio.h> /* for printf */
|
|
#include <stdlib.h> /* for exit */
|
|
#include <getopt.h>
|
|
|
|
int
|
|
main (int argc, char **argv) {
|
|
int c;
|
|
int digit_optind = 0;
|
|
|
|
while (1) {
|
|
int this_option_optind = optind ? optind : 1;
|
|
int option_index = 0;
|
|
static struct option long_options[] = {
|
|
{"add", 1, 0, 0},
|
|
{"append", 0, 0, 0},
|
|
{"delete", 1, 0, 0},
|
|
{"verbose", 0, 0, 0},
|
|
{"create", 1, 0, 'c'},
|
|
{"file", 1, 0, 0},
|
|
{0, 0, 0, 0}
|
|
};
|
|
|
|
c = getopt_long (argc, argv, "abc:d:012",
|
|
long_options, &option_index);
|
|
if (c == \-1)
|
|
break;
|
|
|
|
switch (c) {
|
|
case 0:
|
|
printf ("option %s", long_options[option_index].name);
|
|
if (optarg)
|
|
printf (" with arg %s", optarg);
|
|
printf ("\\n");
|
|
break;
|
|
|
|
case '0':
|
|
case '1':
|
|
case '2':
|
|
if (digit_optind != 0 && digit_optind != this_option_optind)
|
|
printf ("digits occur in two different argv-elements.\\n");
|
|
digit_optind = this_option_optind;
|
|
printf ("option %c\\n", c);
|
|
break;
|
|
|
|
case 'a':
|
|
printf ("option a\\n");
|
|
break;
|
|
|
|
case 'b':
|
|
printf ("option b\\n");
|
|
break;
|
|
|
|
case 'c':
|
|
printf ("option c with value '%s'\\n", optarg);
|
|
break;
|
|
|
|
case 'd':
|
|
printf ("option d with value '%s'\\n", optarg);
|
|
break;
|
|
|
|
case '?':
|
|
break;
|
|
|
|
default:
|
|
printf ("?? getopt returned character code 0%o ??\\n", c);
|
|
}
|
|
}
|
|
|
|
if (optind < argc) {
|
|
printf ("non-option ARGV-elements: ");
|
|
while (optind < argc)
|
|
printf ("%s ", argv[optind++]);
|
|
printf ("\\n");
|
|
}
|
|
|
|
exit (0);
|
|
}
|
|
.fi
|
|
.SH BUGS
|
|
The POSIX.2 specification of
|
|
.BR getopt ()
|
|
has a technical error described in POSIX.2 Interpretation 150. The GNU
|
|
implementation (and probably all other implementations) implements the
|
|
correct behaviour rather than that specified.
|
|
.SH "CONFORMING TO"
|
|
.TP
|
|
\fBgetopt\fP():
|
|
POSIX.2, provided the environment variable POSIXLY_CORRECT is set.
|
|
Otherwise, the elements of \fIargv\fP aren't really const, because we
|
|
permute them. We pretend they're const in the prototype to be
|
|
compatible with other systems.
|