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       #define _XOPEN_SOURCE 500
10       #include <stdlib.h>
11
12       int getsubopt(char **optionp, char * const *tokens, char **valuep);
13

DESCRIPTION

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

RETURN VALUE

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

CONFORMING TO

56       POSIX.1-2001.
57

NOTES

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

EXAMPLE

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

COLOPHON

153       This  page  is  part of release 3.25 of the Linux man-pages project.  A
154       description of the project, and information about reporting  bugs,  can
155       be found at http://www.kernel.org/doc/man-pages/.
156
157
158
159GNU                               2008-05-29                      GETSUBOPT(3)