Provided by: manpages-ja-dev_0.5.0.0.20210215+dfsg-1_all bug

名前

       getopt, getopt_long, getopt_long_only, optarg, optind, opterr, optopt - コマンドラインオプ
       ションを解釈する

書式

       #include <unistd.h>

       int getopt(int argc, char * const argv[],
                  const char *optstring);

       extern char *optarg;
       extern int optind, opterr, optopt;

       #include <getopt.h>

       int getopt_long(int argc, char * const argv[],
                  const char *optstring,
                  const struct option *longopts, int *longindex);

       int getopt_long_only(int argc, char * const argv[],
                  const char *optstring,
                  const struct option *longopts, int *longindex);

   glibc 向けの機能検査マクロの要件 (feature_test_macros(7)  参照):

       getopt(): _POSIX_C_SOURCE >= 2 || _XOPEN_SOURCE
       getopt_long(), getopt_long_only(): _GNU_SOURCE

説明

       getopt()   関数はコマンドライン引き数を解釈する。  getopt()   がとる引き数  argcargv
       は、それぞれプログラムの起動時に  main()  関数に渡された引き数の個数と配列である。 argv の
       要素のうち '-' で始まるもの (かつ "-"  単独や  "--"  単独ではないもの)  は  オプション要素
       (option  element)  とみなされる。  この要素から先頭の  '-'  を除いた文字は  オプション文字
       (option character) とされる。 getopt()  は、繰り返し呼び出されるごとに、次のオプション文字
       を返す。

       変数  optind は、 argv の次に処理される要素のインデックスである。 システムによりこの変数の
       値は 1 に初期化される。 呼び出し側でこの値を 1 にリセットすることで、同じ argv  のスキャン
       をやり直したり、新しい引き数ベクトルをスキャンすることができる。

       新たなオプション文字を見つけると、  getopt()   はその文字を返し、  外部変数  optind とスタ
       ティックな変数 nextchar を更新する。 これらによって、  getopt()   は次回の呼び出しの際に、
       以降のオプション文字や argv 要素のスキャンを継続できる。

       オプション文字がそれ以上見つからなくなると、   getopt()    は   -1  を返す。そして  optind
       は、argv の要素のうち、 オプションでない最初の要素を示すようになる。

       optstring は受け付けるオプション文字からなる文字列である。 文字のあとにコロン (:) が置かれ
       ている場合は、  オプションには引き数が必要であることを示す。 このとき getopt()  は、現在注
       目している  argv  要素で、オプション文字に引き続くテキストへのポインターか、  あるいは次の
       argv 要素のテキストへのポインターを optarg に代入する。 2 個連続してコロンが置かれている場
       合は、 そのオプションは引き数をとってもとらなくてもよい。 現在の argv 要素にテキストがあれ
       ば (つまり、"-oarg" のように、オプション名自身と同じワード内に テキストがある場合)、それが
       optarg に返される。 なければ optarg は  0  に設定される。  これは  GNU  による拡張である。
       optstringW とそれに続くセミコロンが入っていると、 -W foo は長いオプション --foo と同じ
       ように扱われる (POSIX.2 は -W  オプションを実装依存の拡張として予約している)。  この動作は
       GNU による拡張であり、glibc 2 以前のライブラリでは 利用できない。

       デフォルトでは getopt()  は argv をスキャンする際に順序を変更し、 オプション以外の要素を最
       後に移動する。 他にも 2 つのモードが実装されている。  optstring  の先頭文字が  '+'  である
       か、環境変数 POSIXLY_CORRECT が設定されている場合には、オプションを対象とする動作は、 非オ
       プションの引き数が現れた段階で終了する。 optstring の先頭文字が '-' である場合には、  オプ
       ションでない argv 要素は、 文字コード 1 のオプションであるかのように扱われる (これを用いる
       プログラムは、 オプションや argv 要素を任意の順序で受け入れ、かつそれらの順序が 意味を持つ
       ように書かれている必要がある)。 "--" は特殊な引き数で、スキャンのモードによらず、 オプショ
       ンのスキャンを強制的に終了させる。

       認識できないオプション文字があると、 getopt()   はエラーメッセージを標準エラー出力  stderr
       に表示し、 その文字を optopt に保存して '?' を返す。 呼び出したプログラムで opterr を 0 に
       しておけば、 エラーメッセージの表示を抑制できる。

       getopt()  は argv の中に optstring にないオプション文字を見つけた場合、 またはオプション引
       き数が足りないことが分かった場合、  '?' を返して外部変数 optopt をそのオプション文字に設定
       する。 optstring の (上で説明したオプションで指定できる '+' または '-' 後に続く)  最初の文
       字が  コロン  (':') のとき、 getopt()  はオプション引き数が足りない場合に '?' ではなく ':'
       を返す。 エラーを見つけた場合で、かつ optstring の最初の文字がコロンでなく、  かつ外部変数
       opterr が 0 でない場合 (これがデフォルト)、 getopt()  はエラーメッセージを表示する。

   getopt_long()  getopt_long_only()
       getopt_long()  関数は、長いオプション (2 つのダッシュ "--" で始まるオプション) を 受け入れ
       ることを除いて getopt()  と同じように動作する  (プログラムに長いオプションだけが渡された場
       合、  optstring は NULL ではなく空文字列 ("") となる)。 長いオプションの名前は、他と重なら
       ない範囲において短縮できる。 あるいは定義されたオプションに正確にマッチするものでも (当然)
       かまわない。  長いオプションは引き数を取ることができ、 --arg=param または --arg param と言
       う形式で指定する。

       longoptsstruct  option  の要素からなる配列の、先頭要素へのポインターである。  struct
       option<getopt.h> で以下のように定義されている。

           struct option {
               const char *name;
               int         has_arg;
               int        *flag;
               int         val;
           };

       それぞれのフィールドの意味は以下の通り。

       name   長いオプションの名前。

       has_arg
              no_argument (または 0) なら、オプションは引き数をとらない。 required_argument (また
              は 1) なら、オプションは引き数を必要とする。 optional_argument (または 2)  なら、オ
              プションは引き数をとっても とらなくても良い。

       flag   長いオプションに対する結果の返し方を指定する。flag  が  NULL なら getopt_long()  は
              val を返す (例えば呼び出し元のプログラムは、 val に等価なオプション文字を代入するこ
              とができる)。 NULL 以外の場合には、 getopt_long()  は 0 を返す。 このときオプション
              が見つかると flag がポイントする変数に val が代入される。見つからないとこの変数は変
              更されない。

       val    返り値、または flag がポイントする変数へロードされる値。

       配列の最後の要素は、全て 0 で埋められていなければならない。

       longindex は、NULL でなければ、 長いオプションのインデックスを longopts からの相対位置とし
       て保持している変数へのポインターとなる。

       getopt_long_only()  は getopt_long()  と同様の動作をするが、 '-' も "--" と同様に、 長いオ
       プションとして扱われる。'-'  で始まる ("--" 以外の) オプションが、長いものにはマッチしない
       が短いものに マッチする場合においては、それは短いオプションとして解釈される。

