.\"
.\" Japanese Version Copyright (c) 2001-2003 Yuichi SATO
.\"         all rights reserved.
.\" Translated Tue 11 Jan 1994
.\"         by NetBSD jman proj. <jman@spa.is.uec.ac.jp>
.\" Updated Sun Jan 14 04:46:37 JST 2001
.\"         by Yuichi SATO <sato@complex.eng.hokudai.ac.jp>
.\" Updated & Modified Sun Mar  2 15:11:49 JST 2003
.\"         by Yuichi SATO <ysato444@yahoo.co.jp>
.\"
.\"WORD:	parse		解析する
.\"WORD:	interpret	解釈する
.\"
.TH GETOPT 1 "May 31, 1997" Linux ""
.SH 名前
getopt \- コマンドの引き数を解析する (拡張版)
.SH 書式
.BR getopt " optstring parameters"

.BR getopt " [options] [" \-\- "] optstring parameters"

.BR getopt " [options] " \-o | \-\-options " optstring [options] [" \-\- "] parameters"
.SH 説明
.B getopt
は、シェル手続きで簡単に解析できるように、
コマンドラインのオプションを分解
.RI ( 解析 )
するために使われる。
また、正しいオプションであるかを調べるためにも使われる。
これを行うために
.SM GNU
.BR getopt (3) 
ルーチンが使われる。

.B getopt
を呼び出すときに使われたパラメータは、
2 つの部分に分けることができる:
getopt の解析動作を変更するオプション
.RB ( 「書式」
セクションの
.I options
と
.IR "\-o|\-\-options optstring" )
と、解析されるパラメータ
.RB ( 「書式」
セクションの
.IR parameters )
である。
第 2 部分は、
最初のオプションではないパラメータ
(オプション引き数ではないもの) の後か、
最初の
.B ` \-\- '
の後から始まる。
第 1 部分に
.RB ` \-o ' 
または
.RB ` \-\-options '
オプションが見つからない場合、
第 2 部分の最初のパラメータは
短い形式のオプション文字列として使われる。

環境変数
.B GETOPT_COMPATIBLE
が設定された場合、
または最初のパラメータがオプションでなかった場合
.RB (` \- '
で始まっていない場合。
これは
.B 「書式」
セクションの最初の形式である)、
.B getopt
は他のバージョンの
.BR getopt (1)
と互換性のある出力を生成する。
この場合でも、パラメータの並べ替えを行い、オプション引き数を認識する
(詳細は
.B 「互換性」
セクションを参照すること)。

