path: root/upstream/archlinux/man3p/getopt.3p

'\" et
.TH GETOPT "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\"
.SH PROLOG
This manual page is part of the POSIX Programmer's Manual.
The Linux implementation of this interface may differ (consult
the corresponding Linux manual page for details of Linux behavior),
or the interface may not be implemented on Linux.
.\"
.SH NAME
getopt,
optarg,
opterr,
optind,
optopt
\(em command option parsing
.SH SYNOPSIS
.LP
.nf
#include <unistd.h>
.P
int getopt(int \fIargc\fP, char * const \fIargv\fP[], const char *\fIoptstring\fP);
extern char *optarg;
extern int opterr, optind, optopt;
.fi
.SH DESCRIPTION
The
\fIgetopt\fR()
function is a command-line parser that shall follow Utility Syntax
Guidelines 3, 4, 5, 6, 7, 9, and 10 in the Base Definitions volume of POSIX.1\(hy2017,
.IR "Section 12.2" ", " "Utility Syntax Guidelines".
.P
The parameters
.IR argc
and
.IR argv
are the argument count and argument array as passed to
\fImain\fR()
(see
\fIexec\fR()).
The argument
.IR optstring
is a string of recognized option characters; if a character is followed
by a
<colon>,
the option takes an argument. All option characters allowed by Utility
Syntax Guideline 3 are allowed in
.IR optstring .
The implementation may accept other characters as an extension.
.P
The variable
.IR optind
is the index of the next element of the
.IR argv [\^]
vector to be processed. It shall be initialized to 1 by the system, and
\fIgetopt\fR()
shall update it when it finishes with each element of
.IR argv [\|].
If the application sets
.IR optind
to zero before calling
\fIgetopt\fR(),
the behavior is unspecified. When an element of
.IR argv [\|]
contains multiple option characters, it is unspecified how
\fIgetopt\fR()
determines which options have already been processed.
.P
The
\fIgetopt\fR()
function shall return the next option character (if one is found) from
.IR argv
that matches a character in
.IR optstring ,
if there is one that matches. If the option takes an argument,
\fIgetopt\fR()
shall set the variable
.IR optarg
to point to the option-argument as follows:
.IP " 1." 4
If the option was the last character in the string pointed to by an
element of
.IR argv ,
then
.IR optarg
shall contain the next element of
.IR argv ,
and
.IR optind
shall be incremented by 2. If the resulting value of
.IR optind
is greater than
.IR argc ,
this indicates a missing option-argument, and
\fIgetopt\fR()
shall return an error indication.
.IP " 2." 4
Otherwise,
.IR optarg
shall point to the string following the option character in that
element of
.IR argv ,
and
.IR optind
shall be incremented by 1.
.P
If, when
\fIgetopt\fR()
is called:
.sp
.RS 4
.nf

 \fIargv\fP[optind]  \fRis a null pointer\fP
*\fIargv\fP[optind]  \fRis not the character\fP \-
 \fIargv\fP[optind]  \fRpoints to the string\fP "\-"
.fi
.P
.RE
.P
\fIgetopt\fR()
shall return \-1 without changing
.IR optind .
If:
.sp
.RS 4
.nf

\fIargv\fP[optind]   \fRpoints to the string\fP "\-\|\-"
.fi
.P
.RE
.P
\fIgetopt\fR()
shall return \-1 after incrementing
.IR optind .
.P
If
\fIgetopt\fR()
encounters an option character that is not contained in
.IR optstring ,
it shall return the
<question-mark>
(\c
.BR '?' )
character. If it detects a missing option-argument, it shall return the
<colon>
character (\c
.BR ':' )
if the first character of
.IR optstring
was a
<colon>,
or a
<question-mark>
character (\c
.BR '?' )
otherwise. In either case,
\fIgetopt\fR()
shall set the variable
.IR optopt
to the option character that caused the error. If the application has
not set the variable
.IR opterr
to 0 and the first character of
.IR optstring
is not a
<colon>,
\fIgetopt\fR()
shall also print a diagnostic message to
.IR stderr
in the format specified for the
.IR getopts
utility, unless the
.IR stderr
stream has wide orientation, in which case the behavior is undefined.
.P
The
\fIgetopt\fR()
function need not be thread-safe.
.SH "RETURN VALUE"
The
\fIgetopt\fR()
function shall return the next option character specified on the command
line.
.P
A
<colon>
(\c
.BR ':' )
shall be returned if
\fIgetopt\fR()
detects a missing argument and the first character of
.IR optstring
was a
<colon>
(\c
.BR ':' ).
.P
A
<question-mark>
(\c
.BR '?' )
shall be returned if
\fIgetopt\fR()
encounters an option character not in
.IR optstring
or detects a missing argument and the first character of
.IR optstring
was not a
<colon>
(\c
.BR ':' ).
.P
Otherwise,
\fIgetopt\fR()
shall return \-1 when all command line options are parsed.
.SH ERRORS
If the application has not set the variable
.IR opterr
to 0, the first character of
.IR optstring
is not a
<colon>,
and a write error occurs while
\fIgetopt\fR()
is printing a diagnostic message to
.IR stderr ,
then the error indicator for
.IR stderr
shall be set; but
\fIgetopt\fR()
shall still succeed and the value of
.IR errno
after
\fIgetopt\fR()
is unspecified.
.LP
.IR "The following sections are informative."
.SH EXAMPLES
.SS "Parsing Command Line Options"
.P
The following code fragment shows how you might process the arguments
for a utility that can take the mutually-exclusive options
.IR a
and
.IR b
and the options
.IR f
and
.IR o ,
both of which require arguments:
.sp
.RS 4
.nf

#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
.P
int
main(int argc, char *argv[ ])
{
    int c;
    int bflg = 0, aflg = 0, errflg = 0;
    char *ifile;
    char *ofile;
    . . .
    while ((c = getopt(argc, argv, ":abf:o:")) != -1) {
        switch(c) {
        case \(aqa\(aq:
            if (bflg)
                errflg++;
            else
                aflg++;
            break;
        case \(aqb\(aq:
            if (aflg)
                errflg++;
            else
                bflg++;
            break;
        case \(aqf\(aq:
            ifile = optarg;
            break;
        case \(aqo\(aq:
            ofile = optarg;
            break;
        case \(aq:\(aq:       /* -f or -o without operand */
            fprintf(stderr,
                "Option -%c requires an operand\en", optopt);
            errflg++;
            break;
        case \(aq?\(aq:
            fprintf(stderr,
                "Unrecognized option: \(aq-%c\(aq\en", optopt);
            errflg++;
        }
    }
    if (errflg) {
        fprintf(stderr, "usage: . . . ");
        exit(2);
    }
    for ( ; optind < argc; optind++) {
        if (access(argv[optind], R_OK)) {
    . . .
}
.fi
.P
.RE
.P
This code accepts any of the following as equivalent:
.sp
.RS 4
.nf

cmd -ao arg path path
cmd -a -o arg path path
cmd -o arg -a path path
cmd -a -o arg -- path path
cmd -a -oarg path path
cmd -aoarg path path
.fi
.P
.RE
.SS "Selecting Options from the Command Line"
.P
The following example selects the type of database routines the user
wants to use based on the
.IR Options
argument.
.sp
.RS 4
.nf

#include <unistd.h>
#include <string.h>
\&...
const char *Options = "hdbtl";
\&...
int dbtype, c;
char *st;
\&...
dbtype = 0;
while ((c = getopt(argc, argv, Options)) != -1) {
    if ((st = strchr(Options, c)) != NULL) {
        dbtype = st - Options;
        break;
    }
}
.fi
.P
.RE
.SH "APPLICATION USAGE"
The
\fIgetopt\fR()
function is only required to support option characters included in
Utility Syntax Guideline 3. Many historical implementations of
\fIgetopt\fR()
support other characters as options. This is an allowed extension, but
applications that use extensions are not maximally portable. Note that
support for multi-byte option characters is only possible when such
characters can be represented as type
.BR int .
.P
Applications which use wide-character output functions with
.IR stderr
should ensure that any calls to
\fIgetopt\fR()
do not write to
.IR stderr ,
either by setting
.IR opterr
to 0 or by ensuring the first character of
.IR optstring
is always a
<colon>.
.P
While
.IR ferror ( stderr )
may be used to detect failures to write a diagnostic to
.IR stderr
when
\fIgetopt\fR()
returns
.BR '?' ,
the value of
.IR errno
is unspecified in such a condition. Applications desiring more control
over handling write failures should set
.IR opterr
to 0 and independently perform output to
.IR stderr ,
rather than relying on
\fIgetopt\fR()
to do the output.
.SH RATIONALE
The
.IR optopt
variable represents historical practice and allows the application to
obtain the identity of the invalid option.
.P
The description has been written to make it clear that
\fIgetopt\fR(),
like the
.IR getopts
utility, deals with option-arguments whether separated from the option
by
<blank>
characters or not. Note that the requirements on
\fIgetopt\fR()
and
.IR getopts
are more stringent than the Utility Syntax Guidelines.
.P
The
\fIgetopt\fR()
function shall return \-1, rather than EOF, so that
.IR <stdio.h> 
is not required.
.P
The special significance of a
<colon>
as the first character of
.IR optstring
makes
\fIgetopt\fR()
consistent with the
.IR getopts
utility. It allows an application to make a distinction between a
missing argument and an incorrect option letter without having to
examine the option letter. It is true that a missing argument can only
be detected in one case, but that is a case that has to be considered.
.SH "FUTURE DIRECTIONS"
None.
.SH "SEE ALSO"
.IR "\fIexec\fR\^"
.P
The Base Definitions volume of POSIX.1\(hy2017,
.IR "Section 12.2" ", " "Utility Syntax Guidelines",
.IR "\fB<unistd.h>\fP"
.P
The Shell and Utilities volume of POSIX.1\(hy2017,
.IR "\fIgetopts\fR\^"
.\"
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1-2017, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 7, 2018 Edition,
Copyright (C) 2018 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group.
In the event of any discrepancy between this version and the original IEEE and
The Open Group Standard, the original IEEE and The Open Group Standard
is the referee document. The original Standard can be obtained online at
http://www.opengroup.org/unix/online.html .
.PP
Any typographical or formatting errors that appear
in this page are most likely
to have been introduced during the conversion of the source files to
man page format. To report such errors, see
https://www.kernel.org/doc/man-pages/reporting_bugs.html .