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 .\" %%%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 .\"*******************************************************************
  26 .\"
  27 .\" This file was generated with po4a. Translate the source file.
  28 .\"
  29 .\"*******************************************************************
  30 .\"
  31 .\" Japanese Version Copyright (c) 2007  Akihiro MOTOKI
  32 .\"         all rights reserved.
  33 .\" Translated 2007-06-02, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>
  34 .\"
  35 .TH GETSUBOPT 3 2014\-04\-08 GNU "Linux Programmer's Manual"
  36 .SH 名前
  37 getsubopt \- 文字列中のサブオプション引き数の解釈を行う
  38 .SH 書式
  39 \fB#include <stdlib.h>\fP
  40
  41 \fBint getsubopt(char **\fP\fIoptionp\fP\fB, char * const *\fP\fItokens\fP\fB, char
  42 **\fP\fIvaluep\fP\fB);\fP
  43 .sp
  44 .in -4n
  45 glibc 向けの機能検査マクロの要件 (\fBfeature_test_macros\fP(7)  参照):
  46 .in
  47 .sp
  48 \fBgetsubopt\fP():
  49 .ad l
  50 .RS 4
  51 .PD 0
  52 _XOPEN_SOURCE\ >= 500 || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED
  53 .br
  54 || /* Since glibc 2.12: */ _POSIX_C_SOURCE\ >=\ 200809L
  55 .PD
  56 .RE
  57 .ad
  58 .SH 説明
  59 \fBgetsubopt\fP()  は、 \fIoptionp\fP で与えられたカンマ区切りのサブオプション・リストを解析する。
  60 (このようなサブオプション・リストは \fBgetopt\fP(3)  を使ってコマンドラインを解釈した場合に現れることが多い。 例えば、
  61 \fBmount\fP(8)  の \fI\-o\fP オプションを見るとよい。)  それぞれのサブオプションには対応する値を指定することができる。
  62 サブオプションの名前と対応する値は等号 (\(aq=\(aq) で区切られる。 例えば、以下のような文字列を \fIoptionp\fP に渡すことができる。
  63 .sp
  64 .in +4n
  65 \fBro,name=xyz\fP
  66 .in
  67
  68 \fItokens\fP 引き数はトークンへのポインタの配列へのポインタで、 配列は NULL で終端される。 \fBgetsubopt\fP()
  69 はこのトークンを \fIoptionp\fP 内で探す。 それぞれのトークンは、NULL 終端された 1文字以上の文字列で、
  70 他のトークンと区別できる必要がある。 また、等号とカンマを含んではならない。
  71
  72 \fBgetsubopt\fP()  は呼び出されるたびに、 \fIoptionp\fP 中の次の未処理のサブオプションの情報を返す。
  73 サブオプション内に等号があった場合、最初の等号は そのサブオプションの名前と値の区切りと解釈される。 区切りから次のカンマ
  74 (最後のサブオプションの場合、文字列の末尾)  までが、サブオプションの値となる。 サブオプションの名前が \fItokens\fP
  75 内の名前と一致し、値を表す文字列が見つかった場合、 \fBgetsubopt\fP()  は \fI*valuep\fP を値を表す文字列のアドレスに設定する。
  76 \fIoptionp\fP 中の最初のカンマはヌルバイトで上書きされる。そのため、 \fI*valuep\fP はそのサブオプションの「値の文字列」そのものとなる。
  77
  78 サブオプションが認識されたが、値を表す文字列が見つからなかった場合、 *\fIvaluep\fP は NULL に設定される。
  79
  80 \fBgetsubopt\fP()  が返る時、 \fIoptionp\fP は次のサブオプションを指している。 ちょうど最後のサブオプションが処理された場合は、
  81 文字列末尾のヌルバイト (\(aq\e0\(aq) を指している。
  82 .SH 返り値
  83 \fIoptionp\fP 内でサブオプションが見つかった場合、 \fBgetsubopt\fP()  は最初のサブオプションにマッチする \fItokens\fP
  84 の要素の添字を返す。 見つからなかった場合、\-1 を返す。この場合、 \fI*valuep\fP は \fIname\fP\fB[=\fP\fIvalue\fP\fB]\fP
  85 の文字列全体となる。
  86
  87 \fI*optionp\fP は変更されるので、 \fBgetsubopt\fP()  を呼び出す前の最初のサブオプションは \fBgetsubopt\fP()
  88 を呼び出し後のサブオプションと必ずしも同じとは限らない。
  89 .SH 属性
  90 .SS "マルチスレッディング (pthreads(7) 参照)"
  91 関数 \fBgetsubopt\fP() はスレッドセーフである。
  92 .SH 準拠
  93 POSIX.1\-2001.
  94 .SH 注意
  95
  96 \fBgetsubopt\fP()  は、文字列 *\fIoptionp\fP 中に見つけたカンマを上書きするので、文字列 \fI*optionp\fP
  97 は書き込み可能でなければならず、 文字列定数にすることはできない。
  98 .SH 例
  99 以下のプログラムは "\-o" オプションに続いてサブオプションがあることを 期待している。
 100
 101 .nf
 102 #define _XOPEN_SOURCE 500
 103 #include <stdlib.h>
 104 #include <assert.h>
 105 #include <stdio.h>
 106
 107 int
 108 main(int argc, char **argv)
 109 {
 110     enum {
 111         RO_OPT = 0,
 112         RW_OPT,
 113         NAME_OPT
 114     };
 115     char *const token[] = {
 116         [RO_OPT]   = "ro",
 117         [RW_OPT]   = "rw",
 118         [NAME_OPT] = "name",
 119         NULL
 120     };
 121     char *subopts;
 122     char *value;
 123     int opt;
 124
 125     int readonly = 0;
 126     int readwrite = 0;
 127     char *name = NULL;
 128     int errfnd = 0;
 129
 130     while ((opt = getopt(argc, argv, "o:")) != \-1) {
 131         switch (opt) {
 132         case \(aqo\(aq:
 133             subopts = optarg;
 134             while (*subopts != \(aq\e0\(aq && !errfnd) {
 135
 136             switch (getsubopt(&subopts, token, &value)) {
 137             case RO_OPT:
 138                 readonly = 1;
 139                 break;
 140
 141             case RW_OPT:
 142                 readwrite = 1;
 143                 break;
 144
 145             case NAME_OPT:
 146                 if (value == NULL) {
 147                     fprintf(stderr, "Missing value for "
 148                             "suboption \(aq%s\(aq\en", token[NAME_OPT]);
 149                     errfnd = 1;
 150                     continue;
 151                 }
 152
 153                 name = value;
 154                 break;
 155
 156             default:
 157                 fprintf(stderr, "No match found "
 158                         "for token: /%s/\en", value);
 159                 errfnd = 1;
 160                 break;
 161             }
 162         }
 163         if (readwrite && readonly) {
 164             fprintf(stderr, "Only one of \(aq%s\(aq and \(aq%s\(aq can be "
 165                     "specified\en", token[RO_OPT], token[RW_OPT]);
 166             errfnd = 1;
 167         }
 168         break;
 169
 170         default:
 171             errfnd = 1;
 172         }
 173     }
 174
 175     if (errfnd || argc == 1) {
 176         fprintf(stderr, "\enUsage: %s \-o <suboptstring>\en", argv[0]);
 177         fprintf(stderr, "suboptions are \(aqro\(aq, \(aqrw\(aq, "
 178                 "and \(aqname=<value>\(aq\en");
 179         exit(EXIT_FAILURE);
 180     }
 181
 182     /* Remainder of program... */
 183
 184     exit(EXIT_SUCCESS);
 185 }
 186 .fi
 187 .SH 関連項目
 188 \fBgetopt\fP(3)
 189 .SH この文書について
 190 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.65 の一部
 191 である。プロジェクトの説明とバグ報告に関する情報は
 192 http://www.kernel.org/doc/man\-pages/ に書かれている。