.\" Copyright (c) 1988, 1991, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"     @(#)getopt.3	8.5 (Berkeley) 4/27/95
.\"
.\" $FreeBSD$
.Dd April 27, 1995
.Dt GETOPT 3
.Os BSD 4.3
.Sh 名称
.Nm getopt
.Nd コマンドラインの引数リストからのオプション文字の取得
.Sh 書式
.Fd #include <unistd.h>
.Vt extern char *optarg;
.Vt extern int   optind;
.Vt extern int   optopt;
.Vt extern int   opterr;
.Vt extern int   optreset;
.Ft int
.Fn getopt "int argc" "char * const *argv" "const char *optstring"
.Sh 解説
.Fn getopt
関数はコマンドラインの引数リスト
.Fa argv
を逐次的に解析して、次の
.Em 既知
オプション文字を返します。受け入れオプション文字集合の文字列
.Fa optstring
に指定されていた場合、そのオプション文字は
.Em 既知
です。
.Pp
オプション文字列
.Fa optstring
は次の要素含み得ます。それは、個々の文字と、後にコロンが付いた文字です。
コロン付きの文字は後にオプションの引数が続くことを意味します。たとえば、
オプション文字列
.Li "\&""x""
はオプション
.Dq Fl x
を受け入れ、
オプション文字列
.Li "\&""x:""
はオプションと引数
.Dq Fl x argument
を受け入れます。後に続く引数の頭に余白があっても、
.Fn getopt
は構いません。
.Pp
.Fn getopt
からの戻ると、
.Va optarg
はそれが予期されていればオプションの引数を示し、変数
.Va optind
には以後の
.Fn getopt
呼び出しで使用する、次の
.Fa argv
引数のインデックスが含まれます。また変数
.Va optopt
は、
.Fn getopt
によって返された最後の
.Em 既知
オプション文字を保存します。
.Pp
変数
.Va opterr
および
.Va optind
はどちらも 1 に初期化されます。多かれ少なかれ
.Fa argv
エントリを飛び越すための
.Fn getopt
呼び出しの設定前ならば、
.Va optind
変数は別の値に設定できます。
.Pp
複数セットの引数の評価または、1 つの引数セットの複数回評価のために
.Fn getopt
を使用する場合、2 回目以降の
.Fn getopt
各追加呼び出し設定前に変数
.Va optreset
は １ に設定し、変数
.Va optind
は再初期化する必要があります。
.Pp
.Fn getopt
関数は引数リストを使い果たした場合 \-1 を、受け入れられない
オプションに出会った場合は
.Ql ?
を返します。引数リストにあるオプションの解釈は、オプション
.Ql --
(2 重のダッシュ) によって取り消すことができます。
このオプションによって、
.Fn getopt
は引数処理の終わりを伝え、\-1 を返します。
すべてのオプションの処理が終わると
(すなわち、最初の非オプション引数に出会うと)
.Fn getopt
は \-1 を返します。
.Sh 診断
文字列
.Va optarg
にない文字に出会うか、またはオプション引数の欠落を検出すると、
.Fn getopt
関数はエラーメッセージを
.Em stderr
に書き出して
.Ql ?
を返します。
.Va opterr
を 0 に設定すると、これらのエラーメッセージは無効になります。
.Fa optstring
の頭に
.Ql \&:
を付ければ、オプション引数に
欠落があった場合、あらゆるエラーメッセージを抑制した上で
.Ql \&:
が返ります。
.Pp
オプション引数を
.Dq Li \-
で開始可能です。これは合理的ですが、反面で
可能なエラーチェック回数を減らすという不利があります。
.Sh 拡張
.Fn getopt
関数の複数回呼び出しを可能にするため、
.Va optreset
変数が追加されました。これは
.St -p1003.2
規格への拡張です。
.Sh 使用例
.Bd -literal -compact
extern char *optarg;
extern int optind;
int bflag, ch, fd;

bflag = 0;
while ((ch = getopt(argc, argv, "bf:")) != -1)
	switch (ch) {
	case 'b':
		bflag = 1;
		break;
	case 'f':
		if ((fd = open(optarg, O_RDONLY, 0)) < 0) {
			(void)fprintf(stderr,
			    "myname: %s: %s\en", optarg, strerror(errno));
			exit(1);
		}
		break;
	case '?':
	default:
		usage();
	}
argc -= optind;
argv += optind;
.Ed
.Sh 歴史
.Fn getopt
関数は
.Bx 4.3
で最初に取り入れられました。
.Sh バグ
.Fn getopt
関数はいったん、\-1 の代わりに
.Dv EOF
を返すように指定されました。これは、
.Fn getopt
を
.Aq Pa stdio.h
から切り離すことで、
.St -p1003.2-92
により変更されました。
.Pp
.Fa optstring
の文字として単一ダッシュ
.Dq Li -
も指定できますが、
関連する引数を持つことは
.Em 決して
許されません。このため、オプションフラグとして
.Dq Li -
が予期されるプログラムでも、
.Fn getopt
を使用可能です。しかし、これは間違いです。
現在のどのようなプログラム開発でもこれは使うべきではありません。
下位互換のため
.Em だけ
に存在します。
デフォルトで単一ダッシュは、
.Fn getopt
に \-1 を返させます。これは System V と互換であるはずです。
.Pp
オプション文字として数字も使えます。このため、オプションとして数字
.Pq Dq Li \&-\&3
が予期されるプログラムでも
.Fn getopt
を使用可能です。しかし、これは間違いです。
現在のどのようなプログラム開発でもこれは使うべきではありません。
下位互換のため
.Em だけ
に存在します。
次のコードフラグメントが、ほとんどの場合に動作します。
.Bd -literal -offset indent
int length;
char *p;

while ((ch = getopt(argc, argv, "0123456789")) != -1)
	switch (ch) {
	case '0': case '1': case '2': case '3': case '4':
	case '5': case '6': case '7': case '8': case '9':
		p = argv[optind - 1];
		if (p[0] == '-' && p[1] == ch && !p[2])
			length = atoi(++p);
		else
			length = atoi(argv[optind] + 1);
		break;
	}
.Ed