]>
Commit | Line | Data |
---|---|---|
c11b1abf | 1 | .\" Copyright (C) 2007 Michael Kerrisk <mtk.manpages@gmail.com> |
f37855d1 | 2 | .\" and Copyright (C) 2007 Justin Pryzby <pryzbyj@justinpryzby.com> |
645259f4 | 3 | .\" |
7c576f45 | 4 | .\" %%%LICENSE_START(PERMISSIVE_MISC) |
645259f4 MK |
5 | .\" Permission is hereby granted, free of charge, to any person obtaining |
6 | .\" a copy of this software and associated documentation files (the | |
7 | .\" "Software"), to deal in the Software without restriction, including | |
8 | .\" without limitation the rights to use, copy, modify, merge, publish, | |
9 | .\" distribute, sublicense, and/or sell copies of the Software, and to | |
10 | .\" permit persons to whom the Software is furnished to do so, subject to | |
11 | .\" the following conditions: | |
12 | .\" | |
13 | .\" The above copyright notice and this permission notice shall be | |
14 | .\" included in all copies or substantial portions of the Software. | |
15 | .\" | |
16 | .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, | |
17 | .\" EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF | |
18 | .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. | |
19 | .\" IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY | |
20 | .\" CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, | |
21 | .\" TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE | |
22 | .\" SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. | |
8ff7380d | 23 | .\" %%%LICENSE_END |
645259f4 | 24 | .\" |
4b8c67d9 | 25 | .TH GETSUBOPT 3 2017-09-15 "GNU" "Linux Programmer's Manual" |
645259f4 MK |
26 | .SH NAME |
27 | getsubopt \- parse suboption arguments from a string | |
28 | .SH SYNOPSIS | |
645259f4 | 29 | .B #include <stdlib.h> |
dbfe9c70 | 30 | .PP |
8a5a7356 MK |
31 | .BI "int getsubopt(char **"optionp ", char * const *" tokens \ |
32 | ", char **" valuep ); | |
68e4db0a | 33 | .PP |
5d73bb75 MK |
34 | .in -4n |
35 | Feature Test Macro Requirements for glibc (see | |
36 | .BR feature_test_macros (7)): | |
37 | .in | |
68e4db0a | 38 | .PP |
5d73bb75 MK |
39 | .BR getsubopt (): |
40 | .ad l | |
41 | .RS 4 | |
3c63ded0 | 42 | .PD 0 |
cf7fa0a1 MK |
43 | _XOPEN_SOURCE\ >= 500 |
44 | .\" || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED | |
3ba63d80 | 45 | .br |
cf7fa0a1 | 46 | || /* Since glibc 2.12: */ _POSIX_C_SOURCE\ >=\ 200809L |
3c63ded0 | 47 | .PD |
5d73bb75 MK |
48 | .RE |
49 | .ad | |
645259f4 MK |
50 | .SH DESCRIPTION |
51 | .BR getsubopt () | |
52 | parses the list of comma-separated suboptions provided in | |
53 | .IR optionp . | |
988db661 | 54 | (Such a suboption list is typically produced when |
645259f4 MK |
55 | .BR getopt (3) |
56 | is used to parse a command line; | |
d7652592 | 57 | see for example the \fI-o\fP option of |
645259f4 MK |
58 | .BR mount (8).) |
59 | Each suboption may include an associated value, | |
60 | which is separated from the suboption name by an equal sign. | |
988db661 MK |
61 | The following is an example of the kind of string |
62 | that might be passed in | |
645259f4 | 63 | .IR optionp : |
bdd915e2 | 64 | .PP |
a6e2f128 | 65 | .in +4n |
bdd915e2 | 66 | .EX |
645259f4 | 67 | .B ro,name=xyz |
bdd915e2 | 68 | .EE |
a6e2f128 | 69 | .in |
847e0d88 | 70 | .PP |
988db661 | 71 | The |
645259f4 | 72 | .I tokens |
a2834faa | 73 | argument is a pointer to a NULL-terminated array of pointers to the tokens that |
fb186734 | 74 | .BR getsubopt () |
988db661 | 75 | will look for in |
645259f4 MK |
76 | .IR optionp . |
77 | The tokens should be distinct, null-terminated strings containing at | |
78 | least one character, with no embedded equal signs or commas. | |
847e0d88 | 79 | .PP |
645259f4 MK |
80 | Each call to |
81 | .BR getsubopt () | |
82 | returns information about the next unprocessed suboption in | |
83 | .IR optionp . | |
84 | The first equal sign in a suboption (if any) is interpreted as a | |
85 | separator between the name and the value of that suboption. | |
86 | The value extends to the next comma, | |
87 | or (for the last suboption) to the end of the string. | |
88 | If the name of the suboption matches a known name from | |
89 | .IR tokens , | |
90 | and a value string was found, | |
91 | .BR getsubopt () | |
92 | sets | |
bd9b2a9c | 93 | .I *valuep |
645259f4 MK |
94 | to the address of that string. |
95 | The first comma in | |
96 | .I optionp | |
97 | is overwritten with a null byte, so | |
bd9b2a9c | 98 | .I *valuep |
645259f4 | 99 | is precisely the "value string" for that suboption. |
847e0d88 | 100 | .PP |
d9bfdb9c | 101 | If the suboption is recognized, but no value string was found, |
bd9b2a9c | 102 | .I *valuep |
645259f4 | 103 | is set to NULL. |
847e0d88 | 104 | .PP |
645259f4 MK |
105 | When |
106 | .BR getsubopt () | |
107 | returns, | |
108 | .I optionp | |
38254b54 | 109 | points to the next suboption, |
836830b4 | 110 | or to the null byte (\(aq\\0\(aq) at the end of the |
645259f4 MK |
111 | string if the last suboption was just processed. |
112 | .SH RETURN VALUE | |
113 | If the first suboption in | |
114 | .I optionp | |
d9bfdb9c | 115 | is recognized, |
645259f4 MK |
116 | .BR getsubopt () |
117 | returns the index of the matching suboption element in | |
acc57a1d | 118 | .IR tokens . |
645259f4 | 119 | Otherwise, \-1 is returned and |
bd9b2a9c | 120 | .I *valuep |
645259f4 MK |
121 | is the entire |
122 | .IB name [= value ] | |
123 | string. | |
847e0d88 | 124 | .PP |
645259f4 | 125 | Since |
bd9b2a9c | 126 | .I *optionp |
645259f4 MK |
127 | is changed, the first suboption before the call to |
128 | .BR getsubopt () | |
129 | is not (necessarily) the same as the first suboption after | |
130 | .BR getsubopt (). | |
631f7a09 | 131 | .SH ATTRIBUTES |
14a6902f MK |
132 | For an explanation of the terms used in this section, see |
133 | .BR attributes (7). | |
134 | .TS | |
135 | allbox; | |
136 | lb lb lb | |
137 | l l l. | |
138 | Interface Attribute Value | |
139 | T{ | |
631f7a09 | 140 | .BR getsubopt () |
14a6902f MK |
141 | T} Thread safety MT-Safe |
142 | .TE | |
645259f4 | 143 | .SH CONFORMING TO |
e2edc2bf | 144 | POSIX.1-2001, POSIX.1-2008. |
645259f4 | 145 | .SH NOTES |
847e0d88 | 146 | .PP |
645259f4 MK |
147 | Since |
148 | .BR getsubopt () | |
149 | overwrites any commas it finds in the string | |
bd9b2a9c | 150 | .IR *optionp , |
645259f4 | 151 | that string must be writable; it cannot be a string constant. |
8af1ba10 | 152 | .SH EXAMPLE |
5633d88a | 153 | The following program expects suboptions following a "\-o" option. |
847e0d88 | 154 | .PP |
207050fa | 155 | .EX |
645259f4 MK |
156 | #define _XOPEN_SOURCE 500 |
157 | #include <stdlib.h> | |
158 | #include <assert.h> | |
159 | #include <stdio.h> | |
160 | ||
57b1aaa4 MK |
161 | int |
162 | main(int argc, char **argv) | |
645259f4 MK |
163 | { |
164 | enum { | |
165 | RO_OPT = 0, | |
166 | RW_OPT, | |
167 | NAME_OPT | |
168 | }; | |
169 | char *const token[] = { | |
170 | [RO_OPT] = "ro", | |
171 | [RW_OPT] = "rw", | |
172 | [NAME_OPT] = "name", | |
173 | NULL | |
174 | }; | |
175 | char *subopts; | |
176 | char *value; | |
177 | int opt; | |
178 | ||
179 | int readonly = 0; | |
180 | int readwrite = 0; | |
181 | char *name = NULL; | |
182 | int errfnd = 0; | |
183 | ||
29059a65 | 184 | while ((opt = getopt(argc, argv, "o:")) != \-1) { |
d4949190 | 185 | switch (opt) { |
f81fb444 | 186 | case \(aqo\(aq: |
645259f4 | 187 | subopts = optarg; |
f81fb444 | 188 | while (*subopts != \(aq\\0\(aq && !errfnd) { |
645259f4 MK |
189 | |
190 | switch (getsubopt(&subopts, token, &value)) { | |
35facf00 MK |
191 | case RO_OPT: |
192 | readonly = 1; | |
193 | break; | |
194 | ||
195 | case RW_OPT: | |
196 | readwrite = 1; | |
197 | break; | |
198 | ||
199 | case NAME_OPT: | |
200 | if (value == NULL) { | |
201 | fprintf(stderr, "Missing value for " | |
f81fb444 | 202 | "suboption \(aq%s\(aq\\n", token[NAME_OPT]); |
645259f4 | 203 | errfnd = 1; |
35facf00 | 204 | continue; |
645259f4 | 205 | } |
35facf00 MK |
206 | |
207 | name = value; | |
208 | break; | |
209 | ||
210 | default: | |
211 | fprintf(stderr, "No match found " | |
212 | "for token: /%s/\\n", value); | |
645259f4 | 213 | errfnd = 1; |
35facf00 | 214 | break; |
645259f4 | 215 | } |
35facf00 MK |
216 | } |
217 | if (readwrite && readonly) { | |
f81fb444 | 218 | fprintf(stderr, "Only one of \(aq%s\(aq and \(aq%s\(aq can be " |
35facf00 MK |
219 | "specified\\n", token[RO_OPT], token[RW_OPT]); |
220 | errfnd = 1; | |
221 | } | |
222 | break; | |
645259f4 MK |
223 | |
224 | default: | |
225 | errfnd = 1; | |
226 | } | |
227 | } | |
228 | ||
229 | if (errfnd || argc == 1) { | |
29059a65 | 230 | fprintf(stderr, "\\nUsage: %s \-o <suboptstring>\\n", argv[0]); |
f81fb444 MK |
231 | fprintf(stderr, "suboptions are \(aqro\(aq, \(aqrw\(aq, " |
232 | "and \(aqname=<value>\(aq\\n"); | |
645259f4 MK |
233 | exit(EXIT_FAILURE); |
234 | } | |
235 | ||
236 | /* Remainder of program... */ | |
237 | ||
238 | exit(EXIT_SUCCESS); | |
239 | } | |
207050fa | 240 | .EE |
645259f4 | 241 | .SH SEE ALSO |
0a4f8b7b | 242 | .BR getopt (3) |