Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

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)