path: root/usr/src/man/man3c/getopt.3c

.\"
.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
.\" permission to reproduce portions of its copyrighted documentation.
.\" Original documentation from The Open Group can be obtained online at
.\" http://www.opengroup.org/bookstore/.
.\"
.\" The Institute of Electrical and Electronics Engineers and The Open
.\" Group, have given us permission to reprint portions of their
.\" documentation.
.\"
.\" In the following statement, the phrase ``this text'' refers to portions
.\" of the system documentation.
.\"
.\" Portions of this text are reprinted and reproduced in electronic form
.\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
.\" Standard for Information Technology -- Portable Operating System
.\" Interface (POSIX), The Open Group Base Specifications Issue 6,
.\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
.\" Engineers, Inc and The Open Group.  In the event of any discrepancy
.\" between these versions 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.
.\"
.\" This notice shall appear on any product containing this material.
.\"
.\" The contents of this file are subject to the terms of the
.\" Common Development and Distribution License (the "License").
.\" You may not use this file except in compliance with the License.
.\"
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
.\" or http://www.opensolaris.org/os/licensing.
.\" See the License for the specific language governing permissions
.\" and limitations under the License.
.\"
.\" When distributing Covered Code, include this CDDL HEADER in each
.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
.\" If applicable, add the following below this CDDL HEADER, with the
.\" fields enclosed by brackets "[]" replaced with your own identifying
.\" information: Portions Copyright [yyyy] [name of copyright owner]
.\"
.\"
.\" Copyright 1989 AT&T
.\" Copyright (c) 2001, The IEEE and The Open Group.  All Rights Reserved.
.\" Copyright (c) 2007, Sun Microsystems, Inc.  All Rights Reserved.
.\" Copyright 2018 Jason King
.\"
.TH GETOPT 3C "July 17, 2018"
.SH NAME
getopt \- command option parsing
.SH SYNOPSIS
.SS "SVID3, XPG3"
.LP
.nf
#include <stdio.h>

\fBint\fR \fBgetopt\fR(\fBint\fR \fIargc\fR, \fBchar * const\fR \fIargv\fR[], \fBconst char *\fR\fIoptstring\fR);
.fi

.LP
.nf
\fBextern char *\fR\fIoptarg\fR;
.fi

.LP
.nf
\fBextern int\fR \fIoptind\fR, \fIopterr\fR, \fIoptopt\fR;
.fi

.SS "POSIX.2, XPG4, SUS, SUSv2, SUSv3"
.LP
.nf
#include <unistd.h>

\fBint\fR \fBgetopt\fR(\fBint\fR \fIargc\fR, \fBchar * const\fR \fIargv\fR[], \fBconst char *\fR\fIoptstring\fR);
.fi

.LP
.nf
\fBextern char *\fR\fIoptarg\fR;
.fi

.LP
.nf
\fBextern int\fR \fIoptind\fR, \fIopterr\fR, \fIoptopt\fR;
.fi

