Man page - getopt(3)

Packages contains this manual

Available languages:

en fr ja de

Manual

GETOPT

名 前
書 式
説 明
getopt_long() と getopt_long_only()
返 り 値
環 境
属 性
準 拠
注 意
例
getopt()
getopt_long()
関 連 項 目
こ の 文 書 に つ い て

名 前

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 () が と る 引 数 argc と argv は 、 そ れ ぞ れ プ ロ グ ラ ム の 起 動 時 に 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 に よ る 拡 張 で あ る 。 optstring に W と そ れ に 続 く セ ミ コ ロ ン が 入 っ て い る と 、 -W foo は 長 い オ プ シ ョ ン --foo と 同 じ よ う に 扱 わ れ る (POSIX.2 は -W オ プ シ ョ ン を 実 装 依 存 の 拡 張 と し て 予 約 し て い る )。 こ の 動 作 は GNU に よ る 拡 張 で あ り 、 glibc 2 以 前 の ラ イ ブ ラ リ で は 利 用 で き な い 。

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

While processing the option list, getopt () can detect two kinds of errors: (1) an option character that was not specified in optstring and (2) a missing option argument (i.e., an option at the end of the command line without an expected argument). Such errors are handled and reported as follows:

*

By default, getopt () prints an error message on standard error, places the erroneous option character in optopt , and returns '?' as the function result.

*

If the caller has set the global variable opterr to zero, then getopt () does not print an error message. The caller can determine that there was an error by testing whether the function return value is '?'. (By default, opterr has a nonzero value.)

*

If the first character (following any optional '+' or '-' described above) of optstring is a colon (':'), then getopt () likewise does not print an error message. In addition, it returns ':' instead of '?' to indicate a missing option argument. This allows the caller to distinguish the two different types of errors.

getopt_long() と getopt_long_only()

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

longopts は struct 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 に は ま だ 残 っ て い る 。

属 性

こ の 節 で 使 用 さ れ て い る 用 語 の 説 明 に つ い て は 、 attributes (7) を 参 照 。

Image grohtml-45216-1.png

準 拠

getopt ():

POSIX.1-2001, POSIX.1-2008, and POSIX.2, provided the environment variable POSIXLY_CORRECT is set. Otherwise, the elements of argv aren’t really const , because these functions permute them. Nevertheless, const is used in the prototype to be compatible with other systems.

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

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

getopt_long (), getopt_long_only ():

こ れ ら の 関 数 は GNU に よ る 拡 張 で あ る 。

注 意

複 数 の 引 数 ベ ク ト ル を ス キ ャ ン し た り 、 同 じ 引 数 ベ ク ト ル を 二 回 以 上 ス キ ャ ン す る よ う な プ ロ グ ラ ム で 、 optstring の 先 頭 で '+' や '-' と い っ た GNU に よ る 拡 張 機 能 を 使 用 し た り 、 引 数 ベ ク ト ル の 切 り 替 え 時 に POSIXLY_CORRECT の 値 を 変 更 し た り す る 場 合 に は 、 optind を 伝 統 的 な 1 で は な く 0 に リ セ ッ ト す る こ と で getopt () を 再 初 期 化 し な け れ ば な ら な い (0 に リ セ ッ ト す る こ と で 、 POSIXLY_CORRECT や optstring の 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 プ ロ ジ ェ ク ト の リ リ ー ス 5.10 の 一 部 で あ る 。 プ ロ ジ ェ ク ト の 説 明 と バ グ 報 告 に 関 す る 情 報 は https://www.kernel.org/doc/man-pages/ に 書 か れ て い る 。