manual/LDP_man-pages/draft/man3/getopt.3

   1 .\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de)
   2 .\" and Copyright 2006-2008, Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\"
   4 .\" %%%LICENSE_START(VERBATIM)
   5 .\" Permission is granted to make and distribute verbatim copies of this
   6 .\" manual provided the copyright notice and this permission notice are
   7 .\" preserved on all copies.
   8 .\"
   9 .\" Permission is granted to copy and distribute modified versions of this
  10 .\" manual under the conditions for verbatim copying, provided that the
  11 .\" entire resulting derived work is distributed under the terms of a
  12 .\" permission notice identical to this one.
  13 .\"
  14 .\" Since the Linux kernel and libraries are constantly changing, this
  15 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  16 .\" responsibility for errors or omissions, or for damages resulting from
  17 .\" the use of the information contained herein.  The author(s) may not
  18 .\" have taken the same level of care in the production of this manual,
  19 .\" which is licensed free of charge, as they might when working
  20 .\" professionally.
  21 .\"
  22 .\" Formatted or processed versions of this manual, if unaccompanied by
  23 .\" the source, must acknowledge the copyright and authors of this work.
  24 .\" %%%LICENSE_END
  25 .\"
  26 .\" Modified Sat Jul 24 19:27:50 1993 by Rik Faith (faith@cs.unc.edu)
  27 .\" Modified Mon Aug 30 22:02:34 1995 by Jim Van Zandt <jrv@vanzandt.mv.com>
  28 .\"  longindex is a pointer, has_arg can take 3 values, using consistent
  29 .\"  names for optstring and longindex, "\n" in formats fixed.  Documenting
  30 .\"  opterr and getopt_long_only.  Clarified explanations (borrowing heavily
  31 .\"  from the source code).
  32 .\" Modified 8 May 1998 by Joseph S. Myers (jsm28@cam.ac.uk)
  33 .\" Modified 990715, aeb: changed `EOF' into `-1' since that is what POSIX
  34 .\"  says; moreover, EOF is not defined in <unistd.h>.
  35 .\" Modified 2002-02-16, joey: added information about nonexistent
  36 .\"  option character and colon as first option character
  37 .\" Modified 2004-07-28, Michael Kerrisk <mtk.manpages@gmail.com>
  38 .\"     Added text to explain how to order both '[-+]' and ':' at
  39 .\"             the start of optstring
  40 .\" Modified 2006-12-15, mtk, Added getopt() example program.
  41 .\"
  42 .\"*******************************************************************
  43 .\"
  44 .\" This file was generated with po4a. Translate the source file.
  45 .\"
  46 .\"*******************************************************************
  47 .\"
  48 .\" Japanese Version Copyright (c) 1998 NAKANO Takeo all rights reserved.
  49 .\" Translated 1998-08-12, NAKANO Takeo <nakano@apm.seikei.ac.jp>
  50 .\" Updated & Modified 1999-08-21, NAKANO Takeo <nakano@apm.seikei.ac.jp>
  51 .\" Updated & Modified 2001-07-01, Yuichi SATO <ysato@h4.dion.ne.jp>
  52 .\" Updated & Modified 2002-03-23, Yuichi SATO
  53 .\" Updated & Modified 2003-09-07, Yuichi SATO <ysato444@yahoo.co.jp>
  54 .\" Updated & Modified 2005-01-10, Yuichi SATO
  55 .\" Updated & Modified 2005-10-28, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>
  56 .\" Updated & Modified 2006-01-18, Akihiro MOTOKI
  57 .\" Updated & Modified 2007-05-01, Akihiro MOTOKI, LDP v2.46
  58 .\" Updated 2008-08-11, Akihiro MOTOKI, LDP v3.05
  59 .\"
  60 .TH GETOPT 3 2020\-06\-09 GNU "Linux Programmer's Manual"
  61 .SH 名前
  62 getopt, getopt_long, getopt_long_only, optarg, optind, opterr, optopt \-
  63 コマンドラインオプションを解釈する
  64 .SH 書式
  65 .nf
  66 \fB#include <unistd.h>\fP
  67 .PP
  68 \fBint getopt(int \fP\fIargc\fP\fB, char * const \fP\fIargv[]\fP\fB,\fP
  69 \fB           const char *\fP\fIoptstring\fP\fB);\fP
  70 .PP
  71 \fBextern char *\fP\fIoptarg\fP\fB;\fP
  72 \fBextern int \fP\fIoptind\fP\fB, \fP\fIopterr\fP\fB, \fP\fIoptopt\fP\fB;\fP
  73 .PP
  74 \fB#include <getopt.h>\fP
  75 .PP
  76 \fBint getopt_long(int \fP\fIargc\fP\fB, char * const \fP\fIargv[]\fP\fB,\fP
  77 \fB           const char *\fP\fIoptstring\fP\fB,\fP
  78 \fB           const struct option *\fP\fIlongopts\fP\fB, int *\fP\fIlongindex\fP\fB);\fP
  79 .PP
  80 \fBint getopt_long_only(int \fP\fIargc\fP\fB, char * const \fP\fIargv[]\fP\fB,\fP
  81 \fB           const char *\fP\fIoptstring\fP\fB,\fP
  82 \fB           const struct option *\fP\fIlongopts\fP\fB, int *\fP\fIlongindex\fP\fB);\fP
  83 .fi
  84 .PP
  85 .RS -4
  86 glibc 向けの機能検査マクロの要件 (\fBfeature_test_macros\fP(7)  参照):
  87 .ad l
  88 .RE
  89 .PP
  90 \fBgetopt\fP(): _POSIX_C_SOURCE\ >=\ 2 || _XOPEN_SOURCE
  91 .br
  92 \fBgetopt_long\fP(), \fBgetopt_long_only\fP(): _GNU_SOURCE
  93 .ad b
  94 .SH 説明
  95 \fBgetopt\fP()  関数はコマンドライン引き数を解釈する。 \fBgetopt\fP()  がとる引き数 \fIargc\fP と \fIargv\fP
  96 は、それぞれプログラムの起動時に \fImain\fP()  関数に渡された引き数の個数と配列である。 \fIargv\fP の要素のうち \(aq\-\(aq
  97 で始まるもの (かつ "\-" 単独や "\-\-" 単独ではないもの) は オプション要素 (option element) とみなされる。
  98 この要素から先頭の \(aq\-\(aq を除いた文字は オプション文字 (option character) とされる。 \fBgetopt\fP()
  99 は、繰り返し呼び出されるごとに、次のオプション文字を返す。
 100 .PP
 101 変数 \fIoptind\fP は、 \fIargv\fP の次に処理される要素のインデックスである。 システムによりこの変数の値は 1 に初期化される。
 102 呼び出し側でこの値を 1 にリセットすることで、同じ \fIargv\fP のスキャンをやり直したり、新しい引き数ベクトルをスキャンすることができる。
 103 .PP
 104 新たなオプション文字を見つけると、 \fBgetopt\fP()  はその文字を返し、 外部変数 \fIoptind\fP とスタティックな変数
 105 \fInextchar\fP を更新する。 これらによって、 \fBgetopt\fP()  は次回の呼び出しの際に、 以降のオプション文字や \fIargv\fP
 106 要素のスキャンを継続できる。
 107 .PP
 108 オプション文字がそれ以上見つからなくなると、 \fBgetopt\fP()  は \-1 を返す。そして \fIoptind\fP は、\fIargv\fP の要素のうち、
 109 オプションでない最初の要素を示すようになる。
 110 .PP
 111 \fIoptstring\fP は受け付けるオプション文字からなる文字列である。 文字のあとにコロン (:) が置かれている場合は、
 112 オプションには引き数が必要であることを示す。 このとき \fBgetopt\fP()  は、現在注目している \fIargv\fP
 113 要素で、オプション文字に引き続くテキストへのポインターか、 あるいは次の \fIargv\fP 要素のテキストへのポインターを \fIoptarg\fP
 114 に代入する。 2 個連続してコロンが置かれている場合は、 そのオプションは引き数をとってもとらなくてもよい。 現在の \fIargv\fP
 115 要素にテキストがあれば (つまり、"\-oarg" のように、オプション名自身と同じワード内に テキストがある場合)、それが \fIoptarg\fP
 116 に返される。 なければ \fIoptarg\fP は 0 に設定される。 これは GNU による拡張である。 \fIoptstring\fP に \fBW\fP
 117 とそれに続くセミコロンが入っていると、 \fB\-W foo\fP は長いオプション \fB\-\-foo\fP と同じように扱われる (POSIX.2 は \fB\-W\fP
 118 オプションを実装依存の拡張として予約している)。 この動作は GNU による拡張であり、glibc 2 以前のライブラリでは 利用できない。
 119 .PP
 120 By default, \fBgetopt\fP()  permutes the contents of \fIargv\fP as it scans, so
 121 that eventually all the nonoptions are at the end.  Two other scanning modes
 122 are also implemented.  If the first character of \fIoptstring\fP is \(aq+\(aq
 123 or the environment variable \fBPOSIXLY_CORRECT\fP is set, then option
 124 processing stops as soon as a nonoption argument is encountered.  If the
 125 first character of \fIoptstring\fP is \(aq\-\(aq, then each nonoption
 126 \fIargv\fP\-element is handled as if it were the argument of an option with
 127 character code 1.  (This is used by programs that were written to expect
 128 options and other \fIargv\fP\-elements in any order and that care about the
 129 ordering of the two.)  The special argument "\-\-" forces an end of
 130 option\-scanning regardless of the scanning mode.
 131 .PP
 132 While processing the option list, \fBgetopt\fP()  can detect two kinds of
 133 errors: (1) an option character that was not specified in \fIoptstring\fP and
 134 (2) a missing option argument (i.e., an option at the end of the command
 135 line without an expected argument).  Such errors are handled and reported as
 136 follows:
 137 .IP * 3
 138 By default, \fBgetopt\fP()  prints an error message on standard error, places
 139 the erroneous option character in \fIoptopt\fP, and returns \(aq?\(aq as the
 140 function result.
 141 .IP *
 142 If the caller has set the global variable \fIopterr\fP to zero, then
 143 \fBgetopt\fP()  does not print an error message.  The caller can determine that
 144 there was an error by testing whether the function return value is
 145 \(aq?\(aq.  (By default, \fIopterr\fP has a nonzero value.)
 146 .IP *
 147 .\"
 148 If the first character (following any optional \(aq+\(aq or \(aq\-\(aq
 149 described above)  of \fIoptstring\fP is a colon (\(aq:\(aq), then \fBgetopt\fP()
 150 likewise does not print an error message.  In addition, it returns \(aq:\(aq
 151 instead of \(aq?\(aq to indicate a missing option argument.  This allows the
 152 caller to distinguish the two different types of errors.
 153 .SS "getopt_long() と getopt_long_only()"
 154 \fBgetopt_long\fP()  関数は、長いオプション (2 つのダッシュ "\-\-" で始まるオプション) を 受け入れることを除いて
 155 \fBgetopt\fP()  と同じように動作する (プログラムに長いオプションだけが渡された場合、 \fIoptstring\fP は NULL
 156 ではなく空文字列 ("") となる)。 長いオプションの名前は、他と重ならない範囲において短縮できる。
 157 あるいは定義されたオプションに正確にマッチするものでも (当然) かまわない。 長いオプションは引き数を取ることができ、 \fB\-\-arg=param\fP
 158 または \fB\-\-arg param\fP と言う形式で指定する。
 159 .PP
 160 \fIlongopts\fP は \fIstruct option\fP の要素からなる配列の、先頭要素へのポインターである。 \fIstruct option\fP は
 161 \fI<getopt.h>\fP で以下のように定義されている。
 162 .PP
 163 .in +4n
 164 .EX
 165 struct option {
 166     const char *name;
 167     int         has_arg;
 168     int        *flag;
 169     int         val;
 170 };
 171 .EE
 172 .in
 173 .PP
 174 それぞれのフィールドの意味は以下の通り。
 175 .TP
 176 \fIname\fP
 177 長いオプションの名前。
 178 .TP
 179 \fIhas_arg\fP
 180 \fBno_argument\fP (または 0) なら、オプションは引き数をとらない。 \fBrequired_argument\fP (または 1)
 181 なら、オプションは引き数を必要とする。 \fBoptional_argument\fP (または 2) なら、オプションは引き数をとっても とらなくても良い。
 182 .TP
 183 \fIflag\fP
 184 長いオプションに対する結果の返し方を指定する。\fIflag\fP が NULL なら \fBgetopt_long\fP()  は \fIval\fP を返す
 185 (例えば呼び出し元のプログラムは、 \fIval\fP に等価なオプション文字を代入することができる)。 NULL 以外の場合には、
 186 \fBgetopt_long\fP()  は 0 を返す。 このときオプションが見つかると \fIflag\fP がポイントする変数に \fIval\fP
 187 が代入される。見つからないとこの変数は変更されない。
 188 .TP
 189 \fIval\fP
 190 返り値、または \fIflag\fP がポイントする変数へロードされる値。
 191 .PP
 192 配列の最後の要素は、全て 0 で埋められていなければならない。
 193 .PP
 194 \fIlongindex\fP は、NULL でなければ、 長いオプションのインデックスを \fIlongopts\fP
 195 からの相対位置として保持している変数へのポインターとなる。
 196 .PP
 197 \fBgetopt_long_only\fP()  は \fBgetopt_long\fP()  と同様の動作をするが、 \(aq\-\(aq も "\-\-"
 198 と同様に、 長いオプションとして扱われる。\(aq\-\(aq で始まる ("\-\-" 以外の) オプションが、長いものにはマッチしないが短いものに
 199 マッチする場合においては、それは短いオプションとして解釈される。
 200 .SH 返り値
 201 オプションが正常に見つかれば \fBgetopt\fP()  はそのオプション文字を返す。 すべてのコマンドラインオプションの解析が終わったら、
 202 \fBgetopt\fP()  は \-1 を返す。 \fIoptstring\fP に含まれないオプション文字が見つかると、\(aq?\(aq を返す。
 203 引き数が足りないオプションが見つかった場合、 返り値は \fIoptstring\fP の最初の文字による異なる: 最初の文字が \(aq:\(aq であれば
 204 \(aq:\(aq を返し、 それ以外の場合は \(aq?\(aq を返す。
 205 .PP
 206 \fBgetopt_long\fP()  と \fBgetopt_long_only\fP()  も、 短いオプション文字を認識した場合にはその文字を返す。
 207 長いオプションに対しては、 \fIflag\fP が NULL なら \fIval\fP を返し、 \fIflag\fP が NULL 以外なら 0 を返す。 エラーと
 208 \-1 の返り値は \fBgetopt\fP()  と同じである。 さらに \(aq?\(aq
 209 は、マッチが確定できない場合や余分なパラメーターがある場合にも返る。
 210 .SH 環境
 211 .TP
 212 \fBPOSIXLY_CORRECT\fP
 213 これが設定されていると、非オプションの引き数に到達した時点でオプション に対する操作が停止される。
 214 .TP
 215 \fB_<PID>_GNU_nonoption_argv_flags_\fP
 216 この変数は \fBbash\fP(1)  2.0 が glibc と通信するために用いられた。 どの引き数がワイルドカードを展開した結果で、
 217 したがってオプションとみなすべきでないかを知らせるものである。 この機能は \fBbash\fP(1)  のバージョン 2.01 で削除されたが、glibc
 218 にはまだ残っている。
 219 .SH 属性
 220 この節で使用されている用語の説明については、 \fBattributes\fP(7) を参照。
 221 .TS
 222 allbox;
 223 lbw24 lb lb
 224 l l l.
 225 インターフェース        属性  値
 226 T{
 227 \fBgetopt\fP(),
 228 \fBgetopt_long\fP(),
 229 \fBgetopt_long_only\fP()
 230 T}      Thread safety   MT\-Unsafe race:getopt env
 231 .TE
 232 .SH 準拠
 233 .TP
 234 \fBgetopt\fP():
 235 POSIX.1\-2001, POSIX.1\-2008, and POSIX.2, provided the environment variable
 236 \fBPOSIXLY_CORRECT\fP is set.  Otherwise, the elements of \fIargv\fP aren't really
 237 \fIconst\fP, because these functions permute them.  Nevertheless, \fIconst\fP is
 238 used in the prototype to be compatible with other systems.
 239 .IP
 240 \fIoptstring\fP で \(aq+\(aq や \(aq\-\(aq を使うのは GNU による拡張である.
 241 .IP
 242 On some older implementations, \fBgetopt\fP()  was declared in
 243 \fI<stdio.h>\fP.  SUSv1 permitted the declaration to appear in either
 244 \fI<unistd.h>\fP or \fI<stdio.h>\fP.  POSIX.1\-1996 marked the use
 245 of \fI<stdio.h>\fP for this purpose as LEGACY.  POSIX.1\-2001 does not
 246 require the declaration to appear in \fI<stdio.h>\fP.
 247 .TP
 248 \fBgetopt_long\fP(), \fBgetopt_long_only\fP():
 249 これらの関数は GNU による拡張である。
 250 .SH 注意
 251 複数の引き数ベクトルをスキャンしたり、同じ引き数ベクトルを二回以上 スキャンするようなプログラムで、 \fIoptstring\fP の先頭で
 252 \(aq+\(aq や \(aq\-\(aq といった GNU による拡張機能を使用したり、 引き数ベクトルの切り替え時に
 253 \fBPOSIXLY_CORRECT\fP の値を変更したりする場合には、 \fIoptind\fP を伝統的な 1 ではなく 0 にリセットすることで
 254 \fBgetopt\fP()  を再初期化しなければならない (0 にリセットすることで、 \fBPOSIXLY_CORRECT\fP や \fIoptstring\fP
 255 の GNU 拡張機能のチェックを行う内部初期化ルーチンが起動される)。
 256 .SH 例
 257 .SS getopt()
 258 以下に示す簡単なサンプルプログラムでは、 二種類のプログラムオプションを扱うのに \fBgetopt\fP()  を使用している。一つは値を伴わない
 259 \fI\-n\fP で、もう一つは対応する値が必要な \fI\-t val\fP である。
 260 .PP
 261 .EX
 262 #include <unistd.h>
 263 #include <stdlib.h>
 264 #include <stdio.h>
 265
 266 int
 267 main(int argc, char *argv[])
 268 {
 269     int flags, opt;
 270     int nsecs, tfnd;
 271
 272     nsecs = 0;
 273     tfnd = 0;
 274     flags = 0;
 275     while ((opt = getopt(argc, argv, "nt:")) != \-1) {
 276         switch (opt) {
 277         case \(aqn\(aq:
 278             flags = 1;
 279             break;
 280         case \(aqt\(aq:
 281             nsecs = atoi(optarg);
 282             tfnd = 1;
 283             break;
 284         default: /* \(aq?\(aq */
 285             fprintf(stderr, "Usage: %s [\-t nsecs] [\-n] name\en",
 286                     argv[0]);
 287             exit(EXIT_FAILURE);
 288         }
 289     }
 290
 291     printf("flags=%d; tfnd=%d; nsecs=%d; optind=%d\en",
 292             flags, tfnd, nsecs, optind);
 293
 294     if (optind >= argc) {
 295         fprintf(stderr, "Expected argument after options\en");
 296         exit(EXIT_FAILURE);
 297     }
 298
 299     printf("name argument = %s\en", argv[optind]);
 300
 301     /* Other code omitted */
 302
 303     exit(EXIT_SUCCESS);
 304 }
 305 .EE
 306 .SS getopt_long()
 307 以下は、 \fBgetopt_long\fP()  の使用法を、ほぼすべての機能について示したプログラムの例である。
 308 .PP
 309 .EX
 310 #include <stdio.h>     /* for printf */
 311 #include <stdlib.h>    /* for exit */
 312 #include <getopt.h>
 313
 314 int
 315 main(int argc, char **argv) {
 316     int c;
 317     int digit_optind = 0;
 318
 319     while (1) {
 320         int this_option_optind = optind ? optind : 1;
 321         int option_index = 0;
 322         static struct option long_options[] = {
 323             {"add",     required_argument, 0,  0 },
 324             {"append",  no_argument,       0,  0 },
 325             {"delete",  required_argument, 0,  0 },
 326             {"verbose", no_argument,       0,  0 },
 327             {"create",  required_argument, 0, \(aqc\(aq},
 328             {"file",    required_argument, 0,  0 },
 329             {0,         0,                 0,  0 }
 330         };
 331
 332         c = getopt_long(argc, argv, "abc:d:012",
 333                  long_options, &option_index);
 334         if (c == \-1)
 335             break;
 336
 337         switch (c) {
 338         case 0:
 339             printf("option %s", long_options[option_index].name);
 340             if (optarg)
 341                 printf(" with arg %s", optarg);
 342             printf("\en");
 343             break;
 344
 345         case \(aq0\(aq:
 346         case \(aq1\(aq:
 347         case \(aq2\(aq:
 348             if (digit_optind != 0 && digit_optind != this_option_optind)
 349               printf("digits occur in two different argv\-elements.\en");
 350             digit_optind = this_option_optind;
 351             printf("option %c\en", c);
 352             break;
 353
 354         case \(aqa\(aq:
 355             printf("option a\en");
 356             break;
 357
 358         case \(aqb\(aq:
 359             printf("option b\en");
 360             break;
 361
 362         case \(aqc\(aq:
 363             printf("option c with value \(aq%s\(aq\en", optarg);
 364             break;
 365
 366         case \(aqd\(aq:
 367             printf("option d with value \(aq%s\(aq\en", optarg);
 368             break;
 369
 370         case \(aq?\(aq:
 371             break;
 372
 373         default:
 374             printf("?? getopt returned character code 0%o ??\en", c);
 375         }
 376     }
 377
 378     if (optind < argc) {
 379         printf("non\-option ARGV\-elements: ");
 380         while (optind < argc)
 381             printf("%s ", argv[optind++]);
 382         printf("\en");
 383     }
 384
 385     exit(EXIT_SUCCESS);
 386 }
 387 .EE
 388 .SH 関連項目
 389 \fBgetopt\fP(1), \fBgetsubopt\fP(3)
 390 .SH この文書について
 391 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 5.10 の一部である。プロジェクトの説明とバグ報告に関する情報は
 392 \%https://www.kernel.org/doc/man\-pages/ に書かれている。