.SH DESCRIPTION
.LP
The \fBgetopt()\fR function is a command line parser that can be used by
applications that follow Basic Utility Syntax Guidelines 3, 4, 5, 6, 7, 9, and
10 which parallel those defined by application portability standards (see
Intro(1)). It can also be used by applications which additionally follow the
Command Line Interface Paradigm (CLIP) syntax extension guidelines 15, 16, and
17. It partially enforces guideline 18 by requiring that every option has a
short-name, but it allows multiple long-names to be associated with an option.
The remaining guidelines are not addressed by \fBgetopt()\fR and are the
responsibility of the application.
.sp
.LP
The \fIargc\fR and \fIargv\fR arguments are the argument count and argument
array as passed to main (see \fBexec\fR(2)). The \fIoptstring\fR argument
specifies the acceptable options. For utilities wanting to conform to the Basic
Utility Syntax Guidelines, \fIoptstring\fR is a string of recognized option
characters. All option characters allowed by Utility Syntax Guideline 3 are
allowed in \fIoptstring\fR. If a character is followed by a colon (:), the
option is expected to have an option-argument, which can be separated from it
by white space.  Utilities wanting to conform to the extended CLIP guidelines
can specify long-option equivalents to short options by following the
short-option character (and optional colon) with a sequence of strings, each
enclosed in parentheses, that specify the long-option aliases.
.sp
.LP
The \fBgetopt()\fR function returns the short-option character in
\fIoptstring\fR that corresponds to the next option found in \fIargv\fR.
.sp
.LP
The \fBgetopt()\fR function places in \fIoptind\fR the \fIargv\fR index of the
next argument to be processed. The \fIoptind\fR variable is external and is
initialized to 1 before the first call to \fBgetopt()\fR. The \fBgetopt()\fR
function sets the variable \fIoptarg\fR to point to the start of the
option-argument as follows:
.RS +4
.TP
.ie t \(bu
.el o
If the option is a short option and that character is the last character in the
argument, then \fIoptarg\fR contains the next element of \fIargv\fR, and
\fIoptind\fR is incremented by 2.
.RE
.RS +4
.TP
.ie t \(bu
.el o
If the option is a short option and that character is not the last character in
the argument, then \fIoptarg\fR points to the string following the option
character in that argument, and \fIoptind\fR is incremented by 1.
.RE
.RS +4
.TP
.ie t \(bu
.el o
If the option is a long option and the character equals is not found in the
argument, then \fIoptarg\fR contains the next element of \fIargv\fR, and
\fIoptind\fR is incremented by 2.
.RE
.RS +4
.TP
.ie t \(bu
.el o
If the option is a long option and the character equals is found in the
argument, then \fIoptarg\fR points to the string following the equals character
in that argument and \fIoptind\fR is incremented by 1.
.RE
.sp
.LP
In all cases, if the resulting value of \fIoptind\fR is not less than
\fIargc\fR, this indicates a missing option-argument and \fBgetopt()\fR returns
an error indication.
.sp
.LP
When all options have been processed (that is, up to the first operand),
\fBgetopt()\fR returns -1. The special option "--"(two hyphens) can be used to
delimit the end of the options; when it is encountered, -1 is returned and "--"
is skipped. This is useful in delimiting non-option arguments that begin with
"-" (hyphen).
.sp
.LP
If \fBgetopt()\fR encounters a short-option character or a long-option string
not described in the \fIopstring\fR argument, it returns the question-mark (?)
character. If it detects a missing option-argument, it also returns the
question-mark (?) character, unless the first character of the \fIoptstring\fR
argument was a colon (:), in which case \fBgetopt()\fR returns the colon (:)
character. For short options, \fBgetopt()\fR sets the variable \fIoptopt\fR to
the option character that caused the error. For long options, \fIoptopt\fR is
set to the hyphen (-) character and the failing long option can be identified
through \fIargv\fR[\fIoptind\fR-1]. If the application has not set the variable
\fIopterr\fR to 0 and the first character of \fIoptstring\fR is not a colon
(:), \fBgetopt()\fR also prints a diagnostic message to \fBstderr\fR.
.SH RETURN VALUES
.LP
The \fBgetopt()\fR function returns the short-option character associated with
the option recognized.
.sp
.LP
A colon (:) is returned if \fBgetopt()\fR detects a missing argument and the
first character of \fIoptstring\fR was a colon (:).
.sp
.LP
A question mark (?) is returned if \fBgetopt()\fR encounters an option not
specified in \fIoptstring\fR or detects a missing argument and the first
character of \fIoptstring\fR was not a colon (:).
.sp
.LP
Otherwise, \fBgetopt()\fR returns -1 when all command line options are parsed.
.SH ERRORS
.LP
No errors are defined.
.SH EXAMPLES
.LP
\fBExample 1 \fRParsing Command Line Options
.sp
.LP
The following code fragment shows how you might process the arguments for a
utility that can take the mutually-exclusive options \fBa\fR and \fBb\fR and
the options \fBf\fR and \fBo\fR, both of which require arguments:

.sp
.in +2
.nf
#include <unistd.h>

int
main(int argc, char *argv[ ])
{
    int c;
    int bflg, aflg, errflg;
    char *ifile;
    char *ofile;
    extern char *optarg;
    extern int optind, optopt;
    ...
    while ((c = getopt(argc, argv, ":abf:o:")) != -1) {
        switch(c) {
        case 'a':
            if (bflg)
                errflg++;
            else
                aflg++;
            break;
        case 'b':
            if (aflg)
                errflg++;
            else {
                bflg++;
                bproc();
            }
            break;
        case 'f':
            ifile = optarg;
            break;
        case 'o':
            ofile = optarg;
            break;
        case ':':   /* -f or -o without operand */
            fprintf(stderr,
                   "Option -%c requires an operand\en", optopt);
            errflg++;
            break;
        case '?':
            fprintf(stderr,
                   "Unrecognized option: -%c\en", optopt);
            errflg++;
        }
    }
    if (errflg) {
        fprintf(stderr, "usage: ... ");
        exit(2);
    }
    for ( ; optind < argc; optind++) {
        if (access(argv[optind], R_OK)) {
    ...
}
.fi
.in -2

.sp
.LP
This code accepts any of the following as equivalent:

.sp
.in +2
.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
.in -2

.LP
\fBExample 2 \fRCheck Options and Arguments.
.sp
.LP
The following example parses a set of command line options and prints messages
to standard output for each option and argument that it encounters.

.sp
.in +2
.nf
#include <unistd.h>
#include <stdio.h>
\&...
int c;
char *filename;
extern char *optarg;
extern int optind, optopt, opterr;
\&...
while ((c = getopt(argc, argv, ":abf:")) != -1) {
    switch(c) {
    case 'a':
         printf("a is set\en");
         break;
    case 'b':
         printf("b is set\en");
         break;
    case 'f':
         filename = optarg;
         printf("filename is %s\en", filename);
         break;
    case ':':
         printf("-%c without filename\en", optopt);
         break;
    case '?':
         printf("unknown arg %c\en", optopt);
         break;
    }
}
.fi
.in -2

.sp
.LP
This example can be expanded to be CLIP-compliant by substituting the following
string for the \fIoptstring\fR argument:

.sp
.in +2
.nf
:a(ascii)b(binary)f:(in-file)o:(out-file)V(version)?(help)
.fi
.in -2

.sp
.LP
and by replacing the '?' case processing with:

.sp
.in +2
.nf
case 'V':
    fprintf(stdout, "cmd 1.1\en");
    exit(0);
case '?':
    if (optopt == '?') {
        print_help();
        exit(0);
    }
    if (optopt == '-')
        fprintf(stderr,
            "unrecognized option: %s\en", argv[optind-1]);
    else
        fprintf(stderr,
            "unrecognized option: -%c\en", optopt);
    errflg++;
    break;
.fi
.in -2

.sp
.LP
and by replacing the ':' case processing with:

.sp
.in +2
.nf
case ':':   /* -f or -o without operand */
    if (optopt == '-')
        fprintf(stderr,
            "Option %s requires an operand\en", argv[optind-1]);
    else
        fprintf(stderr,
            "Option -%c requires an operand\en", optopt);
    errflg++;
    break;
.fi
.in -2

.sp
.LP
While not encouraged by the CLIP specification, multiple long-option aliases
can also be assigned as shown in the following example:

.sp
.in +2
.nf
:a(ascii)b(binary):(in-file)(input)o:(outfile)(output)V(version)?(help)
.fi
.in -2

.SH ENVIRONMENT VARIABLES
.LP
See \fBenviron\fR(7) for descriptions of the following environment variables
that affect the execution of \fBgetopt()\fR: \fBLANG\fR, \fBLC_ALL\fR, and
\fBLC_MESSAGES\fR.
.sp
.ne 2
.na
\fB\fBLC_CTYPE\fR\fR
.ad
.RS 12n
Determine the locale for the interpretation of sequences of bytes as characters
in \fIoptstring\fR.
.RE

.SH USAGE
.LP
The \fBgetopt()\fR function does not fully check for mandatory arguments
because there is no unambiguous algorithm to do so. Given an option string
\fBa\fR:\fBb\fR and the input \fB-a\fR \fB-b\fR, \fBgetopt()\fR assumes that
\fB-b\fR is the mandatory argument to the \fB-a\fR option and not that \fB-a\fR
is missing a mandatory argument.  Indeed, the only time a missing
option-argument can be reliably detected is when the option is the final option
on the command line and is not followed by any command arguments.
.sp
.LP
It is a violation of the Basic Utility Command syntax standard (see
\fBIntro\fR(1)) for options with arguments to be grouped with other options, as
in \fBcmd\fR \fB-abo\fR \fIfilename\fR , where \fBa\fR and \fBb\fR are options,
\fBo\fR is an option that requires an argument, and \fIfilename\fR is the
argument to \fBo\fR. Although this syntax is permitted in the current
implementation, it should not be used because it may not be supported in future
releases.  The correct syntax to use is:
.sp
.in +2
.nf
cmd \(miab \(mio filename
.fi
.in -2
.sp

.SH ATTRIBUTES
.LP
See \fBattributes\fR(7) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Committed
_
MT-Level	Unsafe
_
Standard	See below.
.TE

.sp
.LP
For the Basic Utility Command syntax is Standard, see \fBstandards\fR(7).
.SH SEE ALSO
.LP
.BR Intro (1),
.BR getopt (1),
.BR getopts (1),
.BR getopt_long (3C),
.BR getsubopt (3C),
.BR gettext (3C),
.BR setlocale (3C),
.BR attributes (7),
.BR environ (7),
.BR standards (7)