draft/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 .\" Permission is hereby granted, free of charge, to any person obtaining
   5 .\" a copy of this software and associated documentation files (the
   6 .\" "Software"), to deal in the Software without restriction, including
   7 .\" without limitation the rights to use, copy, modify, merge, publish,
   8 .\" distribute, sublicense, and/or sell copies of the Software, and to
   9 .\" permit persons to whom the Software is furnished to do so, subject to
  10 .\" the following conditions:
  11 .\"
  12 .\" The above copyright notice and this permission notice shall be
  13 .\" included in all copies or substantial portions of the Software.
  14 .\"
  15 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  16 .\" EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  17 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
  18 .\" IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
  19 .\" CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
  20 .\" TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
  21 .\" SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  22 .\"
  23 .\" Japanese Version Copyright (c) 2007  Akihiro MOTOKI
  24 .\"         all rights reserved.
  25 .\" Translated 2007-06-02, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>
  26 .\"
  27 .TH GETSUBOPT 3 2010-09-26 "GNU" "Linux Programmer's Manual"
  28 .\"O .SH NAME
  29 .SH Ì¾Á°
  30 .\"O getsubopt \- parse suboption arguments from a string
  31 getsubopt \- Ê¸»úÎóÃæ¤Î¥µ¥Ö¥ª¥×¥·¥ç¥ó°ú¤¿ô¤Î²ò¼á¤ò¹Ô¤¦
  32 .\"O .SH SYNOPSIS
  33 .SH ½ñ¼°
  34 .B #include <stdlib.h>
  35
  36 .BI "int getsubopt(char **"optionp ", char * const *" tokens \
  37 ", char **" valuep );
  38 .sp
  39 .in -4n
  40 .\"O Feature Test Macro Requirements for glibc (see
  41 .\"O .BR feature_test_macros (7)):
  42 glibc ¸þ¤±¤Îµ¡Ç½¸¡ºº¥Þ¥¯¥í¤ÎÍ×·ï
  43 .RB ( feature_test_macros (7)
  44 »²¾È):
  45 .in
  46 .sp
  47 .BR getsubopt ():
  48 .ad l
  49 .RS 4
  50 .PD 0
  51 _XOPEN_SOURCE\ >= 500 ||
  52 _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED
  53 .br
  54 || /* Since glibc 2.12: */ _POSIX_C_SOURCE\ >=\ 200809L
  55 .PD
  56 .RE
  57 .ad
  58 .\"O .SH DESCRIPTION
  59 .SH ÀâÌÀ
  60 .\"O .BR getsubopt ()
  61 .\"O parses the list of comma-separated suboptions provided in
  62 .\"O .IR optionp .
  63 .\"O (Such a suboption list is typically produced when
  64 .\"O .BR getopt (3)
  65 .\"O is used to parse a command line;
  66 .\"O see for example the \fI-o\fP option of
  67 .\"O .BR mount (8).)
  68 .\"O Each suboption may include an associated value,
  69 .\"O which is separated from the suboption name by an equal sign.
  70 .\"O The following is an example of the kind of string
  71 .\"O that might be passed in
  72 .\"O .IR optionp :
  73 .BR getsubopt ()
  74 ¤Ï¡¢
  75 .I optionp
  76 ¤ÇÍ¿¤¨¤é¤ì¤¿¥«¥ó¥Þ¶èÀÚ¤ê¤Î¥µ¥Ö¥ª¥×¥·¥ç¥ó¡¦¥ê¥¹¥È¤ò²òÀÏ¤¹¤ë¡£
  77 (¤³¤Î¤è¤¦¤Ê¥µ¥Ö¥ª¥×¥·¥ç¥ó¡¦¥ê¥¹¥È¤Ï
  78 .BR getopt (3)
  79 ¤ò»È¤Ã¤Æ¥³¥Þ¥ó¥É¥é¥¤¥ó¤ò²ò¼á¤·¤¿¾ì¹ç¤Ë¸½¤ì¤ë¤³¤È¤¬Â¿¤¤¡£
  80 Îã¤¨¤Ð¡¢
  81 .BR mount (8)
  82 ¤Î \fI-o\fP ¥ª¥×¥·¥ç¥ó¤ò¸«¤ë¤È¤è¤¤¡£)
  83 ¤½¤ì¤¾¤ì¤Î¥µ¥Ö¥ª¥×¥·¥ç¥ó¤Ë¤ÏÂÐ±þ¤¹¤ëÃÍ¤ò»ØÄê¤¹¤ë¤³¤È¤¬¤Ç¤¤ë¡£
  84 ¥µ¥Ö¥ª¥×¥·¥ç¥ó¤ÎÌ¾Á°¤ÈÂÐ±þ¤¹¤ëÃÍ¤ÏÅù¹æ (\(aq=\(aq) ¤Ç¶èÀÚ¤é¤ì¤ë¡£
  85 Îã¤¨¤Ð¡¢°Ê²¼¤Î¤è¤¦¤ÊÊ¸»úÎó¤ò
  86 .I optionp
  87 ¤ËÅÏ¤¹¤³¤È¤¬¤Ç¤¤ë¡£
  88 .sp
  89 .in +4n
  90 .B ro,name=xyz
  91 .in
  92
  93 .\"O The
  94 .\"O .I tokens
  95 .\"O argument is a pointer to a NULL-terminated array of pointers to the tokens that
  96 .\"O .BR getsubopt ()
  97 .\"O will look for in
  98 .\"O .IR optionp .
  99 .\"O The tokens should be distinct, null-terminated strings containing at
 100 .\"O least one character, with no embedded equal signs or commas.
 101 .I tokens
 102 °ú¤¿ô¤Ï¥È¡¼¥¯¥ó¤Ø¤Î¥Ý¥¤¥ó¥¿¤ÎÇÛÎó¤Ø¤Î¥Ý¥¤¥ó¥¿¤Ç¡¢
 103 ÇÛÎó¤Ï NULL ¤Ç½ªÃ¼¤µ¤ì¤ë¡£
 104 .BR getsubopt ()
 105 ¤Ï¤³¤Î¥È¡¼¥¯¥ó¤ò
 106 .I optionp
 107 Æâ¤ÇÃµ¤¹¡£
 108 ¤½¤ì¤¾¤ì¤Î¥È¡¼¥¯¥ó¤Ï¡¢NULL ½ªÃ¼¤µ¤ì¤¿ 1Ê¸»ú°Ê¾å¤ÎÊ¸»úÎó¤Ç¡¢
 109 Â¾¤Î¥È¡¼¥¯¥ó¤È¶èÊÌ¤Ç¤¤ëÉ¬Í×¤¬¤¢¤ë¡£
 110 ¤Þ¤¿¡¢Åù¹æ¤È¥«¥ó¥Þ¤ò´Þ¤ó¤Ç¤Ï¤Ê¤é¤Ê¤¤¡£
 111
 112 .\"O Each call to
 113 .\"O .BR getsubopt ()
 114 .\"O returns information about the next unprocessed suboption in
 115 .\"O .IR optionp .
 116 .BR getsubopt ()
 117 ¤Ï¸Æ¤Ó½Ð¤µ¤ì¤ë¤¿¤Ó¤Ë¡¢
 118 .I optionp
 119 Ãæ¤Î¼¡¤ÎÌ¤½èÍý¤Î¥µ¥Ö¥ª¥×¥·¥ç¥ó¤Î¾ðÊó¤òÊÖ¤¹¡£
 120 .\"O The first equal sign in a suboption (if any) is interpreted as a
 121 .\"O separator between the name and the value of that suboption.
 122 .\"O The value extends to the next comma,
 123 .\"O or (for the last suboption) to the end of the string.
 124 ¥µ¥Ö¥ª¥×¥·¥ç¥óÆâ¤ËÅù¹æ¤¬¤¢¤Ã¤¿¾ì¹ç¡¢ºÇ½é¤ÎÅù¹æ¤Ï
 125 ¤½¤Î¥µ¥Ö¥ª¥×¥·¥ç¥ó¤ÎÌ¾Á°¤ÈÃÍ¤Î¶èÀÚ¤ê¤È²ò¼á¤µ¤ì¤ë¡£
 126 ¶èÀÚ¤ê¤«¤é¼¡¤Î¥«¥ó¥Þ (ºÇ¸å¤Î¥µ¥Ö¥ª¥×¥·¥ç¥ó¤Î¾ì¹ç¡¢Ê¸»úÎó¤ÎËöÈø)
 127 ¤Þ¤Ç¤¬¡¢¥µ¥Ö¥ª¥×¥·¥ç¥ó¤ÎÃÍ¤È¤Ê¤ë¡£
 128 .\"O If the name of the suboption matches a known name from
 129 .\"O .IR tokens ,
 130 .\"O and a value string was found,
 131 .\"O .BR getsubopt ()
 132 .\"O sets
 133 .\"O .I *valuep
 134 .\"O to the address of that string.
 135 ¥µ¥Ö¥ª¥×¥·¥ç¥ó¤ÎÌ¾Á°¤¬
 136 .I tokens
 137 Æâ¤ÎÌ¾Á°¤È°ìÃ×¤·¡¢ÃÍ¤òÉ½¤¹Ê¸»úÎó¤¬¸«¤Ä¤«¤Ã¤¿¾ì¹ç¡¢
 138 .BR getsubopt ()
 139 ¤Ï
 140 .I *valuep
 141 ¤òÃÍ¤òÉ½¤¹Ê¸»úÎó¤Î¥¢¥É¥ì¥¹¤ËÀßÄê¤¹¤ë¡£
 142 .\"O The first comma in
 143 .\"O .I optionp
 144 .\"O is overwritten with a null byte, so
 145 .\"O .I *valuep
 146 .\"O is precisely the "value string" for that suboption.
 147 .I optionp
 148 Ãæ¤ÎºÇ½é¤Î¥«¥ó¥Þ¤Ï¥Ì¥ë¥Ð¥¤¥È¤Ç¾å½ñ¤¤µ¤ì¤ë¡£¤½¤Î¤¿¤á¡¢
 149 .I *valuep
 150 ¤Ï¤½¤Î¥µ¥Ö¥ª¥×¥·¥ç¥ó¤Î¡ÖÃÍ¤ÎÊ¸»úÎó¡×¤½¤Î¤â¤Î¤È¤Ê¤ë¡£
 151
 152 .\"O If the suboption is recognized, but no value string was found,
 153 .\"O .RI * valuep
 154 .\"O is set to NULL.
 155 ¥µ¥Ö¥ª¥×¥·¥ç¥ó¤¬Ç§¼±¤µ¤ì¤¿¤¬¡¢ÃÍ¤òÉ½¤¹Ê¸»úÎó¤¬¸«¤Ä¤«¤é¤Ê¤«¤Ã¤¿¾ì¹ç¡¢
 156 .RI * valuep
 157 ¤Ï NULL ¤ËÀßÄê¤µ¤ì¤ë¡£
 158
 159 .\"O When
 160 .\"O .BR getsubopt ()
 161 .\"O returns,
 162 .\"O .I optionp
 163 .\"O points to the next suboption,
 164 .\"O or to the null byte (\(aq\\0\(aq) at the end of the
 165 .\"O string if the last suboption was just processed.
 166 .BR getsubopt ()
 167 ¤¬ÊÖ¤ë»þ¡¢
 168 .I optionp
 169 ¤Ï¼¡¤Î¥µ¥Ö¥ª¥×¥·¥ç¥ó¤ò»Ø¤·¤Æ¤¤¤ë¡£
 170 ¤Á¤ç¤¦¤ÉºÇ¸å¤Î¥µ¥Ö¥ª¥×¥·¥ç¥ó¤¬½èÍý¤µ¤ì¤¿¾ì¹ç¤Ï¡¢
 171 Ê¸»úÎóËöÈø¤Î¥Ì¥ë¥Ð¥¤¥È (\(aq\\0\(aq) ¤ò»Ø¤·¤Æ¤¤¤ë¡£
 172 .\"O .SH RETURN VALUE
 173 .SH ÊÖ¤êÃÍ
 174 .\"O If the first suboption in
 175 .\"O .I optionp
 176 .\"O is recognized,
 177 .\"O .BR getsubopt ()
 178 .\"O returns the index of the matching suboption element in
 179 .\"O .IR tokens .
 180 .\"O Otherwise, \-1 is returned and
 181 .\"O .I *valuep
 182 .\"O is the entire
 183 .\"O .IB name [= value ]
 184 .\"O string.
 185 .I optionp
 186 Æâ¤Ç¥µ¥Ö¥ª¥×¥·¥ç¥ó¤¬¸«¤Ä¤«¤Ã¤¿¾ì¹ç¡¢
 187 .BR getsubopt ()
 188 ¤ÏºÇ½é¤Î¥µ¥Ö¥ª¥×¥·¥ç¥ó¤Ë¥Þ¥Ã¥Á¤¹¤ë
 189 .I tokens
 190 ¤ÎÍ×ÁÇ¤ÎÅº»ú¤òÊÖ¤¹¡£
 191 ¸«¤Ä¤«¤é¤Ê¤«¤Ã¤¿¾ì¹ç¡¢\-1 ¤òÊÖ¤¹¡£¤³¤Î¾ì¹ç¡¢
 192 .I *valuep
 193 ¤Ï
 194 .IB name [= value ]
 195 ¤ÎÊ¸»úÎóÁ´ÂÎ¤È¤Ê¤ë¡£
 196
 197 .\"O Since
 198 .\"O .I *optionp
 199 .\"O is changed, the first suboption before the call to
 200 .\"O .BR getsubopt ()
 201 .\"O is not (necessarily) the same as the first suboption after
 202 .\"O .BR getsubopt ().
 203 .I *optionp
 204 ¤ÏÊÑ¹¹¤µ¤ì¤ë¤Î¤Ç¡¢
 205 .BR getsubopt ()
 206 ¤ò¸Æ¤Ó½Ð¤¹Á°¤ÎºÇ½é¤Î¥µ¥Ö¥ª¥×¥·¥ç¥ó¤Ï
 207 .BR getsubopt ()
 208 ¤ò¸Æ¤Ó½Ð¤·¸å¤Î¥µ¥Ö¥ª¥×¥·¥ç¥ó¤ÈÉ¬¤º¤·¤âÆ±¤¸¤È¤Ï¸Â¤é¤Ê¤¤¡£
 209 .\"O .SH CONFORMING TO
 210 .SH ½àµò
 211 POSIX.1-2001.
 212 .\"O .SH NOTES
 213 .SH Ãí°Õ
 214
 215 .\"O Since
 216 .\"O .BR getsubopt ()
 217 .\"O overwrites any commas it finds in the string
 218 .\"O .I *optionp ,
 219 .\"O that string must be writable; it cannot be a string constant.
 220 .BR getsubopt ()
 221 ¤Ï¡¢Ê¸»úÎó
 222 .RI * optionp
 223 Ãæ¤Ë¸«¤Ä¤±¤¿¥«¥ó¥Þ¤ò¾å½ñ¤¤¹¤ë¤Î¤Ç¡¢Ê¸»úÎó
 224 .I *optionp
 225 ¤Ï½ñ¤¹þ¤ß²ÄÇ½¤Ç¤Ê¤±¤ì¤Ð¤Ê¤é¤º¡¢
 226 Ê¸»úÎóÄê¿ô¤Ë¤¹¤ë¤³¤È¤Ï¤Ç¤¤Ê¤¤¡£
 227 .\"O .SH EXAMPLE
 228 .SH Îã
 229 .\"O The following program expects suboptions following a "\-o" option.
 230 °Ê²¼¤Î¥×¥í¥°¥é¥à¤Ï "\-o" ¥ª¥×¥·¥ç¥ó¤ËÂ³¤¤¤Æ¥µ¥Ö¥ª¥×¥·¥ç¥ó¤¬¤¢¤ë¤³¤È¤ò
 231 ´üÂÔ¤·¤Æ¤¤¤ë¡£
 232
 233 .nf
 234 #define _XOPEN_SOURCE 500
 235 #include <stdlib.h>
 236 #include <assert.h>
 237 #include <stdio.h>
 238
 239 int main(int argc, char **argv)
 240 {
 241     enum {
 242         RO_OPT = 0,
 243         RW_OPT,
 244         NAME_OPT
 245     };
 246     char *const token[] = {
 247         [RO_OPT]   = "ro",
 248         [RW_OPT]   = "rw",
 249         [NAME_OPT] = "name",
 250         NULL
 251     };
 252     char *subopts;
 253     char *value;
 254     int opt;
 255
 256     int readonly = 0;
 257     int readwrite = 0;
 258     char *name = NULL;
 259     int errfnd = 0;
 260
 261     while ((opt = getopt(argc, argv, "o:")) != \-1) {
 262         switch (opt) {
 263         case \(aqo\(aq:
 264             subopts = optarg;
 265             while (*subopts != \(aq\\0\(aq && !errfnd) {
 266
 267             switch (getsubopt(&subopts, token, &value)) {
 268             case RO_OPT:
 269                 readonly = 1;
 270                 break;
 271
 272             case RW_OPT:
 273                 readwrite = 1;
 274                 break;
 275
 276             case NAME_OPT:
 277                 if (value == NULL) {
 278                     fprintf(stderr, "Missing value for "
 279                             "suboption \(aq%s\(aq\\n", token[NAME_OPT]);
 280                     errfnd = 1;
 281                     continue;
 282                 }
 283
 284                 name = value;
 285                 break;
 286
 287             default:
 288                 fprintf(stderr, "No match found "
 289                         "for token: /%s/\\n", value);
 290                 errfnd = 1;
 291                 break;
 292             }
 293         }
 294         if (readwrite && readonly) {
 295             fprintf(stderr, "Only one of \(aq%s\(aq and \(aq%s\(aq can be "
 296                     "specified\\n", token[RO_OPT], token[RW_OPT]);
 297             errfnd = 1;
 298         }
 299         break;
 300
 301         default:
 302             errfnd = 1;
 303         }
 304     }
 305
 306     if (errfnd || argc == 1) {
 307         fprintf(stderr, "\\nUsage: %s \-o <suboptstring>\\n", argv[0]);
 308         fprintf(stderr, "suboptions are \(aqro\(aq, \(aqrw\(aq, "
 309                 "and \(aqname=<value>\(aq\\n");
 310         exit(EXIT_FAILURE);
 311     }
 312
 313     /* Remainder of program... */
 314
 315     exit(EXIT_SUCCESS);
 316 }
 317 .fi
 318 .\"O .SH SEE ALSO
 319 .SH ´ØÏ¢¹àÌÜ
 320 .BR getopt (3)