diff options
Diffstat (limited to 'man3/getopt.3')
| -rw-r--r-- | man3/getopt.3 | 577 |
1 files changed, 0 insertions, 577 deletions
diff --git a/man3/getopt.3 b/man3/getopt.3 deleted file mode 100644 index 71c3675..0000000 --- a/man3/getopt.3 +++ /dev/null @@ -1,577 +0,0 @@ -'\" 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 2023-10-31 "Linux man-pages 6.7" -.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) |