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)