summaryrefslogtreecommitdiffstats
path: root/man/man3/getopt.3
diff options
context:
space:
mode:
Diffstat (limited to 'man/man3/getopt.3')
-rw-r--r--man/man3/getopt.3577
1 files changed, 577 insertions, 0 deletions
diff --git a/man/man3/getopt.3 b/man/man3/getopt.3
new file mode 100644
index 0000000..828394a
--- /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 2024-05-02 "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)