Merging upstream version 6.8.

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

1 files changed, 251 insertions, 0 deletions

diff --git a/man/man3/getsubopt.3 b/man/man3/getsubopt.3
new file mode 100644
index 0000000..99bb4dd
--- /dev/null
+++ b/man/man3/getsubopt.3
@@ -0,0 +1,251 @@
+'\" t
+.\" Copyright (C) 2007 Michael Kerrisk <mtk.manpages@gmail.com>
+.\" and Copyright (C) 2007 Justin Pryzby <pryzbyj@justinpryzby.com>
+.\"
+.\" %%%LICENSE_START(PERMISSIVE_MISC)
+.\" Permission is hereby granted, free of charge, to any person obtaining
+.\" a copy of this software and associated documentation files (the
+.\" "Software"), to deal in the Software without restriction, including
+.\" without limitation the rights to use, copy, modify, merge, publish,
+.\" distribute, sublicense, and/or sell copies of the Software, and to
+.\" permit persons to whom the Software is furnished to do so, subject to
+.\" the following conditions:
+.\"
+.\" The above copyright notice and this permission notice shall be
+.\" included in all copies or substantial portions of the Software.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+.\" EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+.\" IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+.\" CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+.\" TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+.\" SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+.\" %%%LICENSE_END
+.\"
+.TH getsubopt 3 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+getsubopt \- parse suboption arguments from a string
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <stdlib.h>
+.P
+.BI "int getsubopt(char **restrict " optionp ", char *const *restrict " tokens ,
+.BI "              char **restrict " valuep );
+.fi
+.P
+.RS -4
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.RE
+.P
+.BR getsubopt ():
+.nf
+    _XOPEN_SOURCE >= 500
+.\"    || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
+        || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L
+.fi
+.SH DESCRIPTION
+.BR getsubopt ()
+parses the list of comma-separated suboptions provided in
+.IR optionp .
+(Such a suboption list is typically produced when
+.BR getopt (3)
+is used to parse a command line;
+see for example the \fI\-o\fP option of
+.BR mount (8).)
+Each suboption may include an associated value,
+which is separated from the suboption name by an equal sign.
+The following is an example of the kind of string
+that might be passed in
+.IR optionp :
+.P
+.in +4n
+.EX
+.B ro,name=xyz
+.EE
+.in
+.P
+The
+.I tokens
+argument is a pointer to a NULL-terminated array of pointers to the tokens that
+.BR getsubopt ()
+will look for in
+.IR optionp .
+The tokens should be distinct, null-terminated strings containing at
+least one character, with no embedded equal signs or commas.
+.P
+Each call to
+.BR getsubopt ()
+returns information about the next unprocessed suboption in
+.IR optionp .
+The first equal sign in a suboption (if any) is interpreted as a
+separator between the name and the value of that suboption.
+The value extends to the next comma,
+or (for the last suboption) to the end of the string.
+If the name of the suboption matches a known name from
+.IR tokens ,
+and a value string was found,
+.BR getsubopt ()
+sets
+.I *valuep
+to the address of that string.
+The first comma in
+.I optionp
+is overwritten with a null byte, so
+.I *valuep
+is precisely the "value string" for that suboption.
+.P
+If the suboption is recognized, but no value string was found,
+.I *valuep
+is set to NULL.
+.P
+When
+.BR getsubopt ()
+returns,
+.I optionp
+points to the next suboption,
+or to the null byte (\[aq]\e0\[aq]) at the end of the
+string if the last suboption was just processed.
+.SH RETURN VALUE
+If the first suboption in
+.I optionp
+is recognized,
+.BR getsubopt ()
+returns the index of the matching suboption element in
+.IR tokens .
+Otherwise, \-1 is returned and
+.I *valuep
+is the entire
+.IB name [= value ]
+string.
+.P
+Since
+.I *optionp
+is changed, the first suboption before the call to
+.BR getsubopt ()
+is not (necessarily) the same as the first suboption after
+.BR getsubopt ().
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface	Attribute	Value
+T{
+.na
+.nh
+.BR getsubopt ()
+T}	Thread safety	MT-Safe
+.TE
+.SH STANDARDS
+POSIX.1-2008.
+.SH HISTORY
+POSIX.1-2001.
+.SH NOTES
+Since
+.BR getsubopt ()
+overwrites any commas it finds in the string
+.IR *optionp ,
+that string must be writable; it cannot be a string constant.
+.SH EXAMPLES
+The following program expects suboptions following a "\-o" option.
+.P
+.\" SRC BEGIN (getsubopt.c)
+.EX
+#define _XOPEN_SOURCE 500
+#include <stdio.h>
+#include <stdlib.h>
+\&
+#include <assert.h>
+\&
+int
+main(int argc, char *argv[])
+{
+    enum {
+        RO_OPT = 0,
+        RW_OPT,
+        NAME_OPT
+    };
+    char *const token[] = {
+        [RO_OPT]   = "ro",
+        [RW_OPT]   = "rw",
+        [NAME_OPT] = "name",
+        NULL
+    };
+    char *subopts;
+    char *value;
+    int opt;
+\&
+    int readonly = 0;
+    int readwrite = 0;
+    char *name = NULL;
+    int errfnd = 0;
+\&
+    while ((opt = getopt(argc, argv, "o:")) != \-1) {
+        switch (opt) {
+        case \[aq]o\[aq]:
+            subopts = optarg;
+            while (*subopts != \[aq]\e0\[aq] && !errfnd) {
+\&
+                switch (getsubopt(&subopts, token, &value)) {
+                case RO_OPT:
+                    readonly = 1;
+                    break;
+\&
+                case RW_OPT:
+                    readwrite = 1;
+                    break;
+\&
+                case NAME_OPT:
+                    if (value == NULL) {
+                        fprintf(stderr,
+                                "Missing value for suboption \[aq]%s\[aq]\en",
+                                token[NAME_OPT]);
+                        errfnd = 1;
+                        continue;
+                    }
+\&
+                    name = value;
+                    break;
+\&
+                default:
+                    fprintf(stderr,
+                            "No match found for token: /%s/\en", value);
+                    errfnd = 1;
+                    break;
+                }
+            }
+            if (readwrite && readonly) {
+                fprintf(stderr,
+                        "Only one of \[aq]%s\[aq] and \[aq]%s\[aq] can be specified\en",
+                        token[RO_OPT], token[RW_OPT]);
+                errfnd = 1;
+            }
+            break;
+\&
+        default:
+            errfnd = 1;
+        }
+    }
+\&
+    if (errfnd || argc == 1) {
+        fprintf(stderr, "\enUsage: %s \-o <suboptstring>\en", argv[0]);
+        fprintf(stderr,
+                "suboptions are \[aq]ro\[aq], \[aq]rw\[aq], and \[aq]name=<value>\[aq]\en");
+        exit(EXIT_FAILURE);
+    }
+\&
+    /* Remainder of program... */
+\&
+    exit(EXIT_SUCCESS);
+}
+.EE
+.\" SRC END
+.SH SEE ALSO
+.BR getopt (3)