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