Manpages

名 前

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/ に 書 か れ て い る 。