--- getopt.3 2003/03/07 10:35:16 1.1
+++ getopt.3 2005/10/05 10:11:57 1.2
@@ -7,7 +7,7 @@
.\" 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
+.\" 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
@@ -31,10 +31,13 @@
.\" 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 2002-02-16 "GNU" "Linux Programmer's Manual"
+.TH GETOPT 3 2004-07-28 "GNU" "Linux Programmer's Manual"
.SH NAME
-getopt \- Parse command line options
+getopt \- Parse command-line options
.SH SYNOPSIS
.nf
.B #include <unistd.h>
@@ -59,27 +62,28 @@
.fi
.SH DESCRIPTION
The
-.B getopt()
-function parses the command line arguments. Its arguments
+.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
-.B main()
+.I main()
function on program invocation.
-An element of \fIargv\fP that starts with `-' (and is not exactly "-" or "--")
+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
+(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
+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
+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.
+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
@@ -97,54 +101,56 @@
contains
.B W
followed by a semicolon, then
-.B -W foo
+.B \-W foo
is treated as the long option
-.BR --foo .
+.BR \-\-foo .
(The
-.B -W
+.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
+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
+\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
+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
+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
+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
+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
+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 of \fIoptstring\fP
-is a colon (`:'), then \fBgetopt()\fP returns `:' instead of `?' to
+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 nonzero (which is the default),
-\fBgetopt()\fP prints an error message.
+the external variable \fIopterr\fP is non-zero (which is the default),
+\fBgetopt\fP() prints an error message.
.PP
The
-.B getopt_long()
+.BR getopt_long ()
function works like
-.B getopt()
+.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
+.B \-\-arg=param
or
-.BR "--arg param" .
+.BR "\-\-arg param" .
.PP
.I longopts
is a pointer to the first element of an array of
@@ -172,15 +178,15 @@
.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
+\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 \fBNULL\fP, then \fBgetopt_long()\fP returns \fIval\fP. (For
+is \fBNULL\fP, 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
+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
@@ -194,22 +200,33 @@
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,
+\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"
-The
-.B getopt()
-function returns the option character if the option was found
-successfully, `:' if there was a missing parameter for one of the
-options, `?' for an unknown option character, or \-1
-for the end of the option list.
+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
+\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 \fBNULL\fP, and 0 otherwise. Error
-and \-1 returns are the same as for \fBgetopt()\fP, plus `?' for an
+and \-1 returns are the same as for \fBgetopt\fP (), plus '?' for an
ambiguous match or an extraneous parameter.
.SH "ENVIRONMENT VARIABLES"
.TP
@@ -229,7 +246,7 @@
version 2.01, but the support remains in GNU libc.
.SH EXAMPLE
The following example program illustrates the use of
-.BR getopt_long()
+.BR getopt_long ()
with most of its features.
.nf
.sp
@@ -257,7 +274,7 @@
c = getopt_long (argc, argv, "abc:d:012",
long_options, &option_index);
- if (c == -1)
+ if (c == \-1)
break;
switch (c) {
@@ -286,11 +303,11 @@
break;
case 'c':
- printf ("option c with value `%s'\\n", optarg);
+ printf ("option c with value '%s'\\n", optarg);
break;
case 'd':
- printf ("option d with value `%s'\\n", optarg);
+ printf ("option d with value '%s'\\n", optarg);
break;
case '?':
@@ -313,15 +330,14 @@
.fi
.SH BUGS
The POSIX.2 specification of
-.B getopt()
+.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:
+\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.
-
|
