1getsubopt(3C) Standard C Library Functions getsubopt(3C)
2
6 getsubopt - parse suboption arguments from a string
7
9 #include <stdlib.h>
10 int getsubopt(char **optionp, char * const *keylistp, char **valuep);
12
15 The getsubopt() function parses suboption arguments in a flag argument.
16 Such options often result from the use of getopt(3C).
17 The getsubopt() argument optionp is a pointer to a pointer to the
20 option argument string. The suboption arguments are separated by commas
21 and each can consist of either a single token or a token-value pair
22 separated by an equal sign.
23 The keylistp argument is a pointer to a vector of strings. The end of
26 the vector is identified by a null pointer. Each entry in the vector is
27 one of the possible tokens that might be found in *optionp. Since com‐
28 mas delimit suboption arguments in optionp, they should not appear in
29 any of the strings pointed to by keylistp. Similarly, because an equal
30 sign separates a token from its value, the application should not
31 include an equal sign in any of the strings pointed to by keylistp.
32 The valuep argument is the address of a value string pointer.
35 If a comma appears in optionp, it is interpreted as a suboption separa‐
38 tor. After commas have been processed, if there are one or more equal
39 signs in a suboption string, the first equal sign in any suboption
40 string is interpreted as a separator between a token and a value. Sub‐
41 sequent equal signs in a suboption string are interpreted as part of
42 the value.
43 If the string at *optionp contains only one suboption argument (equiva‐
46 lently, no commas), getsubopt() updates *optionp to point to the null
47 character at the end of the string. Otherwise, it isolates the subop‐
48 tion argument by replacing the comma separator with a null character
49 and updates *optionp to point to the start of the next suboption argu‐
50 ment. If the suboption argument has an associated value (equivalently,
51 contains an equal sign), getsubopt() updates *valuep to point to the
52 value's first character. Otherwise, it sets *valuep to a null pointer.
53 The calling application can use this information to determine whether
54 the presence or absence of a value for the suboption is an error.
55 Additionally, when getsubopt() fails to match the suboption with a
58 token in the keylistp array, the calling application should decide if
59 this is an error or if the unrecognized option should be processed in
60 another way.
61
63 The getsubopt() function returns the index of the matched token string
64 or -1 if no token strings were matched.
65
67 No errors are defined.
68
70 Example 1 Use getsubopt() to process options.
71 The following example demonstrates the processing of options to the
74 mount(1M) utility using getsubopt().
75 #include <stdlib.h>
78 char *myopts[] = {
80 #define READONLY 0
81 "ro",
82 #define READWRITE 1
83 "rw",
84 #define WRITESIZE 2
85 "wsize",
86 #define READSIZE 3
87 "rsize",
88 NULL};
89 main(argc, argv)
91 int argc;
92 char **argv;
93 {
94 int sc, c, errflag;
95 char *options, *value;
96 extern char *optarg;
97 extern int optind;
98 .
99 .
100 .
101 while((c = getopt(argc, argv, "abf:o:")) != -1) {
102 switch (c) {
103 case 'a': /* process a option */
104 break;
105 case 'b': /* process b option */
106 break;
107 case 'f':
108 ofile = optarg;
109 break;
110 case '?':
111 errflag++;
112 break;
113 case 'o':
114 options = optarg;
115 while (*options != '\0') {
116 switch(getsubopt(&options,myopts,&value)){
117 case READONLY : /* process ro option */
118 break;
119 case READWRITE : /* process rw option */
120 break;
121 case WRITESIZE : /* process wsize option */
122 if (value == NULL) {
123 error_no_arg();
124 errflag++;
125 } else
126 write_size = atoi(value);
127 break;
128 case READSIZE : /* process rsize option */
129 if (value == NULL) {
130 error_no_arg();
131 errflag++;
132 } else
133 read_size = atoi(value);
134 break;
135 default :
136 /* process unknown token */
137 error_bad_token(value);
138 errflag++;
139 break;
140 }
141 }
142 break;
143 }
144 }
145 if (errflag) {
146 /* print usage instructions etc. */
147 }
148 for (; optind<argc; optind++) {
149 /* process remaining arguments */
150 }
151 .
152 .
153 .
154 }
155 Example 2 Parse suboptions.
158 The following example uses the getsubopt() function to parse a value
161 argument in the optarg external variable returned by a call to
162 getopt(3C).
163 #include <stdlib.h>
166 ...
167 char *tokens[] = {"HOME", "PATH", "LOGNAME", (char *) NULL };
168 char *value;
169 int opt, index;
170 while ((opt = getopt(argc, argv, "e:")) != -1) {
171 switch(opt) {
172 case 'e' :
173 while ((index = getsubopt(&optarg, tokens, &value)) != -1) {
174 switch(index) {
175 ...
176 }
177 break;
178 ...
179 }
180 }
181
184 See attributes(5) for descriptions of the following attributes:
185 ┌─────────────────────────────┬─────────────────────────────┐
190 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
191 ├─────────────────────────────┼─────────────────────────────┤
192 │Interface Stability │Standard │
193 ├─────────────────────────────┼─────────────────────────────┤
194 │MT-Level │MT-Safe │
195 └─────────────────────────────┴─────────────────────────────┘
196
198 mount(1M), getopt(3C), attributes(5), standards(5)
199SunOS 5.11 29 Sep 2005 getsubopt(3C)