release/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 .SH 名前
  29 getsubopt \- 文字列中のサブオプション引き数の解釈を行う
  30 .SH 書式
  31 .B #include <stdlib.h>
  32
  33 .BI "int getsubopt(char **"optionp ", char * const *" tokens \
  34 ", char **" valuep );
  35 .sp
  36 .in -4n
  37 glibc 向けの機能検査マクロの要件
  38 .RB ( feature_test_macros (7)
  39 参照):
  40 .in
  41 .sp
  42 .BR getsubopt ():
  43 .ad l
  44 .RS 4
  45 .PD 0
  46 _XOPEN_SOURCE\ >= 500 ||
  47 _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED
  48 .br
  49 || /* Since glibc 2.12: */ _POSIX_C_SOURCE\ >=\ 200809L
  50 .PD
  51 .RE
  52 .ad
  53 .SH 説明
  54 .BR getsubopt ()
  55 は、
  56 .I optionp
  57 で与えられたカンマ区切りのサブオプション・リストを解析する。
  58 (このようなサブオプション・リストは
  59 .BR getopt (3)
  60 を使ってコマンドラインを解釈した場合に現れることが多い。
  61 例えば、
  62 .BR mount (8)
  63 の \fI-o\fP オプションを見るとよい。)
  64 それぞれのサブオプションには対応する値を指定することができる。
  65 サブオプションの名前と対応する値は等号 (\(aq=\(aq) で区切られる。
  66 例えば、以下のような文字列を
  67 .I optionp
  68 に渡すことができる。
  69 .sp
  70 .in +4n
  71 .B ro,name=xyz
  72 .in
  73
  74 .I tokens
  75 引き数はトークンへのポインタの配列へのポインタで、
  76 配列は NULL で終端される。
  77 .BR getsubopt ()
  78 はこのトークンを
  79 .I optionp
  80 内で探す。
  81 それぞれのトークンは、NULL 終端された 1文字以上の文字列で、
  82 他のトークンと区別できる必要がある。
  83 また、等号とカンマを含んではならない。
  84
  85 .BR getsubopt ()
  86 は呼び出されるたびに、
  87 .I optionp
  88 中の次の未処理のサブオプションの情報を返す。
  89 サブオプション内に等号があった場合、最初の等号は
  90 そのサブオプションの名前と値の区切りと解釈される。
  91 区切りから次のカンマ (最後のサブオプションの場合、文字列の末尾)
  92 までが、サブオプションの値となる。
  93 サブオプションの名前が
  94 .I tokens
  95 内の名前と一致し、値を表す文字列が見つかった場合、
  96 .BR getsubopt ()
  97 は
  98 .I *valuep
  99 を値を表す文字列のアドレスに設定する。
 100 .I optionp
 101 中の最初のカンマはヌルバイトで上書きされる。そのため、
 102 .I *valuep
 103 はそのサブオプションの「値の文字列」そのものとなる。
 104
 105 サブオプションが認識されたが、値を表す文字列が見つからなかった場合、
 106 .RI * valuep
 107 は NULL に設定される。
 108
 109 .BR getsubopt ()
 110 が返る時、
 111 .I optionp
 112 は次のサブオプションを指している。
 113 ちょうど最後のサブオプションが処理された場合は、
 114 文字列末尾のヌルバイト (\(aq\\0\(aq) を指している。
 115 .SH 返り値
 116 .I optionp
 117 内でサブオプションが見つかった場合、
 118 .BR getsubopt ()
 119 は最初のサブオプションにマッチする
 120 .I tokens
 121 の要素の添字を返す。
 122 見つからなかった場合、\-1 を返す。この場合、
 123 .I *valuep
 124 は
 125 .IB name [= value ]
 126 の文字列全体となる。
 127
 128 .I *optionp
 129 は変更されるので、
 130 .BR getsubopt ()
 131 を呼び出す前の最初のサブオプションは
 132 .BR getsubopt ()
 133 を呼び出し後のサブオプションと必ずしも同じとは限らない。
 134 .SH 準拠
 135 POSIX.1-2001.
 136 .SH 注意
 137
 138 .BR getsubopt ()
 139 は、文字列
 140 .RI * optionp
 141 中に見つけたカンマを上書きするので、文字列
 142 .I *optionp
 143 は書き込み可能でなければならず、
 144 文字列定数にすることはできない。
 145 .SH 例
 146 以下のプログラムは "\-o" オプションに続いてサブオプションがあることを
 147 期待している。
 148
 149 .nf
 150 #define _XOPEN_SOURCE 500
 151 #include <stdlib.h>
 152 #include <assert.h>
 153 #include <stdio.h>
 154
 155 int main(int argc, char **argv)
 156 {
 157     enum {
 158         RO_OPT = 0,
 159         RW_OPT,
 160         NAME_OPT
 161     };
 162     char *const token[] = {
 163         [RO_OPT]   = "ro",
 164         [RW_OPT]   = "rw",
 165         [NAME_OPT] = "name",
 166         NULL
 167     };
 168     char *subopts;
 169     char *value;
 170     int opt;
 171
 172     int readonly = 0;
 173     int readwrite = 0;
 174     char *name = NULL;
 175     int errfnd = 0;
 176
 177     while ((opt = getopt(argc, argv, "o:")) != \-1) {
 178         switch (opt) {
 179         case \(aqo\(aq:
 180             subopts = optarg;
 181             while (*subopts != \(aq\\0\(aq && !errfnd) {
 182
 183             switch (getsubopt(&subopts, token, &value)) {
 184             case RO_OPT:
 185                 readonly = 1;
 186                 break;
 187
 188             case RW_OPT:
 189                 readwrite = 1;
 190                 break;
 191
 192             case NAME_OPT:
 193                 if (value == NULL) {
 194                     fprintf(stderr, "Missing value for "
 195                             "suboption \(aq%s\(aq\\n", token[NAME_OPT]);
 196                     errfnd = 1;
 197                     continue;
 198                 }
 199
 200                 name = value;
 201                 break;
 202
 203             default:
 204                 fprintf(stderr, "No match found "
 205                         "for token: /%s/\\n", value);
 206                 errfnd = 1;
 207                 break;
 208             }
 209         }
 210         if (readwrite && readonly) {
 211             fprintf(stderr, "Only one of \(aq%s\(aq and \(aq%s\(aq can be "
 212                     "specified\\n", token[RO_OPT], token[RW_OPT]);
 213             errfnd = 1;
 214         }
 215         break;
 216
 217         default:
 218             errfnd = 1;
 219         }
 220     }
 221
 222     if (errfnd || argc == 1) {
 223         fprintf(stderr, "\\nUsage: %s \-o <suboptstring>\\n", argv[0]);
 224         fprintf(stderr, "suboptions are \(aqro\(aq, \(aqrw\(aq, "
 225                 "and \(aqname=<value>\(aq\\n");
 226         exit(EXIT_FAILURE);
 227     }
 228
 229     /* Remainder of program... */
 230
 231     exit(EXIT_SUCCESS);
 232 }
 233 .fi
 234 .SH 関連項目
 235 .BR getopt (3)