伝統的な
.BR getopt (1)
の実装では、引き数やオプションではないパラメータで
空白と他の (シェル特有の) 特殊文字を組み合わせて使うことができない。
この問題を解決するため、
この実装ではクォートした出力を生成する。
この出力は、シェル (通常は
.B eval
コマンドが使われる) によって再び解析されなければならない。
これにはクォートすべき文字列を保護するという効果があるが、
.B getopt
を他のバージョンとは互換性のない方法
.RB ( 「書式」
セクションの 2, 3 番目の形式) で呼び出さなければならない。
拡張版の
.BR getopt (1)
がインストールされているかどうかを調べるには、特別なテストオプション
.RB ( \-T ) 
を使うことができる。
.SH オプション
.IP "\-a, \-\-alternative"
長いオプションを 1 個の
.RB ` \- '
で始めることができるようにする。
.IP "\-h, \-\-help"
ちょっとした使用ガイドを表示し、正常終了する。
それ以上は何も出力されない。
.IP "\-l, \-\-longoptions longopts"
認識させる長い (複数文字の) オプションを指定する。
2 つ以上のオプション名をコンマで区切って一度に指定できる。
このオプションは 2 回以上指定することができる。
.I longopts 
は交換可能である。
.I longopts 
で指定されている長いオプション名の後に、1 個のコロンを続けることができる。
これは、そのオプションに引き数が必須であることを示す。
また、長いオプション名の後に 2 個のコロンを続けることもできる。
これは、そのオプションが引き数を取る場合もあることを示す。
.IP "\-n, \-\-name progname"
エラーが報告された場合に
.BR getopt (3)
ルーチンが使うプログラム名。
このオプションを指定しても、
.BR getopt (1)
のエラーは getopt から発生したものとして表示される点に注意すること。
.IP "\-o, \-\-options shortopts"
認識させる短い (1 文字の) オプションを指定する。
このオプションが指定されていない場合、
.B getopt 
の 1 個の
.RB ` \- ' 
で始まっていない最初のパラメータ (かつ、オプションの引き数でないもの) が
短いオプションの文字列として使われる。
.I shortopts 
に指定されている短いオプション文字の後に、1 個のコロンを続けることができる。
これは、そのオプションに引き数が必須であることを示す。
また、長いオプション名の後に 2 個のコロンを続けることもできる。
これは、そのオプションが引き数を取る場合もあることを示す。
オプションの解析法と出力の生成法を変更するために、
shortopts の最初の文字を
.RB ` + ' 
または
.RB ` \- ' 
にすることができる
(詳細は
.B 「スキャンモード」
セクションを参照すること)。
.IP "\-q, \-\-quiet"
getopt(3) によるエラー表示をさせない。
.IP "\-Q, \-\-quiet\-output"
通常の出力を生成させない。
.IR \-q
を指定しない限り、
.BR getopt (3)
によってエラーが表示される。
.IP "\-s, \-\-shell shell"
指定したシェルのクォート方法に設定する。
\-s オプションが指定されていない場合、
.SM BASH
でのクォート方法が使われる。
指定可能な引き数は、現在のところ
.RB ` sh ',
.RB ` bash ',
.RB ` csh ',
.RB ` tcsh '
である。
.IP "\-u, \-\-unquoted"
出力をクォートしない。
空白と (シェル依存の) 特殊文字は、(他の
.BR getopt (1)
の実装と同じように) このモードでは大混乱を引き起こす。
.IP "\-T \-\-test"
.BR getopt (1) 
が拡張バージョンか古いバージョンかをテストする。
何も出力しないが、エラーステータスを 4 に設定する。
他の
.BR getopt (1)
の実装の場合や、このバージョンで環境変数
.B GETOPT_COMPATIBLE
が設定されている場合、
.RB ` \-\- ' 
を返し、エラーステータスを 0 に設定する。
.IP "\-V, \-\-version"
バージョン情報を出力し、正常終了する。
それ以上は何も出力されない。
.SH 解析
このセクションでは
.B getopt
のパラメータの第 2 部分
.RB ( 「書式」
セクションの
.IR parameters )
のフォーマットについて説明している。
次のセクション
.RB ( 出力 ) 
では生成される出力について説明している。
これらのパラメータは、一般に、シェル関数が呼ばれたときのパラメータである。
シェル関数が呼ばれたときの各パラメータが
.B getopt 
のパラメータリストにある 1 つのパラメータに
厳密に対応している点に注意しなければならない
.RB ( 「例」
セクションを参照すること)。
全ての解析が GNU 
.BR getopt (3) 
ルーチンで行われる。

パラメータは左から右へ解析される。
各パラメータは、短いオプション・長いオプション・オプションへの引き数・
オプションではないパラメータに分類される。

簡単な短いオプションは、
.RB ` \- ' 
の後に短いオプション文字が続くものである。
オプションが引き数を必須としている場合、
引き数はオプション文字の直後に書くことができる。
(コマンドライン上で空白で区切られた) 次のパラメータとして書くこともできる。
オプションが引き数を取ることも取らないこともできる場合、
引き数が存在するならば、オプション文字の直後に書かなければならない。

