getsubopt(3)

1GETSUBOPT(3)               Linux Programmer's Manual              GETSUBOPT(3)
2
3
4

NAME

6       getsubopt - parse suboption arguments from a string
7

SYNOPSIS

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

DESCRIPTION

20       getsubopt()  parses  the list of comma-separated suboptions provided in
21       optionp.  (Such a suboption list is typically produced  when  getopt(3)
22       is  used  to  parse  a  command  line; see for example the -o option of
23       mount(8).)  Each suboption may include an associated  value,  which  is
24       separated  from  the suboption name by an equal sign.  The following is
25       an example of the kind of string that might be passed in optionp:
26
27           ro,name=xyz
28
29       The tokens argument is a pointer to a NULL-terminated array of pointers
30       to  the  tokens  that getsubopt() will look for in optionp.  The tokens
31       should be distinct, null-terminated strings  containing  at  least  one
32       character, with no embedded equal signs or commas.
33
34       Each call to getsubopt() returns information about the next unprocessed
35       suboption in optionp.  The first equal sign in a suboption (if any)  is
36       interpreted  as a separator between the name and the value of that sub‐
37       option.  The value extends to the next comma, or (for the  last  subop‐
38       tion) to the end of the string.  If the name of the suboption matches a
39       known name from tokens, and a value string was found, getsubopt()  sets
40       *valuep  to  the address of that string.  The first comma in optionp is
41       overwritten with a null  byte,  so  *valuep  is  precisely  the  "value
42       string" for that suboption.
43
44       If  the suboption is recognized, but no value string was found, *valuep
45       is set to NULL.
46
47       When getsubopt() returns, optionp points to the next suboption,  or  to
48       the null byte ('\0') at the end of the string if the last suboption was
49       just processed.
50

RETURN VALUE

52       If the first suboption in optionp is  recognized,  getsubopt()  returns
53       the  index  of the matching suboption element in tokens.  Otherwise, -1
54       is returned and *valuep is the entire name[=value] string.
55
56       Since *optionp is changed, the first suboption before the call to  get‐
57       subopt()  is  not  (necessarily)  the same as the first suboption after
58       getsubopt().
59

CONFORMING TO

61       POSIX.1-2001.
62

NOTES

64       Since  getsubopt()  overwrites  any  commas  it  finds  in  the  string
65       *optionp, that string must be writable; it cannot be a string constant.
66

EXAMPLE

68       The following program expects suboptions following a "-o" option.
69
70       #define _XOPEN_SOURCE 500
71       #include <stdlib.h>
72       #include <assert.h>
73       #include <stdio.h>
74
75       int main(int argc, char **argv)
76       {
77           enum {
78               RO_OPT = 0,
79               RW_OPT,
80               NAME_OPT
81           };
82           char *const token[] = {
83               [RO_OPT]   = "ro",
84               [RW_OPT]   = "rw",
85               [NAME_OPT] = "name",
86               NULL
87           };
88           char *subopts;
89           char *value;
90           int opt;
91
92           int readonly = 0;
93           int readwrite = 0;
94           char *name = NULL;
95           int errfnd = 0;
96
97           while ((opt = getopt(argc, argv, "o:")) != -1) {
98               switch (opt) {
99               case 'o':
100                   subopts = optarg;
101                   while (*subopts != '\0' && !errfnd) {
102
103                   switch (getsubopt(&subopts, token, &value)) {
104                   case RO_OPT:
105                       readonly = 1;
106                       break;
107
108                   case RW_OPT:
109                       readwrite = 1;
110                       break;
111
112                   case NAME_OPT:
113                       if (value == NULL) {
114                           fprintf(stderr, "Missing value for "
115                                   "suboption '%s'\n", token[NAME_OPT]);
116                           errfnd = 1;
117                           continue;
118                       }
119
120                       name = value;
121                       break;
122
123                   default:
124                       fprintf(stderr, "No match found "
125                               "for token: /%s/\n", value);
126                       errfnd = 1;
127                       break;
128                   }
129               }
130               if (readwrite && readonly) {
131                   fprintf(stderr, "Only one of '%s' and '%s' can be "
132                           "specified\n", token[RO_OPT], token[RW_OPT]);
133                   errfnd = 1;
134               }
135               break;
136
137               default:
138                   errfnd = 1;
139               }
140           }
141
142           if (errfnd || argc == 1) {
143               fprintf(stderr, "\nUsage: %s -o <suboptstring>\n", argv[0]);
144               fprintf(stderr, "suboptions are 'ro', 'rw', "
145                       "and 'name=<value>'\n");
146               exit(EXIT_FAILURE);
147           }
148
149           /* Remainder of program... */
150
151           exit(EXIT_SUCCESS);
152       }
153

COLOPHON

158       This  page  is  part of release 3.53 of the Linux man-pages project.  A
159       description of the project, and information about reporting  bugs,  can
160       be found at http://www.kernel.org/doc/man-pages/.
161
162
163
164GNU                               2010-09-26                      GETSUBOPT(3)