man3/getsubopt.3

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