(最後のオプションを除く) 全てのオプションが
必須の引き数もオプションとしての引き数も必要としない限り、
1 個の
.RB ` \- '
の後に複数の短いオプションを指定することができる。

長いオプションは、通常
.RB ` \-\- ' 
の後に長いオプション名が続く。
オプションが引き数を必須としている場合、
.RB ` = '
で区切って長いオプション名の直後に書くことができる。
また、(コマンドライン上で空白で区切って) 次の引き数として書くこともできる。
オプションが引き数を取ることも取らないこともできる場合、
引き数が存在するならば、
.RB ` = '
で区切って長いオプション名の直後に書かなければならない
.RB (` = '
をオプションの後に書いたにも関らず、その後に何も指定しなかった場合、
引き数が存在しないものとして解釈される。
これはちょっとしたバグである。
.B 「バグ」
セクションを参照すること)。
長いオプションは、省略形が曖昧でない (他のオプションと区別がつく) 限り、
短く省略することができる。

.RB ` \- '
で始まらず、かつ前のオプションが必須としている引き数でもないパラメータは、
オプションではないパラメータである。
.RB ` \-\- ' 
パラメータの後にあるパラメータは、
オプションではないパラメータとして解釈される。
環境変数
.B POSIXLY_CORRECT 
が設定されている場合、
または短いオプション文字列が
.RB ` + '
で始まっている場合、
最初のオプションではないパラメータが見つかった時点で、
残りの全てのパラメータはオプションではないパラメータとして解釈される。
.SH 出力
出力は前のセクションで説明した各要素に対して生成される。
出力は要素が入力で指定された順番で生成される。
ただし、オプションではないパラメータは例外である。
出力は
.I 互換
.RI ( クォートされない )
モードで生成することができる。
また、引き数とオプションではないパラメータに含まれる空白と他の特殊文字を
保護するモードで出力することもできる
.RB ( 「クォート」
セクションを参照すること)。
出力がシェルスクリプトで処理される場合、
その出力は別々の要素から構成されているようにみえる。
この要素は (大部分のシェル言語では shift コマンドを使って)
1 つ 1 つ処理できる。
この動作はクォートされないモードでは不完全である。
なぜなら、要素に空白や特殊文字があった場合、
要素が期待していない箇所で分割されてしまうからである。
必須とされる引き数が見つからない、またはオプションが認識されない、
といった原因でパラメータ解析に問題がある場合、
標準エラーにエラーが表示される。
このとき、不正な要素に対しては何も出力されず、
0 でないエラーステータスが返される。

短いオプションに対して、出力として 1 個の
.RB ` - ' 
とオプション文字が生成される。
オプションが引き数を取る場合、次のパラメータが引き数になる。
オプションが引き数を取っても取らなくてもよい場合に、
引き数が指定されていないと、
クォートモードでは次のパラメータが生成されるが空のパラメータになる。
この場合、クォートしない (互換) モードでは
2 番目のパラメータは生成されない。
他の多くの
.BR getopt (1) 
の実装では、取っても取らなくてもよい引き数は
サポートされていない点に注意すること。

複数の短いオプションが 1 個の
.RB ` \- ' 
の後に指定されている場合、
各オプションは区切られたパラメータとして出力に表示される。

長いオプションに対して、
.RB ` \-\- ' 
と完全なオプション名が 1 つのパラメータとして生成される。
「入力でオプションが略書きされている。
または、オプションが 1 個の
.RB ` \- ' 
を使って指定されている。」ということに関らず、この動作をする。
引き数は短いオプションとして扱われる。

通常、全てのオプションとその引き数が出力に生成されるまで、
オプションではないパラメータは出力されない。
そして、1 個のパラメータとして
.RB ` \-\- ' 
が生成される。
その後にオプションではないパラメータは、
見つかった順番で別々のパラメータとして生成される。
短いオプション文字列の最初の文字が
.RB ` \- '
である場合にのみ、
オプションではないパラメータは入力で見つかった位置で出力される
(この動作は
.B 「書式」
セクションの最初の形式が使われた場合にはサポートされない。
この場合、
.RB ` \- '
と
.RB ` + '
が前に付く全てのパラメータが無視される)。
.SH クォート
互換モードでは、引き数やオプションではないパラメータにある
空白や「特殊」文字は正しく扱われない。
この出力はシェルスクリプトに与えられるので、
スクリプトは、出力をどのようにして個々のパラメータに
分割すべきなのかを知らない。
この問題を回避するため、この実装ではクォート機能を提供する。
これは、各パラメータをクォートして出力を生成する、という手法を取る。
この出力がもう一度シェル (通常はシェルの
.B eval
コマンド) に与えられた場合、
出力は個々のパラメータに正しく分割される。

環境変数
.B GETOPT_COMPATIBLE
が設定された場合・
.B 「書式」
セクションの最初の形式が使われた場合・
.RB ` \-u '
オプションが指定された場合、クォートは行われない。

クォートの規則はシェルごとに異なる。
使用しているシェルを選択するために
.RB ` \-s '
オプションを使うことができる。
以下のシェルで正しく機能する:
.RB ` sh ',
.RB ` bash ',
.RB ` csh ' ,
.RB ` tcsh '.
実際には、2 つの「方式」に分類される:
sh 式のクォート規則と csh 式のクォート規則である。
他のシェルスクリプト言語を使っている場合でも、
これらの方式のどちらかが使える可能性がある。

.SH スキャンモード
特殊なスキャンモードであることを示すために、
短いオプションの最初の文字を
.RB ` \- '
または
.RB ` + '
にすることができる。
.B 「書式」
セクションの最初の呼び出し形式が使われた場合、これは無視される。
しかし、環境変数
.B POSIXLY_CORRECT
が指定されているかどうかは調べられる。

最初の文字が
.RB ` + '
の場合、または環境変数
.B POSIXLY_CORRECT
が設定されている場合、オプションではない最初のパラメータ
(つまり、
.RB ` \- '
で始まっていないパラメータ) が
オプション引き数でないと分かった時点で解析はストップする。
それ以降の全てのパラメータは、オプションではないパラメータとして解釈される。

