'\" te .\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. .\" Copyright 1989 AT&T .\" Portions Copyright (c) 2001, the Institute of Electrical and Electronics Engineers, Inc. and The Open Group. All Rights Reserved. .\" 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 Sun OS 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] .TH GETOPT 3C "Oct 16, 2007" .SH NAME getopt \- command option parsing .SH SYNOPSIS .SS "SVID3, XPG3" .LP .nf #include \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 \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 .sp .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 .sp .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 .sp .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 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 #include \&... 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 .sp .LP See \fBenviron\fR(5) 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 .sp .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 .sp .LP See \fBattributes\fR(5) 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(5). .SH SEE ALSO .sp .LP \fBIntro\fR(1), \fBgetopt\fR(1), \fBgetopts\fR(1), \fBgetsubopt\fR(3C), \fBgettext\fR(3C), \fBsetlocale\fR(3C), \fBattributes\fR(5), \fBenviron\fR(5), \fBstandards\fR(5)