diff options
Diffstat (limited to 'man/man3/getopt.3')
| -rw-r--r-- | man/man3/getopt.3 | 577 |
1 files changed, 577 insertions, 0 deletions
diff --git a/man/man3/getopt.3 b/man/man3/getopt.3 new file mode 100644 index 000000000..02d0ea141 --- /dev/null +++ b/man/man3/getopt.3 @@ -0,0 +1,577 @@ +'\" t +.\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) +.\" and Copyright 2006-2008, Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified Sat Jul 24 19:27:50 1993 by Rik Faith (faith@cs.unc.edu) +.\" Modified Mon Aug 30 22:02:34 1995 by Jim Van Zandt <jrv@vanzandt.mv.com> +.\" longindex is a pointer, has_arg can take 3 values, using consistent +.\" names for optstring and longindex, "\n" in formats fixed. Documenting +.\" opterr and getopt_long_only. Clarified explanations (borrowing heavily +.\" from the source code). +.\" Modified 8 May 1998 by Joseph S. Myers (jsm28@cam.ac.uk) +.\" Modified 990715, aeb: changed `EOF' into `-1' since that is what POSIX +.\" says; moreover, EOF is not defined in <unistd.h>. +.\" Modified 2002-02-16, joey: added information about nonexistent +.\" option character and colon as first option character +.\" Modified 2004-07-28, Michael Kerrisk <mtk.manpages@gmail.com> +.\" Added text to explain how to order both '[-+]' and ':' at +.\" the start of optstring +.\" Modified 2006-12-15, mtk, Added getopt() example program. +.\" +.TH getopt 3 (date) "Linux man-pages (unreleased)" +.SH NAME +getopt, getopt_long, getopt_long_only, +optarg, optind, opterr, optopt \- Parse command-line options +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <unistd.h> +.P +.BI "int getopt(int " argc ", char *" argv [], +.BI " const char *" optstring ); +.P +.BI "extern char *" optarg ; +.BI "extern int " optind ", " opterr ", " optopt ; +.P +.B #include <getopt.h> +.P +.BI "int getopt_long(int " argc ", char *" argv [], +.BI " const char *" optstring , +.BI " const struct option *" longopts ", int *" longindex ); +.BI "int getopt_long_only(int " argc ", char *" argv [], +.BI " const char *" optstring , +.BI " const struct option *" longopts ", int *" longindex ); +.fi +.P +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.P +.BR getopt (): +.nf + _POSIX_C_SOURCE >= 2 || _XOPEN_SOURCE +.fi +.P +.BR getopt_long (), +.BR getopt_long_only (): +.nf + _GNU_SOURCE +.fi +.SH DESCRIPTION +The +.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 +.IR main () +function on program invocation. +An element of \fIargv\fP that starts with \[aq]\-\[aq] +(and is not exactly "\-" or "\-\-") +is an option element. +The characters of this element +(aside from the initial \[aq]\-\[aq]) are option characters. +If +.BR getopt () +is called repeatedly, it returns successively each of the option characters +from each of the option elements. +.P +The variable +.I optind +is the index of the next element to be processed in +.IR argv . +The system initializes this value to 1. +The caller can reset it to 1 to restart scanning of the same +.IR argv , +or when scanning a new argument vector. +.P +If +.BR getopt () +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 +.BR getopt () +can +resume the scan with the following option character or +\fIargv\fP-element. +.P +If there are no more option characters, +.BR getopt () +returns \-1. +Then \fIoptind\fP is the index in \fIargv\fP of the first +\fIargv\fP-element that is not an option. +.P +.I optstring +is a string containing the legitimate option characters. +A legitimate option character is any visible one byte +.BR ascii (7) +character (for which +.BR isgraph (3) +would return nonzero) that is not \[aq]\-\[aq], \[aq]:\[aq], or \[aq];\[aq]. +If such a +character is followed by a colon, the option requires an argument, so +.BR getopt () +places a pointer to the following text in the same +\fIargv\fP-element, or the text of the following \fIargv\fP-element, in +.IR optarg . +Two colons mean an option takes +an optional arg; if there is text in the current \fIargv\fP-element +(i.e., in the same word as the option name itself, for example, "\-oarg"), +then it is returned in \fIoptarg\fP, otherwise \fIoptarg\fP is set to zero. +This is a GNU extension. +If +.I optstring +contains +.B W +followed by a semicolon, then +.B \-W foo +is treated as the long option +.BR \-\-foo . +(The +.B \-W +option is reserved by POSIX.2 for implementation extensions.) +This behavior is a GNU extension, not available with libraries before +glibc 2. +.P +By default, +.BR getopt () +permutes the contents of \fIargv\fP as it +scans, so that eventually all the nonoptions are at the end. +Two other scanning modes are also implemented. +If the first character of +\fIoptstring\fP is \[aq]+\[aq] or the environment variable +.B POSIXLY_CORRECT +is set, then option processing stops as soon as a nonoption argument is +encountered. +If \[aq]+\[aq] is not the first character of +.IR optstring , +it is treated as a normal option. +If +.B POSIXLY_CORRECT +behaviour is required in this case +.I optstring +will contain two \[aq]+\[aq] symbols. +If the first character of \fIoptstring\fP is \[aq]\-\[aq], then +each nonoption \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 +of the scanning mode. +.P +While processing the option list, +.BR getopt () +can detect two kinds of errors: +(1) an option character that was not specified in +.I optstring +and (2) a missing option argument +(i.e., an option at the end of the command line without an expected argument). +Such errors are handled and reported as follows: +.IP \[bu] 3 +By default, +.BR getopt () +prints an error message on standard error, +places the erroneous option character in +.IR optopt , +and returns \[aq]?\[aq] as the function result. +.IP \[bu] +If the caller has set the global variable +.I opterr +to zero, then +.BR getopt () +does not print an error message. +The caller can determine that there was an error by testing whether +the function return value is \[aq]?\[aq]. +(By default, +.I opterr +has a nonzero value.) +.IP \[bu] +If the first character +(following any optional \[aq]+\[aq] or \[aq]\-\[aq] described above) +of \fIoptstring\fP +is a colon (\[aq]:\[aq]), then +.BR getopt () +likewise does not print an error message. +In addition, it returns \[aq]:\[aq] instead of \[aq]?\[aq] to +indicate a missing option argument. +This allows the caller to distinguish the two different types of errors. +.\" +.SS getopt_long() and getopt_long_only() +The +.BR getopt_long () +function works like +.BR getopt () +except that it also accepts long options, started with two dashes. +(If the program accepts only long options, then +.I optstring +should be specified as an empty string (""), not NULL.) +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 +or +.BR "\-\-arg param" . +.P +.I longopts +is a pointer to the first element of an array of +.I struct option +declared in +.I <getopt.h> +as +.P +.in +4n +.EX +struct option { + const char *name; + int has_arg; + int *flag; + int val; +}; +.EE +.in +.P +The meanings of the different fields are: +.TP +.I name +is the name of the long option. +.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 +\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 NULL, then +.BR getopt_long () +returns \fIval\fP. +(For example, the calling program may set \fIval\fP to the equivalent short +option character.) +Otherwise, +.BR getopt_long () +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 +\fIval\fP +is the value to return, or to load into the variable pointed +to by \fIflag\fP. +.P +The last element of the array has to be filled with zeros. +.P +If \fIlongindex\fP is not NULL, it +points to a variable which is set to the index of the long option relative to +.IR longopts . +.P +.BR getopt_long_only () +is like +.BR getopt_long (), +but \[aq]\-\[aq] as well +as "\-\-" can indicate a long option. +If an option that starts with \[aq]\-\[aq] +(not "\-\-") doesn't match a long option, but does match a short option, +it is parsed as a short option instead. +.SH RETURN VALUE +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 \[aq]?\[aq] 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 \[aq]:\[aq], then \[aq]:\[aq] is returned; +otherwise \[aq]?\[aq] is returned. +.P +.BR getopt_long () +and +.BR getopt_long_only () +also return the option +character when a short option is recognized. +For a long option, they +return \fIval\fP if \fIflag\fP is NULL, and 0 otherwise. +Error and \-1 returns are the same as for +.BR getopt (), +plus \[aq]?\[aq] for an +ambiguous match or an extraneous parameter. +.SH ENVIRONMENT +.TP +.B POSIXLY_CORRECT +If this is set, then option processing stops as soon as a nonoption +argument is encountered. +.TP +.B _<PID>_GNU_nonoption_argv_flags_ +This variable was used by +.BR bash (1) +2.0 to communicate to glibc which arguments are the results of +wildcard expansion and so should not be considered as options. +This behavior was removed in +.BR bash (1) +2.01, but the support remains in glibc. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lb lb lbx +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR getopt (), +.BR getopt_long (), +.BR getopt_long_only () +T} Thread safety T{ +.na +.nh +MT-Unsafe race:getopt env +T} +.TE +.SH VERSIONS +POSIX specifies that the +.I argv +array argument should be +.IR const , +but these functions permute its elements +unless the environment variable +.B POSIXLY_CORRECT +is set. +.I const +is used in the actual prototype to be compatible with other systems; +however, this page doesn't show the qualifier, +to avoid confusing readers. +.SH STANDARDS +.TP +.BR getopt () +POSIX.1-2008. +.TP +.BR getopt_long () +.TQ +.BR getopt_long_only () +GNU. +.IP +The use of \[aq]+\[aq] and \[aq]\-\[aq] in +.I optstring +is a GNU extension. +.SH HISTORY +.TP +.BR getopt () +POSIX.1-2001, and POSIX.2. +.P +On some older implementations, +.BR getopt () +was declared in +.IR <stdio.h> . +SUSv1 permitted the declaration to appear in either +.I <unistd.h> +or +.IR <stdio.h> . +POSIX.1-1996 marked the use of +.I <stdio.h> +for this purpose as LEGACY. +POSIX.1-2001 does not require the declaration to appear in +.IR <stdio.h> . +.SH NOTES +A program that scans multiple argument vectors, +or rescans the same vector more than once, +and wants to make use of GNU extensions such as \[aq]+\[aq] +and \[aq]\-\[aq] at the start of +.IR optstring , +or changes the value of +.B POSIXLY_CORRECT +between scans, +must reinitialize +.BR getopt () +by resetting +.I optind +to 0, rather than the traditional value of 1. +(Resetting to 0 forces the invocation of an internal initialization +routine that rechecks +.B POSIXLY_CORRECT +and checks for GNU extensions in +.IR optstring .) +.P +Command-line arguments are parsed in strict order +meaning that an option requiring an argument will consume the next argument, +regardless of whether that argument is the correctly specified option argument +or simply the next option +(in the scenario the user mis-specifies the command line). +For example, if +.I optstring +is specified as "1n:" +and the user specifies the command line arguments incorrectly as +.IR "prog\ \-n\ \-1" , +the +.I \-n +option will be given the +.B optarg +value "\-1", and the +.I \-1 +option will be considered to have not been specified. +.SH EXAMPLES +.SS getopt() +The following trivial example program uses +.BR getopt () +to handle two program options: +.IR \-n , +with no associated value; and +.IR "\-t val" , +which expects an associated value. +.P +.\" SRC BEGIN (getopt.c) +.EX +#include <stdio.h> +#include <stdlib.h> +#include <unistd.h> +\& +int +main(int argc, char *argv[]) +{ + int flags, opt; + int nsecs, tfnd; +\& + nsecs = 0; + tfnd = 0; + flags = 0; + while ((opt = getopt(argc, argv, "nt:")) != \-1) { + switch (opt) { + case \[aq]n\[aq]: + flags = 1; + break; + case \[aq]t\[aq]: + nsecs = atoi(optarg); + tfnd = 1; + break; + default: /* \[aq]?\[aq] */ + fprintf(stderr, "Usage: %s [\-t nsecs] [\-n] name\en", + argv[0]); + exit(EXIT_FAILURE); + } + } +\& + printf("flags=%d; tfnd=%d; nsecs=%d; optind=%d\en", + flags, tfnd, nsecs, optind); +\& + if (optind >= argc) { + fprintf(stderr, "Expected argument after options\en"); + exit(EXIT_FAILURE); + } +\& + printf("name argument = %s\en", argv[optind]); +\& + /* Other code omitted */ +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SS getopt_long() +The following example program illustrates the use of +.BR getopt_long () +with most of its features. +.P +.\" SRC BEGIN (getopt_long.c) +.EX +#include <getopt.h> +#include <stdio.h> /* for printf */ +#include <stdlib.h> /* for exit */ +\& +int +main(int argc, char *argv[]) +{ + int c; + int digit_optind = 0; +\& + while (1) { + int this_option_optind = optind ? optind : 1; + int option_index = 0; + static struct option long_options[] = { + {"add", required_argument, 0, 0 }, + {"append", no_argument, 0, 0 }, + {"delete", required_argument, 0, 0 }, + {"verbose", no_argument, 0, 0 }, + {"create", required_argument, 0, \[aq]c\[aq]}, + {"file", required_argument, 0, 0 }, + {0, 0, 0, 0 } + }; +\& + c = getopt_long(argc, argv, "abc:d:012", + long_options, &option_index); + if (c == \-1) + break; +\& + switch (c) { + case 0: + printf("option %s", long_options[option_index].name); + if (optarg) + printf(" with arg %s", optarg); + printf("\en"); + break; +\& + case \[aq]0\[aq]: + case \[aq]1\[aq]: + case \[aq]2\[aq]: + if (digit_optind != 0 && digit_optind != this_option_optind) + printf("digits occur in two different argv\-elements.\en"); + digit_optind = this_option_optind; + printf("option %c\en", c); + break; +\& + case \[aq]a\[aq]: + printf("option a\en"); + break; +\& + case \[aq]b\[aq]: + printf("option b\en"); + break; +\& + case \[aq]c\[aq]: + printf("option c with value \[aq]%s\[aq]\en", optarg); + break; +\& + case \[aq]d\[aq]: + printf("option d with value \[aq]%s\[aq]\en", optarg); + break; +\& + case \[aq]?\[aq]: + break; +\& + default: + printf("?? getopt returned character code 0%o ??\en", c); + } + } +\& + if (optind < argc) { + printf("non\-option ARGV\-elements: "); + while (optind < argc) + printf("%s ", argv[optind++]); + printf("\en"); + } +\& + exit(EXIT_SUCCESS); +} +.EE +.\" SRC END +.SH SEE ALSO +.BR getopt (1), +.BR getsubopt (3) |