最初の文字が
.RB ` \- '
の場合、オプションではない引き数は見つかった箇所で出力される。
通常の操作では、
.RB ` \-\- ' 
パラメータが生成された後で、最後にまとめて出力される。
この場合でも
.RB ` \-\- '
パラメータは生成されるが、
通常このモードでは最後のパラメータになる点に注意すること。
.SH 互換性
このバージョンの
.BR getopt (1)
は、出来るだけ他のバージョンと互換性があるように書かれた。
通常は他のバージョンを修正することなく、
このバージョンに置き換えることができる。
更に、いくつかの利点がある。

getopt の最初のパラメータの最初の文字が
.RB ` \- '
でない場合、getopt は互換モードになる。
最初のパラメータは短いオプションの文字列として解釈され、
他の全ての引き数が解析される。
この場合でも、環境変数
.B POSIXLY_CORRECT 
が設定されていない限り、パラメータの並べ替えを行う
(つまり、オプションではない全てのパラメータが最後に出力される)。

環境変数
.B GETOPT_COMPATIBLE 
は
.B getopt
を強制的に互換モードにする。
この環境変数と
.B POSIXLY_CORRECT
の両方を設定すると、「難しい」プログラムのために 100% の互換性を提供する。
しかし、通常はどちらも設定する必要がない。

互換モードでは、短いオプション文字列の最初に付く
.RB ` \- '
と
.RB ` + '
は無視される。
.SH リターンコード
解析に成功した場合、
.B getopt
はエラーコード
.B 0 
を返す。
.BR getopt (3)
がエラーを返した場合は
.B 1
を返す。
パラメータが理解できなかった場合は
.B 2 
を返す。
メモリが足りない (out\-of\-memory) といった内部エラーの場合は
.B 3
を返す。
.BR \-T
オプションを付けて呼び出された場合は
.B 4
を返す。
.SH 例
(ba)sh と (t)csh での使用例のスクリプトは、
.BR getopt (1)
ディストリビューションで提供されている。
これらはオプションとして
.B /usr/local/lib/getopt 
または
.B /usr/lib/getopt
にインストールされている。
.SH 環境変数
.IP POSIXLY_CORRECT
この環境変数は
.BR getopt (3)
ルーチンで調べられる。
これが設定されている場合、パラメータがオプションまたは
オプション引き数でないと分かった時点で解析は停止する。
それ以降の全てのパラメータは、
.RB ` \- '
で始まっているかどうかに関係なく、
オプションではないパラメータとして解釈される。
.IP GETOPT_COMPATIBLE
.B getopt
に対して強制的に
.B 「書式」
セクションの最初の呼び出し形式を使わせる。
.SH バグ
.BR getopt (3)
は、引き数を取っても取らなくてもよい長いオプションを解析できる
(ただし、短いオプションの場合は解析できない)。
この
.BR getopt (1)
は、オプション引き数が指定されていない場合、それが存在しないものとして扱う。

短いオプション変数を全く使いたくない場合、
書式は全く直感的でないものになる
(明示的に空の文字列に設定する必要がある)。

.SH 著者
Frodo Looijaard <frodol@dds.nl>
.SH 関連項目
.BR getopt (3),
.BR bash (1),
.BR tcsh (1).