Debian Codegraph @

upstream/debian-unstable/man3/getsubopt.3

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