diff options
Diffstat (limited to 'man-pages-posix-2013/man1p/getopts.1p')
| -rw-r--r-- | man-pages-posix-2013/man1p/getopts.1p | 445 |
1 files changed, 445 insertions, 0 deletions
diff --git a/man-pages-posix-2013/man1p/getopts.1p b/man-pages-posix-2013/man1p/getopts.1p new file mode 100644 index 0000000..baf210d --- /dev/null +++ b/man-pages-posix-2013/man1p/getopts.1p @@ -0,0 +1,445 @@ +'\" et +.TH GETOPTS "1P" 2013 "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 +getopts +\(em parse utility options +.SH SYNOPSIS +.LP +.nf +getopts \fIoptstring name \fB[\fIarg\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR getopts +utility shall retrieve options and option-arguments from a list of +parameters. It shall support the Utility Syntax Guidelines 3 to 10, +inclusive, described in the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +Each time it is invoked, the +.IR getopts +utility shall place the value of the next option in the shell variable +specified by the +.IR name +operand and the index of the next argument to be processed in the shell +variable +.IR OPTIND . +Whenever the shell is invoked, +.IR OPTIND +shall be initialized to 1. +.P +When the option requires an option-argument, the +.IR getopts +utility shall place it in the shell variable +.IR OPTARG . +If no option was found, or if the option that was found does not have +an option-argument, +.IR OPTARG +shall be unset. +.P +If an option character not contained in the +.IR optstring +operand is found where an option character is expected, the shell +variable specified by +.IR name +shall be set to the +<question-mark> +(\c +.BR '?' ) +character. In this case, if the first character in +.IR optstring +is a +<colon> +(\c +.BR ':' ), +the shell variable +.IR OPTARG +shall be set to the option character found, but no output shall be +written to standard error; otherwise, the shell variable +.IR OPTARG +shall be unset and a diagnostic message shall be written to standard +error. This condition shall be considered to be an error detected in +the way arguments were presented to the invoking application, but shall +not be an error in +.IR getopts +processing. +.P +If an option-argument is missing: +.IP " *" 4 +If the first character of +.IR optstring +is a +<colon>, +the shell variable specified by +.IR name +shall be set to the +<colon> +character and the shell variable +.IR OPTARG +shall be set to the option character found. +.IP " *" 4 +Otherwise, the shell variable specified by +.IR name +shall be set to the +<question-mark> +character, the shell variable +.IR OPTARG +shall be unset, and a diagnostic message shall be written to standard +error. This condition shall be considered to be an error detected in +the way arguments were presented to the invoking application, but shall +not be an error in +.IR getopts +processing; a diagnostic message shall be written as stated, but the +exit status shall be zero. +.P +When the end of options is encountered, the +.IR getopts +utility shall exit with a return value greater than zero; the shell +variable +.IR OPTIND +shall be set to the index of the first operand, or the value +.BR \(dq$#\(dq +1 +if there are no operands; the +.IR name +variable shall be set to the +<question-mark> +character. Any of the following shall identify the end of options: +the first +.BR \(dq\(mi\|\(mi\(dq +argument that is not an option-argument, finding an argument that is +not an option-argument and does not begin with a +.BR '\(mi' , +or encountering an error. +.P +The shell variables +.IR OPTIND +and +.IR OPTARG +shall be local to the caller of +.IR getopts +and shall not be exported by default. +.P +The shell variable specified by the +.IR name +operand, +.IR OPTIND , +and +.IR OPTARG +shall affect the current shell execution environment; see +.IR "Section 2.12" ", " "Shell Execution Environment". +.P +If the application sets +.IR OPTIND +to the value 1, a new set of parameters can be used: either the +current positional parameters or new +.IR arg +values. Any other attempt to invoke +.IR getopts +multiple times in a single shell execution environment with parameters +(positional parameters or +.IR arg +operands) that are not the same in all invocations, or with an +.IR OPTIND +value modified to be a value other than 1, produces unspecified +results. +.SH OPTIONS +None. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIoptstring\fR" 10 +A string containing the option characters recognized by the utility +invoking +.IR getopts . +If a character is followed by a +<colon>, +the option shall be expected to have an argument, which should be supplied +as a separate argument. Applications should specify an option character +and its option-argument as separate arguments, but +.IR getopts +shall interpret the characters following an option character requiring +arguments as an argument whether or not this is done. An explicit null +option-argument need not be recognized if it is not supplied as a +separate argument when +.IR getopts +is invoked. (See also the +\fIgetopt\fR() +function defined in the System Interfaces volume of POSIX.1\(hy2008.) The characters +<question-mark> +and +<colon> +shall not be used as option characters by an application. The use of +other option characters that are not alphanumeric produces unspecified +results. If the option-argument is not supplied as a separate argument +from the option character, the value in +.IR OPTARG +shall be stripped of the option character and the +.BR '\(mi' . +The first character in +.IR optstring +determines how +.IR getopts +behaves if an option character is not known or an option-argument is +missing. +.IP "\fIname\fR" 10 +The name of a shell variable that shall be set by the +.IR getopts +utility to the option character that was found. +.P +The +.IR getopts +utility by default shall parse positional parameters passed to the +invoking shell procedure. If +.IR arg s +are given, they shall be parsed instead of the positional parameters. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR getopts : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2008, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +Determine the locale for the interpretation of sequences of bytes of +text data as characters (for example, single-byte as opposed to +multi-byte characters in arguments and input files). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fIOPTIND\fP" 10 +This variable shall be used by the +.IR getopts +utility as the index of the next argument to be processed. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +Whenever an error is detected and the first character in the +.IR optstring +operand is not a +<colon> +(\c +.BR ':' ), +a diagnostic message shall be written to standard error with the +following information in an unspecified format: +.IP " *" 4 +The invoking program name shall be identified in the message. The +invoking program name shall be the value of the shell special parameter +0 (see +.IR "Section 2.5.2" ", " "Special Parameters") +at the time the +.IR getopts +utility is invoked. A name equivalent to: +.RS 4 +.sp +.RS 4 +.nf +\fB +basename "$0" +.fi \fR +.P +.RE +.P +may be used. +.RE +.IP " *" 4 +If an option is found that was not specified in +.IR optstring , +this error is identified and the invalid option character shall be +identified in the message. +.IP " *" 4 +If an option requiring an option-argument is found, but an +option-argument is not found, this error shall be identified and the +invalid option character shall be identified in the message. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +An option, specified or unspecified by +.IR optstring , +was found. +.IP >0 6 +The end of options was encountered or an error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Since +.IR getopts +affects the current shell execution environment, it is generally +provided as a shell regular built-in. If it is called in a subshell or +separate utility execution environment, such as one of the following: +.sp +.RS 4 +.nf +\fB +(getopts abc value "$@") +nohup getopts ... +find . \(miexec getopts ... \e; +.fi \fR +.P +.RE +.P +it does not affect the shell variables in the caller's environment. +.P +Note that shell functions share +.IR OPTIND +with the calling shell even though the positional parameters are +changed. If the calling shell and any of its functions uses +.IR getopts +to parse arguments, the results are unspecified. +.SH EXAMPLES +The following example script parses and displays its arguments: +.sp +.RS 4 +.nf +\fB +aflag= +bflag= +while getopts ab: name +do + case $name in + a) aflag=1;; + b) bflag=1 + bval="$OPTARG";; + ?) printf "Usage: %s: [\(mia] [\(mib value] args\en" $0 + exit 2;; + esac +done +if [ ! \(miz "$aflag" ]; then + printf "Option \(mia specified\en" +fi +if [ ! \(miz "$bflag" ]; then + printf 'Option \(mib "%s" specified\en' "$bval" +fi +shift $(($OPTIND \(mi 1)) +printf "Remaining arguments are: %s\en$*" +.fi \fR +.P +.RE +.SH RATIONALE +The +.IR getopts +utility was chosen in preference to the System V +.IR getopt +utility because +.IR getopts +handles option-arguments containing +<blank> +characters. +.P +The +.IR OPTARG +variable is not mentioned in the ENVIRONMENT VARIABLES section because +it does not affect the execution of +.IR getopts ; +it is one of the few ``output-only'' variables used by the standard +utilities. +.P +The +<colon> +is not allowed as an option character because that is not historical +behavior, and it violates the Utility Syntax Guidelines. The +<colon> +is now specified to behave as in the KornShell version of the +.IR getopts +utility; when used as the first character in the +.IR optstring +operand, it disables diagnostics concerning missing option-arguments +and unexpected option characters. This replaces the use of the +.IR OPTERR +variable that was specified in an early proposal. +.P +The formats of the diagnostic messages produced by the +.IR getopts +utility and the +\fIgetopt\fR() +function are not fully specified because implementations with superior +(``friendlier'') formats objected to the formats used by some +historical implementations. The standard developers considered it +important that the information in the messages used be uniform between +.IR getopts +and +\fIgetopt\fR(). +Exact duplication of the messages might not be possible, particularly +if a utility is built on another system that has a different +\fIgetopt\fR() +function, but the messages must have specific information included so +that the program name, invalid option character, and type of error can +be distinguished by a user. +.P +Only a rare application program intercepts a +.IR getopts +standard error message and wants to parse it. Therefore, +implementations are free to choose the most usable messages they can +devise. The following formats are used by many historical +implementations: +.sp +.RS 4 +.nf +\fB +"%s: illegal option \(mi\|\(mi %c\en", <\fIprogram name\fP>, <\fIoption character\fP> +.P +"%s: option requires an argument \(mi\|\(mi %c\en", <\fIprogram name\fP>, \e + <\fIoption character\fP> +.fi \fR +.P +.RE +.P +Historical shells with built-in versions of +\fIgetopt\fR() +or +.IR getopts +have used different formats, frequently not even indicating the option +character found in error. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.5.2" ", " "Special Parameters" +.P +The Base Definitions volume of POSIX.1\(hy2008, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.P +The System Interfaces volume of POSIX.1\(hy2008, +.IR "\fIgetopt\fR\^(\|)" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, Copyright (C) 2013 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. +(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) 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.unix.org/online.html . + +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 . |