1GETSUBOPT(3) Linux Programmer's Manual GETSUBOPT(3)
2
3
4
6 getsubopt - parse suboption arguments from a string
7
9 #include <stdlib.h>
10
11 int getsubopt(char **optionp, char * const *tokens, char **valuep);
12
13 Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
14
15 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
27 ro,name=xyz
28
29 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
34 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
44 If the suboption is recognized, but no value string was found, *valuep
45 is set to NULL.
46
47 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
56 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
64 ┌────────────┬───────────────┬─────────┐
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
79 #define _XOPEN_SOURCE 500
80 #include <stdlib.h>
81 #include <assert.h>
82 #include <stdio.h>
83
84 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
102 int readonly = 0;
103 int readwrite = 0;
104 char *name = NULL;
105 int errfnd = 0;
106
107 while ((opt = getopt(argc, argv, "o:")) != -1) {
108 switch (opt) {
109 case 'o':
110 subopts = optarg;
111 while (*subopts != '\0' && !errfnd) {
112
113 switch (getsubopt(&subopts, token, &value)) {
114 case RO_OPT:
115 readonly = 1;
116 break;
117
118 case RW_OPT:
119 readwrite = 1;
120 break;
121
122 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
130 name = value;
131 break;
132
133 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
147 default:
148 errfnd = 1;
149 }
150 }
151
152 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
159 /* Remainder of program... */
160
161 exit(EXIT_SUCCESS);
162 }
163
165 getopt(3)
166
168 This page is part of release 4.15 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/.
172
173
174
175GNU 2017-09-15 GETSUBOPT(3)