1GETSUBOPT(3) Linux Programmer's Manual GETSUBOPT(3)
2
6 getsubopt - parse suboption arguments from a string
7
9 #include <stdlib.h>
10 int getsubopt(char **optionp, char * const *tokens, char **valuep);
12 Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
14 getsubopt():
16 _XOPEN_SOURCE >= 500
17 || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L
18
20 getsubopt() parses the list of comma-separated suboptions provided in
21 optionp. (Such a suboption list is typically produced when getopt(3)
22 is used to parse a command line; see for example the -o option of
23 mount(8).) Each suboption may include an associated value, which is
24 separated from the suboption name by an equal sign. The following is
25 an example of the kind of string that might be passed in optionp:
26 ro,name=xyz
28 The tokens argument is a pointer to a NULL-terminated array of pointers
30 to the tokens that getsubopt() will look for in optionp. The tokens
31 should be distinct, null-terminated strings containing at least one
32 character, with no embedded equal signs or commas.
33 Each call to getsubopt() returns information about the next unprocessed
35 suboption in optionp. The first equal sign in a suboption (if any) is
36 interpreted as a separator between the name and the value of that sub‐
37 option. The value extends to the next comma, or (for the last subop‐
38 tion) to the end of the string. If the name of the suboption matches a
39 known name from tokens, and a value string was found, getsubopt() sets
40 *valuep to the address of that string. The first comma in optionp is
41 overwritten with a null byte, so *valuep is precisely the "value
42 string" for that suboption.
43 If the suboption is recognized, but no value string was found, *valuep
45 is set to NULL.
46 When getsubopt() returns, optionp points to the next suboption, or to
48 the null byte ('\0') at the end of the string if the last suboption was
49 just processed.
50
52 If the first suboption in optionp is recognized, getsubopt() returns
53 the index of the matching suboption element in tokens. Otherwise, -1
54 is returned and *valuep is the entire name[=value] string.
55 Since *optionp is changed, the first suboption before the call to get‐
57 subopt() is not (necessarily) the same as the first suboption after
58 getsubopt().
59
61 For an explanation of the terms used in this section, see
62 attributes(7).
63 ┌────────────┬───────────────┬─────────┐
65 │Interface │ Attribute │ Value │
66 ├────────────┼───────────────┼─────────┤
67 │getsubopt() │ Thread safety │ MT-Safe │
68 └────────────┴───────────────┴─────────┘
70 POSIX.1-2001, POSIX.1-2008.
71
73 Since getsubopt() overwrites any commas it finds in the string
74 *optionp, that string must be writable; it cannot be a string constant.
75
77 The following program expects suboptions following a "-o" option.
78 #define _XOPEN_SOURCE 500
80 #include <stdlib.h>
81 #include <assert.h>
82 #include <stdio.h>
83 int
85 main(int argc, char **argv)
86 {
87 enum {
88 RO_OPT = 0,
89 RW_OPT,
90 NAME_OPT
91 };
92 char *const token[] = {
93 [RO_OPT] = "ro",
94 [RW_OPT] = "rw",
95 [NAME_OPT] = "name",
96 NULL
97 };
98 char *subopts;
99 char *value;
100 int opt;
101 int readonly = 0;
103 int readwrite = 0;
104 char *name = NULL;
105 int errfnd = 0;
106 while ((opt = getopt(argc, argv, "o:")) != -1) {
108 switch (opt) {
109 case 'o':
110 subopts = optarg;
111 while (*subopts != '\0' && !errfnd) {
112 switch (getsubopt(&subopts, token, &value)) {
114 case RO_OPT:
115 readonly = 1;
116 break;
117 case RW_OPT:
119 readwrite = 1;
120 break;
121 case NAME_OPT:
123 if (value == NULL) {
124 fprintf(stderr, "Missing value for "
125 "suboption '%s'\n", token[NAME_OPT]);
126 errfnd = 1;
127 continue;
128 }
129 name = value;
131 break;
132 default:
134 fprintf(stderr, "No match found "
135 "for token: /%s/\n", value);
136 errfnd = 1;
137 break;
138 }
139 }
140 if (readwrite && readonly) {
141 fprintf(stderr, "Only one of '%s' and '%s' can be "
142 "specified\n", token[RO_OPT], token[RW_OPT]);
143 errfnd = 1;
144 }
145 break;
146 default:
148 errfnd = 1;
149 }
150 }
151 if (errfnd || argc == 1) {
153 fprintf(stderr, "\nUsage: %s -o <suboptstring>\n", argv[0]);
154 fprintf(stderr, "suboptions are 'ro', 'rw', "
155 "and 'name=<value>'\n");
156 exit(EXIT_FAILURE);
157 }
158 /* Remainder of program... */
160 exit(EXIT_SUCCESS);
162 }
163
165 getopt(3)
166
168 This page is part of release 5.04 of the Linux man-pages project. A
169 description of the project, information about reporting bugs, and the
170 latest version of this page, can be found at
171 https://www.kernel.org/doc/man-pages/.
172GNU 2019-03-06 GETSUBOPT(3)