getopts - ユーティリティーオプションの解析
/usr/bin/getopts optstring name [arg...]
getopts optstring name [argument]...
getopts optstring name [arg]...
getopts [–a name] optstring name [arg]...
getopts ユーティリティを使えば、引数リストからオプションやオプション引数を検索できます。
getopts は、呼び出されるたびに、name オペランドで指定されているシェル変数に次のオプションを入れ、シェル変数 OPTIND に処理すべき次の引数へのインデックスを入れます。シェルが呼び出されるたびに、OPTIND は 1 に初期設定されます。
オプション引数を必要とするオプションの場合、getopts はオプション引数をシェル変数 OPTARG に入れます。オプションがない場合または見つかったオプションにオプション引数がない場合、OPTARG は設定されません。
オプション文字の位置に、optstring オペランドに含まれていないオプション文字があると、name で指定されているシェル変数が疑問符 (?) 文字に設定されます。この場合、optstring の最初の文字がコロン (:) なら、シェル変数 OPTARG は見つかったオプション文字に設定されますが、標準エラー出力には何も出力されません。それ以外の場合、シェル変数 OPTARG は設定されず、標準エラー出力には診断メッセージが出力されます。この状況は、呼び出しアプリケーションに引数を渡す方法においてエラーがあったと判断され、getopts 処理のエラーとはなりません。
オプション引数がない場合は、以下のように処理されます。
optstring の最初の文字がコロン (:) なら、name で指定されているシェル変数はコロン文字に設定され、シェル変数 OPTARG は見つかったオプション文字に設定されます。
それ以外の場合、name で指定されているシェル変数は疑問符 (?) 文字に設定され、シェル変数 OPTARG は設定されず、標準エラー出力には診断メッセージが出力されます。この状況は、呼び出しアプリケーションに引数を渡す方法においてエラーがあったと判断され、getopts 処理のエラーとはなりません。この判断を示した診断メッセージが出力されますが、終了ステータスは 0 になります。
オプションの最後にくると、getopts はゼロより大きい戻り値で終了します。シェル変数 OPTIND は最初に現われた非オプション引数のインデックスに設定されます。このとき、最初に現われた - - 引数は、他の非オプション引数が先に現われない場合にオプションとしてみなされます。非オプション引数が 1 つもない場合は、$# + 1 に設定され、name 変数は疑問符 (?) 文字になります。オプションの終わりを判断するのは、 特殊オプション - - がある場合、- 以外で始まる引数が見つかった場合、またはエラーが発生した場合です。
シェル変数 OPTIND と OPTARG は getopts の呼び出し元のローカル変数であり、デフォルトではエクスポートされません。
name オペランドで指定されているシェル変数、OPTIND、および OPTARG は、現在のシェル実行環境に影響を及ぼします。
アプリケーションが OPTIND を 1 に設定すると、新しいパラメータセットが使用できるようになります。 現在の位置パラメータまたは新しい arg 値です。すべての呼び出しで同じパラメータ (位置パラメータまたは arg オペランド) を使おうとしない場合、または OPTIND を1 以外の値に変更した場合、1 つのシェル実行環境で getopts を複数回呼び出すと、結果は不確定です。
getopts は、Bourne シェル組み込みコマンドの1 つであり、定位置パラメータの解析およびオプションの妥当性チェックに使用されます。sh(1) を参照してください。このコマンドは、コマンド構文標準規格 (Intro(1) のルール 3 - 10 を参照) のうち、該当するルールすべてをサポートします。このコマンドは、getopt コマンドの代わりに使用してください。
optstring には、getopts を使用するコマンドが認識できるオプション文字を入れなければなりません。オプション文字の後にコロンが付いている場合は、そのオプションには 1 つまたは複数の引数があるとみなされます。オプションと引数の間は、スペースによって区切られていなければなりません。
getopts は、呼び出されるたびに、次のオプションをシェル変数 name に入れ、処理すべき次の引数へのインデックスをシェル変数 OPTIND に入れます。シェルまたはシェル手続きが呼び出されるたびに、OPTIND の値は 1 に初期設定されます。
オプションにオプション引数が必要な場合、getopts はその引数をシェル変数 OPTARG に入れます。
不正なオプションが検出されると、? が name に入ります。
オプションの終わりが検出されると、getopts はゼロ以外の終了ステータスで終了します。特殊オプション – を使用して、オプションの終わりを表すことができます。
デフォルトでは、getopts は定位置パラメータを解析します。getopts コマンド行に追加の引数 (argument . . .) が指定されると、getopts は定位置パラメータの代わりにその引数を解析します。
/usr/lib/getoptcvt は filename 内のシェルスクリプトを読み取り、getopt の代わりに getopts を使用できるようにそれを変換し、その結果を標準出力に出力します。
新しいコマンドはすべて、Intro(1) で説明しているコマンド構文標準規格に従うようにするために、定位置パラメータの解析、およびオプションがそのコマンドの有効なオプションであるかどうかのチェックに、getopts または getopt を使用しなければなりません。
getopts は、 optstring に含まれていないオプション文字を検出すると、 標準エラー出力にエラーメッセージを表示します。
現在の実装においては、次のようにコマンド構文規格 (Intro(1) を参照) に従わない使用方法が認められていますが、このような使用方法は、将来、システムのリリースではサポートされないので、使用しないでください。以下のセクションの例と同様に、–a および –b がオプションであり、–o はオプション引数を持つオプションとします。
次の例では、ルール 5 (オプション引数を持つオプションは別のオプションと一緒にまとめることはできない) に違反しています。
example% cmd -aboxxx filename
次の例では、ルール 6 (オプション引数を持つオプションの後には、スペースがなければならない) に違反しています。
example% cmd -ab oxxx filename
シェル変数 OPTIND の値を変更したり、異なる引数の集まりを解析したりした場合の結果は不確定です。
arg が正当なオプションを示しているかどうかをチェックします。arg を省略すると、定位置パラメータが使用されます。オプション引数は + または - で始まります。+ または - 以外の文字で始まっているオプション、また – 引数があると、オプションの終わりとみなされます。optstring には、getopts が認識する文字を記述します。文字のあとに : が続く場合、そのオプションには引数があるとみなされます。オプションと引数とはブランクで区切ることができます。
arg が + で始まる場合、getopts は + を起動するたびに name 内で見つかった次のオプション文字を設定します。次の arg のインデックスは OPTIND に格納されます。オプション引数がある場合は OPTARG に格納されます。
optstring 内で先頭に : がある場合、getopts は無効なオプション文字を OPTARG に格納し、name を ? (未定義のオプションが指定された場合) または : (必要なオプション引数が省略されている場合) に設定します。getopts はエラーメッセージを表示します。オプションがなくなると、終了ステータスは 0 以外になります。
getopts は、従来の単一文字の短いオプションも、Sun の Command Line Interface Paradigm (CLIP) で定義された長いオプションもサポートします。
長いオプションは短いオプションの別名です。長いオプションを指定するには、対応する短いオプションのあとに、長いオプションを括弧に囲んで指定します。たとえば、短いオプション「f」の別名として、長いオプション「file」を指定する場合、次のスクリプト行を使用します。
getopts "f(file)" opt
コマンド行上では、長いオプションの前に「--」または「++」を指定します。前述の例の場合、コマンド行上の「--file」は「-f」と同等であり、「++file」は「+f」と同等です。
短いオプションの別名として長いオプションを複数指定することはできますが、これは CLIP 仕様には違反することであり、使用するときには十分注意する必要があります。長いオプションを複数指定するときには、次のように、それぞれの長いオプションを括弧で囲む必要があります。
getopts "f:(file)(input-file)o:(output-file)"
前述の例の場合、「--file」と「--input-file」は両方とも「-f」と同等であり、「--output-file」は「-o」と同等です。
変数名は、常に、短いオプションに設定されます。コマンド行上で長いオプションを指定しても、変数名はそれと同等の短いオプションに設定されます。
シェルの getopts 組み込みコマンドに関する詳細は、このマニュアルページ内で前述した Bourne シェル (sh) の説明を参照してください。
getopts ユーティリティーを使えば、arg で指定された引数リストまたは定位置パラメータ (arg が省略されている場合) から、オプションや引数を検索できます。また、optstring の情報に基づいて、コマンドの使用法を示すメッセージやマニュアルページを生成することもできます。
getopts は、呼び出されるたびに、name オペランドで指定されているシェル変数に次のオプションを入れ、シェル変数 OPTIND に処理すべき次の引数へのインデックスを入れます。シェルが呼び出されると、OPTIND が 1 に初期化されます。オプションにオプション引数が必要であるか、許可される場合、getopts はそのオプション引数をシェル変数 OPTARG に入れます。それ以外の場合、OPTARG はオプションの設定時に 1 に、オプションの設定解除時に 0 にそれぞれ設定されます。
optstring 文字列は、英数字、特殊文字 (+、-、 ?、:)、スペース文字 (SPACE)、または [...] で囲まれた文字グループで構成されます。文字グループは、{...} 内に入れ子にできます。[...] グループの外にある 1 つの復帰改行文字 (NEWLINE) とそれに続く 0 個以上の空白文字は無視されます。オプションとコマンド引数の形式は、1 つ以上の空白行で区切られます。
各 [...] グループは、ラベル (省略可)、属性 (区切り文字は :、省略可)、および ? に続く説明文字列 (省略可) で構成されます。? から次の ] の末尾までの文字は、オプション解析および短い使用法メッセージとして無視されます。これらは、詳細なヘルプまたはマニュアルページの生成に使用されます。: 文字をラベルに表示することはできません。ラベルでは ? 文字を ?? と指定し、説明文字列では ] 文字を ]] と指定する必要があります。2 つの \b (バックスペース) 文字の間のテキストは、そのテキストがボールド (太文字) で表示されることを示しています。2 つの \a (ベル) 文字の間のテキストは、そのテキストが強調またはイタリックで表示されることを示しています。2 つの \v (垂直タブ) 文字の間のテキストは、そのテキストが固定幅フォントで表示されることを示しています。2 つの \f (フォームフィード) 文字の間のテキストは、囲まれたテキストを名前とするシェル関数からの出力で置き換えられます。
このインタフェースからの出力はすべて、標準エラー出力に書き込まれます。
グループの種類を次に示します。
次の形式のグループ
[-[version][flag[number]]...[?text]]
は最初のグループとして表示され、拡張インタフェースを使用可能にします。
version にはインタフェースのバージョン (現在は 1) を指定します。 バージョンが省略された場合は、最新バージョンと見なされます。将来の拡張により version の値は大きくなってゆきますが、すべてのバージョンがサポートされます。通常、 text には SCCS または CVS 識別文字列を指定します。数値 (省略可) を含むゼロ以上のフラグを指定して、オプション解析を制御できます。次のフラグがあります。
複数回受け渡しできるように、この optstring をキャッシュします。同じプロセス内で何度も呼び出し可能な組み込みコマンドを最適化する場合に使用します。
ヘルプの生成時にこの optstring を無視します。複数の受け渡しから得られる optstring 値を統合する場合に使用します。
ヘルプメッセージに長いオプション名だけを表示します。
オプション文字の接頭辞 - はオプションです。これは、廃止された ps(1) オプション構文に対応しています。
この数値は、長いオプション名の接頭辞として追加する必要のある - 文字の数を示します。デフォルト値は 2 です。指定可能な値は 0、1、2 です。たとえば、dd(1M) の場合は p0、find(1) の場合は p1 と指定します。
この数値は、マニュアルページのセクション番号を指定します。デフォルトは 1 です。
[ option[!][=number ][:longname][? text]] 形式のオプション。この場合、最初のフィールドはオプション文字です。これは、オプションが一致した場合に name オペランド内に返される値です。オプション文字が存在しない場合は、2 桁以上の数値を指定してください。長いオプションが一致する場合、この数値が name オペランドの値として返されます。オプションの後に ! が続く場合、オプション文字の意味は longname の意味の逆になります。値を取らないオプションの場合、OPTARG は、逆オプション文字 ! では 0 に、それ以外の場合は 1 に設定されます。オプションの =number は、オプション文字ではなく name オペランドに返される数を示します。longname は –longname で指定されます。これは、すべての長いオプションのうちで、あいまいさのない最短の接頭辞により照合されます。longname フィールド内の * は、追加の文字すべてが正確に一致するならば、その位置までの文字だけが一致する必要があることを示します。longname も説明テキストも存在しないオプションの場合、[ と ] は省略できます。
オプション引数の指定。引数を取るオプションの後に文字列値を表す : または数値を表す # を付けてから、オプション引数を指定できます。オプション引数の指定では、フィールド 1 にオプション引数名が含まれます。「:」で区切られた残りのフィールドは、タイプ名およびゼロ以上の特殊属性ワード (listof、oneof、および ignorecase) になります。最後のフィールドには、「:=default」のようにデフォルトのオプション値を指定できます。オプション引数の指定に続いて、中括弧で囲んだオプション値の説明のリストを記述できます。引数を取る長いオプションは、–longname= value のように指定します。: や # の後に ? が続く場合、そのオプション引数はオプションです。オプション文字の書式だけが指定されている場合は、次の引数が - または + で始まるのであれば、オプションの引数値は設定されません。
オプション値の説明。
引数の指定。オプション引数の指定に続いて、有効なオプション引数値のリストを {...} で囲んで指定できます。許可されるそれぞれの値は、[...] の中に値を含めて指定できます。その後に説明を記述できます。
[+\ n...] 形式のグループは、 ... の表す文字を固定幅フォントで表示します。改行は追加しません。
[+name ?text] 形式のグループでは、セクション名と説明テキストを指定します。name を省略すると、text は新しい段落に配置されます。
[-name ?text] 形式のグループでは、IMPLEMENTATION セクションのエントリを指定します。
optstring の先頭文字が + の場合、+ で始まる引数もオプションと見なされます。
先頭の : 文字、または optstring の先頭の + に続く : は、エラーの処理方法に影響を及ぼします。オプションの処理時にオプション文字または optstring で指定されていない longname 引数を検出すると、name という名前のシェル変数が ? 文字に設定されます。シェル変数 OPTARG は、検出された文字に設定されます。オプション引数が存在しないか、その値が無効な場合、name が : 文字に設定され、シェル変数 OPTARG が検出されたオプション文字に設定されます。先頭に : が存在しない場合、name は ? 文字に設定され、OPTARG の設定は解除されます。エラーが発生した場合には、エラーメッセージが標準エラー出力に書き込まれます。
次の場合は、オプションの終わりが発生します。
特別な引数 -- が検出されました。
先頭文字が - でない引数が検出されました。
ヘルプ引数が指定されています。
エラーが発生します。
OPTIND が値 1 に設定されている場合は、新しい引数セットを使用できます。
getopts も使用すると、コマンドの使用方法や詳細な説明を含むヘルプメッセージを生成できます。args は次のように指定します。
使用方法の概要を生成する場合に使用します。
詳細な使用方法メッセージを生成する場合に使用します。
書式付きのマニュアルページを生成する場合に使用します。
簡単に解析できる使用方法メッセージを生成する場合に使用します。
マニュアルページを html 形式で生成する場合に使用します。
マニュアルページを nroff 形式で生成する場合に使用します。
現在の optstring を一覧表示する場合に使用します。
version=n を一覧表示する場合に使用します。オプション name が getopts により認識される場合、n は 0 よりも大きくなります。
オプションの終わりが検出されると、getopts は 0 以外の戻り値で終了し、変数 OPTIND が最初の非オプション引数のインデックスに設定されます。
ksh では次のオプションがサポートされています。
使用方法メッセージ内で、コマンド名の代わりに name を使用します。
次のオペランドがサポートされています。
getopts を呼び出すユーティリティによって識別されるオプション文字が入った文字列。文字の後ろにコロンが付いている場合、そのオプションには引数があることを意味します。引数は別個に指定する必要があります。アプリケーションは、オプション文字とそのオプション引数を別々に指定しなければなりませんが、そのように指定されているかどうかに関わらず、getopts は、引数を取るオプションに続く文字をその引数と解釈します。オプション引数として NULL を渡すには getopts 起動時に明示的に引数とする必要があります。getopt(3C) を参照してください。アプリケーションでは、疑問符 (?) とコロン (:) をオプション文字としては使用できません。英数字以外のオプション文字を使用した場合の結果は不確定です。オプション引数とオプション文字とを別々に指定しないと、OPTARG の値からオプション文字と - が取り除かれます。オプション文字がわからないとき、またはオプション引数がないとき、optstring の最初の文字によって、getopts のふるまいが決まります。
getopts によって、見つかったオプション文字に設定されるシェル変数の名前。
デフォルトでは、getopts は、呼び出し側のシェルプロシージャに引き渡す位置パラメータの構文を解析します。arg が指定されていれば、位置パラメータの代わりに解析されます。
getopts は現在のシェル実行環境に影響を及ぼすので、通常、シェルに組み込まれています。以下のように、サブシェルや別のユーティリティ実行環境で呼び出された場合は、
(getopts abc value "$@")
nohup getopts ...
find . -exec getopts ... \;
この場合、getopts は呼び出し側の環境のシェル変数には影響しません。
なお、位置パラメータが変更されても、シェル関数は呼び出し側シェルと OPTIND を共有します。引数の構文を解析するために getopts を使用したい関数は、処理の最初で OPTIND の値を保存し、戻る前に復元するのが一般的です。ただし、呼び出し側シェル用に関数が OPTIND を変更する場合もあります。
以下に示すスクリプトは、引数を解析して表示する例です。
aflag=
bflag=
while getopts ab: name
do
case $name in
a) aflag=1;;
b) bflag=1
bval="$OPTARG";;
?) printf "Usage: %s: [-a] [-b value] args\n" $0
exit 2;;
esac
done
if [ ! -z "$aflag" ]; then
printf "Option -a specified\n"
fi
if [ ! -z "$bflag" ]; then
printf 'Option -b "%s" specified\n' "$bval"
fi
shift $(($OPTIND - 1))
printf "Remaining arguments are: %s\n" "$*"
使用例 2 オプション付きコマンド用の引数の処理
以下のシェルプログラムの一部は、コマンドに対する引数を処理する方法を示す例です。この例では、オプション引数を伴わない –a または –b と、オプション引数を伴う –o を使用します。
while getopts abo: c
do
case $c in
a | b) FLAG=$c;;
o) OARG=$OPTARG;;
\?) echo $USAGE
exit 2;;
esac
done
shift `expr $OPTIND − 1`
使用例 3 等価コード表現
以下のコードは、すべて同じ処理を実行します。
cmd -a -b -o "xxx z yy" filename cmd -a -b -o "xxx z yy" -- filename cmd -ab -o xxx,z,yy filename cmd -ab -o "xxx z yy" filename cmd -o xxx,z,yy -b -a filename
getopts の実行に影響を与える次の環境変数についての詳細は、environ(5) を参照してください。LANG、LC_ALL、LC_CTYPE、LC_MESSAGES、および NLSPATH。
この変数は、次に処理する引数へのインデックスとして getopts が使用します。
この変数は、オプションに引数が使用された場合、その引数を保存するために getopts が使用します。
次の終了ステータスが返されます。
optstring で指定した、または指定しなかったオプションが見つかりました。
オプションの並びの終わりを検出した、またはエラーが発生しました。
ksh により、次の終了値が返されます。
指定されたオプションが見つかりました。
オプションの並びの終わりを検出しました。
使用方法または情報のメッセージが生成されました。
属性についての詳細は、マニュアルページの attributes(5) を参照してください。
|
|
Intro(1), getoptcvt(1), ksh(1), ksh88(1), ps(1), sh(1), getopt(3C), attributes(5), environ(5), standards(5)
エラーが検出されたとき、optstring オペランドの最初の文字がコロン (:) 以外なら、以下の情報が入った診断メッセージが不特定なフォーマットで標準エラー出力に出力されます。
呼び出し側のプログラム名がメッセージ内に示されます。呼び出し側のプログラム名は、getopts が呼び出された時点で、シェル特殊パラメータ 0 の値を持ちます。次と等価の名前
basename "$0"
が使用できます。
optstring にないオプションが見つかった場合、エラーと認識されて、無効なオプション文字がメッセージ内に示されます。
オプション引数を必要とするオプションが見つかったが、オプション引数がない場合、エラーと認識されて、無効なオプション文字がメッセージ内に示されます。