1getsubopt(3)               Library Functions Manual               getsubopt(3)
2
3
4

NAME

6       getsubopt - parse suboption arguments from a string
7

LIBRARY

9       Standard C library (libc, -lc)
10

SYNOPSIS

12       #include <stdlib.h>
13
14       int getsubopt(char **restrict optionp, char *const *restrict tokens,
15                     char **restrict valuep);
16
17   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
18
19       getsubopt():
20           _XOPEN_SOURCE >= 500
21               || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L
22

DESCRIPTION

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
31           ro,name=xyz
32
33       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
38       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
48       If  the suboption is recognized, but no value string was found, *valuep
49       is set to NULL.
50
51       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

RETURN VALUE

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
60       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

ATTRIBUTES

65       For an  explanation  of  the  terms  used  in  this  section,  see  at‐
66       tributes(7).
67
68       ┌────────────────────────────────────────────┬───────────────┬─────────┐
69Interface                                   Attribute     Value   
70       ├────────────────────────────────────────────┼───────────────┼─────────┤
71getsubopt()                                 │ Thread safety │ MT-Safe │
72       └────────────────────────────────────────────┴───────────────┴─────────┘
73

STANDARDS

75       POSIX.1-2008.
76

HISTORY

78       POSIX.1-2001.
79

NOTES

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

EXAMPLES

85       The following program expects suboptions following a "-o" option.
86
87       #define _XOPEN_SOURCE 500
88       #include <stdio.h>
89       #include <stdlib.h>
90
91       #include <assert.h>
92
93       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
111           int readonly = 0;
112           int readwrite = 0;
113           char *name = NULL;
114           int errfnd = 0;
115
116           while ((opt = getopt(argc, argv, "o:")) != -1) {
117               switch (opt) {
118               case 'o':
119                   subopts = optarg;
120                   while (*subopts != '\0' && !errfnd) {
121
122                       switch (getsubopt(&subopts, token, &value)) {
123                       case RO_OPT:
124                           readonly = 1;
125                           break;
126
127                       case RW_OPT:
128                           readwrite = 1;
129                           break;
130
131                       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
140                           name = value;
141                           break;
142
143                       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
158               default:
159                   errfnd = 1;
160               }
161           }
162
163           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
170           /* Remainder of program... */
171
172           exit(EXIT_SUCCESS);
173       }
174

SEE ALSO

176       getopt(3)
177
178
179
180Linux man-pages 6.04              2023-03-30                      getsubopt(3)
Impressum