返り値

       オプションが正常に見つかれば getopt()  はそのオプション文字を返す。 すべてのコマンドライン
       オプションの解析が終わったら、 getopt()  は -1 を返す。 optstring に含まれないオプション文
       字が見つかると、'?'   を返す。    引き数が足りないオプションが見つかった場合、    返り値は
       optstring  の最初の文字による異なる: 最初の文字が ':' であれば ':' を返し、 それ以外の場合
       は '?' を返す。

       getopt_long()  と getopt_long_only()  も、  短いオプション文字を認識した場合にはその文字を
       返す。  長いオプションに対しては、  flag が NULL なら val を返し、 flag が NULL 以外なら 0
       を返す。 エラーと -1 の返り値は getopt()  と同じである。 さらに '?' は、マッチが確定できな
       い場合や余分なパラメーターがある場合にも返る。

環境

       POSIXLY_CORRECT
              これが設定されていると、非オプションの引き数に到達した時点でオプション に対する操作
              が停止される。

       _<PID>_GNU_nonoption_argv_flags_
              この変数は bash(1)  2.0 が glibc と通信するために用いられた。  どの引き数がワイルド
              カードを展開した結果で、 したがってオプションとみなすべきでないかを知らせるものであ
              る。 この機能は bash(1)  のバージョン 2.01  で削除されたが、glibc  にはまだ残ってい
              る。

準拠

       getopt():
              環境変数  POSIXLY_CORRECT  が設定されている場合は  POSIX.2 と POSIX.1-2001 に準拠す
              る。 他の場合は argv の要素は本当の意味での定数にはならない。  なぜなら順序が変更さ
              れてしまうからである。   ただしそれらは、プロトタイプでは定数であるかのようにしてあ
              る。 これは他のシステムとの互換性のためである。

              optstring で '+' や '-' を使うのは GNU による拡張である.

              古い実装のいくつかでは、 getopt()  は  <stdio.h>  で宣言されていた。  SUSv1  では、
              <unistd.h><stdio.h>  のどちらかで  宣言してもよかった。  POSIX.1-2001  では、
              getopt の宣言を <stdio.h> で行うのは「過去の名残」であるとされた。 POSIX.1-2001  で
              は <stdio.h> で宣言を行うことを認めていない。

       getopt_long(), getopt_long_only():
              これらの関数は GNU による拡張である。

