summaryrefslogtreecommitdiffstats
path: root/man3/getsubopt.3
diff options
context:
space:
mode:
Diffstat (limited to 'man3/getsubopt.3')
-rw-r--r--man3/getsubopt.3251
1 files changed, 0 insertions, 251 deletions
diff --git a/man3/getsubopt.3 b/man3/getsubopt.3
deleted file mode 100644
index caf03a2..0000000
--- a/man3/getsubopt.3
+++ /dev/null
@@ -1,251 +0,0 @@
-'\" 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 2023-10-31 "Linux man-pages 6.7"
-.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)