注意

       複数の引き数ベクトルをスキャンしたり、同じ引き数ベクトルを二回以上  スキャンするようなプロ
       グラムで、 optstring の先頭で '+' や '-' といった GNU による拡張機能を使用したり、  引き数
       ベクトルの切り替え時に  POSIXLY_CORRECT の値を変更したりする場合には、 optind を伝統的な 1
       ではなく 0 にリセットすることで getopt()  を再初期化しなければならない (0 にリセットするこ
       とで、  POSIXLY_CORRECToptstring の GNU 拡張機能のチェックを行う内部初期化ルーチンが起
       動される)。

バグ

       POSIX.2   における    getopt()     の仕様には技術的な問題があり、    その内容は    POSIX.2
       Interpretation 150 に記されている。 GNU による実装では (おそらく他のすべての実装でも)、 仕
       様と異なる正しい動作をするように実装されている。

   getopt()
       以下に示す簡単なサンプルプログラムでは、  二種類のプログラムオプションを扱うのに  getopt()
       を使用している。一つは値を伴わない -n で、もう一つは対応する値が必要な -t val である。

       #include <unistd.h>
       #include <stdlib.h>
       #include <stdio.h>

       int
       main(int argc, char *argv[])
       {
           int flags, opt;
           int nsecs, tfnd;

           nsecs = 0;
           tfnd = 0;
           flags = 0;
           while ((opt = getopt(argc, argv, "nt:")) != -1) {
               switch (opt) {
               case 'n':
                   flags = 1;
                   break;
               case 't':
                   nsecs = atoi(optarg);
                   tfnd = 1;
                   break;
               default: /* '?' */
                   fprintf(stderr, "Usage: %s [-t nsecs] [-n] name\n",
                           argv[0]);
                   exit(EXIT_FAILURE);
               }
           }

           printf("flags=%d; tfnd=%d; nsecs=%d; optind=%d\n",
                   flags, tfnd, nsecs, optind);

           if (optind >= argc) {
               fprintf(stderr, "Expected argument after options\n");
               exit(EXIT_FAILURE);
           }

           printf("name argument = %s\n", argv[optind]);

           /* Other code omitted */

           exit(EXIT_SUCCESS);
       }

   getopt_long()
       以下は、 getopt_long()  の使用法を、ほぼすべての機能について示したプログラムの例である。

       #include <stdio.h>     /* for printf */
       #include <stdlib.h>    /* for exit */
       #include <getopt.h>

       int
       main(int argc, char **argv) {
           int c;
           int digit_optind = 0;

           while (1) {
               int this_option_optind = optind ? optind : 1;
               int option_index = 0;
               static struct option long_options[] = {
                   {"add",     required_argument, 0,  0 },
                   {"append",  no_argument,       0,  0 },
                   {"delete",  required_argument, 0,  0 },
                   {"verbose", no_argument,       0,  0 },
                   {"create",  required_argument, 0, 'c'},
                   {"file",    required_argument, 0,  0 },
                   {0,         0,                 0,  0 }
               };

               c = getopt_long(argc, argv, "abc:d:012",
                        long_options, &option_index);
               if (c == -1)
                   break;

               switch (c) {
               case 0:
                   printf("option %s", long_options[option_index].name);
                   if (optarg)
                       printf(" with arg %s", optarg);
                   printf("\n");
                   break;

               case '0':
               case '1':
               case '2':
                   if (digit_optind != 0 && digit_optind != this_option_optind)
                     printf("digits occur in two different argv-elements.\n");
                   digit_optind = this_option_optind;
                   printf("option %c\n", c);
                   break;

               case 'a':
                   printf("option a\n");
                   break;

               case 'b':
                   printf("option b\n");
                   break;

               case 'c':
                   printf("option c with value '%s'\n", optarg);
                   break;

               case 'd':
                   printf("option d with value '%s'\n", optarg);
                   break;

               case '?':
                   break;

               default:
                   printf("?? getopt returned character code 0%o ??\n", c);
               }
           }

           if (optind < argc) {
               printf("non-option ARGV-elements: ");
               while (optind < argc)
                   printf("%s ", argv[optind++]);
               printf("\n");
           }

           exit(EXIT_SUCCESS);
       }

関連項目

       getopt(1), getsubopt(3)

この文書について

       この  man ページは Linux man-pages プロジェクトのリリース 3.79 の一部 である。プロジェクト
       の説明とバグ報告に関する情報は http://www.kernel.org/doc/man-pages/ に書かれている。