.\" Copyright (c) 1992, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" This code is derived from software contributed to Berkeley by
.\" Casey Leedom of Lawrence Livermore National Laboratory.
.\"
.\" 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.
.\"
.\"	@(#)getcap.3	8.4 (Berkeley) 5/13/94
.\"
.\" $FreeBSD$
.Dd May 13, 1994
.Dt GETCAP 3 
.Os
.Sh 名称
.Nm cgetent ,
.Nm cgetset ,
.Nm cgetmatch ,
.Nm cgetcap ,
.Nm cgetnum ,
.Nm cgetstr ,
.Nm cgetustr ,
.Nm cgetfirst ,
.Nm cgetnext ,
.Nm cgetclose
.Nd ケーパビリティデータベースにアクセスするルーチン 
.Sh 書式
.Fd #include <stdlib.h>
.Ft int
.Fn cgetent "char **buf" "char **db_array" "char *name"
.Ft int
.Fn cgetset "char *ent"
.Ft int
.Fn cgetmatch "char *buf" "char *name"
.Ft char *
.Fn cgetcap "char *buf" "char *cap" "int type"
.Ft int
.Fn cgetnum "char *buf" "char *cap" "long *num"
.Ft int
.Fn cgetstr "char *buf" "char *cap" "char **str"
.Ft int
.Fn cgetustr "char *buf" "char *cap" "char **str"
.Ft int
.Fn cgetfirst "char **buf" "char **db_array"
.Ft int
.Fn cgetnext "char **buf" "char **db_array"
.Ft int
.Fn cgetclose "void"
.Sh 解説
.Fn cgetent
は、
.Dv NULL
で終わるファイル配列
.Fa db_array
で指定したデータベースから、ケーパビリティ
.Em name
を抜き出し、
.Fa buf
内に malloc したそのコピーのポインタを返します。
.Fn cgetent
関数は
.Dv ASCII
ファイルにアクセスする前に、まず、
.Nm .db
で終わるファイルを探します(
.Xr cap_mkdb 1
参照)。
.Fa Buf
は、以後の
.Fn cgetmatch ,
.Fn cgetcap ,
.Fn cgetnum ,
.Fn cgetstr
および
.Fn cgetustr
の呼び出しすべてを通じて保持されなければなりませんが、呼び出しの完了後は 
.Xr free 3
できます。抜き出しに成功した場合は 0が、返すレコードに未解決な
.Nm tc
拡張の含まれている場合は 1が、要求されたレコードの見付からなかった場合は
\-1 が返ります。システムエラー(ファイルがオープンできなかった/読み取れ
なかった、など)が発生した場合は
\-2 が返るとともに、
.Va errno
が設定されます。また、潜在的な参照ループが検出された場合は
\-3 が返ります(後述の
.Ic tc=
参照)。
.Pp
.Fn cgetset
関数は、1 つのケーパビリティレコードエントリが含まれた、キャラクタバッ
ファのケーパビリティデータベースへの追加を有効にします。 概念的には、
このエントリが最初の ``ファイル'' としてデータベースに追加されるので、
.Fn cgetent
の呼び出しでは最初に検索されます。エントリは
.Fa ent
に渡されますが、
.Fa ent
が
.Dv NULL
の場合、現在のエントリはデータベースから除去されます。
.Fn cgetset
の呼び出しは、データベースの走査に先行しなければなりません。
.Fn cgetent
呼び出しの前に、呼び出す必要があります。シーケンシャルなアクセスを実行
する場合は、最初のシーケンシャルアクセス呼び出し(
.Fn cgetfirst
または
.Fn cgetnext
)の前に呼び出すか、
.Fn cgetclose
呼び出しの直後に呼び出す必要があります(後掲参照)。呼び出しに成功した場合は
0 が、失敗した場合は \-1 が返ります。
.Pp
.Fn cgetmatch
関数は、
.Em name
がケーパビリティレコード
.Fa buf
の名前の 1つならば 0を、そうでなければ
\-1 を返します。
.Pp
.Fn cgetcap
関数は、タイプ
.Fa type
によってケーパビリティ
.Fa cap
を、ケーパビリティレコード
.Fa buf
で検索します。タイプは、1 つのキャラクタを使用して指定します。コロン 
(`:')を使用した場合は、タイプのないケーパビリティが検索されます(後掲の
タイプの説明を参照してください)。検索が成功した場合は
.Fa buf
にある
.Fa cap
値のポインタが返ります。要求されたケーパビリティが見付からない場合は、
.Dv NULL
が返ります。ケーパビリティ値の終わりは、
.Ql :
または
.Tn ASCII
.Dv NUL
で示されます(後掲のケーパビリティデータベースの構文を、参照してくださ
い)。 
.Pp
.Fn cgetnum
関数は、
.Fa buf
で示されたケーパビリティレコードから、数値ケーパビリティ
.Fa cap
の値を取り出します。この数値は
.Fa num
に示される
.Ft long
で返されます。成功した場合は 0が返ります。要求された数値ケーパビリティが
見付からない場合は \-1 が返ります。
.Pp
.Fn cgetstr
関数は、
.Fa buf
で示されたケーパビリティレコードから、ストリングケーパビリティ
.Fa cap
の値を取り出します。そのストリングのデコードされ、
.Dv NUL
で終わる
.Xr malloc
されたコピーのポインタが、
.Fa str
に示される
.Ft char *
で返されます。成功した場合は、デコードされたストリングの終端の
.Dv NUL
を含まない数が返ります。要求されたストリングケーパビリティが見付からな
い場合は \-1 が返り、システムエラー(ストレージ割り振りエラー)が発生し
た場合は \-2 が返ります。
.Pp
.Fn cgetustr
関数は
.Fn cgetstr
と同様な機能ですが、特殊キャラクタを拡張しないで、むしろケーパビリティ
ストリングの、文字どおり各キャラクタを返すところが違います。
.Pp
.Fn cgetfirst
および
.Fn cgetnext
関数は、ファイル名が
.Dv NULL
ポインタで終わる配列
.Fa db_array
への、シーケンシャルなアクセスができる関数グループを構成します。
.Fn cgetfirst
関数は、指定データベースにある最初のレコードを返し、最初のレコードへの
アクセスをリセットします。 
.Fn cgetnext
関数は、前の
.Fn cgetfirst
または
.Fn cgetnext
呼び出しによって返ったレコードの、指定データベースにある次のレコードを
返します。前の呼び出しがない場合は、指定データベースにある最初のレコー
ドを返します。各レコードは 
.Fa buf
で示される
.Xt malloc
されたコピーで返り、
.Ic tc
拡張がなされます。(後掲の
.Ic tc=
の説明を参照してください。)
データベース検索を完了して、返すレコードがない場合は 0が返ります。検索
に成功して返すレコードがあり、さらに次のレコードの残っている可能性があ
る(データベースの終わりにまだ達していない)場合は 1が返ります。返すレコー
ドに、未解決な 
.Nm tc
拡張の含まれている場合は 2が返ります。システムエラーの発生した場合は 
\-1 が返ります。潜在的な参照ループが検出された場合は \-2 が返ります。
(後掲の
.Ic tc=
の説明を参照してください。)データベースが完了した(0が返った)場合、デー
タベースはクローズされます。 
.Pp
.Fn cgetclose
関数は、シーケンシャルなアクセスをクローズし、すべてのメモリおよび使用
されていたファイル記述子を解放します。 
.Fn cgetset
の呼び出しによってプッシュされたバッファは、消去されないことに注意して
ください。 
.Sh ケーパビリティデータベースの構文
ケーパビリティデータベースは一般に
.Tn ASCII
です。標準のテキストエディタで編集できます。空白行および `#' で始まる
行はコメントなので無視されます。`\|\e' で終わる行は、次の行が現在の行 
の続きであることを示します。この `\|\e' および後に続く改行は無視されま
す。長い行はふつういくつかの物理行に分割され、最終行を除いて各行末に
`\|\e' が付けられます。
.Pp
ケーパビリティデータベースは、一連のレコード(1論理行当たり1つ)によって 
構成されます。各レコードには、可変数の `:' で分けられたフィールド(ケー
パビリティ)が含まれます。空白スペースキャラクタ(スペースおよびタブ)で、
すべて構成されるフィールドは無視されます。
.Pp
各レコードの最初のケーパビリティは、 `|' キャラクタで分けられた名前(複
数)を指定します。取り決めによって最後の名前は常にコメントで、ルックアッ
プタグとしての意図はありません。たとえば、
.Nm termcap
データベースの
.Em vt100
レコードの最初は次のとおりです。
.Pp
.Dl "d0\||\|vt100\||\|vt100-am\||\|vt100am\||\|dec vt100:"
.Pp
ここでは最初から 4つの名前が、このレコードのアクセスに使用できます。
.Pp
残りの空白ではないケーパビリティはそれぞれ、オプションでタイプ指定値が
後に続く名前を、(名前、値)結合セットで記述します。次のとおりです。
.Bl -column "nameTvalue"
.It 名前 Ta "タイプのない[ブール] ケーパビリティ名 [真の]"
.It name Ns Em \&T Ns value Ta 値
.Em value
をもつケーパビリティ
.Pq Em name , \&T
.It name@ Ta
存在する非ケーパビリティ
.Em name
.It nameT@ Ta
存在しない(非在の)ケーパビリティ
.Pq Em name , \&T
.El
.Pp
名前は、1つまたは複数のキャラクタで構成されます。名前には  `:' を除く
あらゆるキャラクタを含めることができますが、印刷可能キャラクタに限定し
て、 `#' 、`=' 、`%' 、`@' などのグラフィックキャラクタの使用を避ける
のが、通常は最良です。タイプは、ケーパビリティ名をそれぞれの関連タイプ
指定値から区別するのに使用される 1つのキャラクタです。`:' を除くすべて
のキャラクタが使用できますが、ふつうは `#'、`=' 、`%' 、などのグラフィッ
クキャラクタが使用されます。値は無制限な数のキャラクタで、`:' を除くす
べてのキャラクタが使用できます。 
.Sh ケーパビリティデータベースの意味論
ケーパビリティレコードは、(名前、値)結合のセットを記述します。名前は、 
それらに結合された複数の値を持つことができます。1つの名前に対する異な
る値は、それぞれの
.Fa type
によって識別されます。
.Fn cgetcap
関数は、ケーパビリティ名およびその値のタイプが与えられた、名前の値のポ
インタを返します。
.Pp
タイプ `#' および `=' は慣用で、数値およびストリングタイプ指定の値を示
しますが、これらのタイプのそうした用途限定は強制的なものではありません。 
関数
.Fn cgetnum
および
.Fn cgetstr
によって、`#' および `=' の従来の構文および意味論が実行できます。タイ
プのないケーパビリティは、ふつう真値および偽値をそれぞれ示す存在または
非在付きの、ブールオブジェクトを示します。この解釈は簡単に次のように表
すことができます。 
.Pp
.Dl "(getcap(buf, name, ':') != NULL)"
.Pp
特殊ケーパビリティ
.Ic tc= name
は、名前によって指定したレコードを
.Ic tc
ケーパビリティに置き換えるように指示します。
.Ic tc
ケーパビリティは、同じく
.Ic tc
ケーパビリティが含まれたレコードを補間できます。1つのレコード内で、複数の
.Ic tc
ケーパビリティが使用できます。
.Ic tc
の拡張範囲(すなわち引数が検索される範囲)には、
.Ic tc
が宣言されたファイル以降の、そのファイル配列にあるすべてのファイルが含
まれます。 
.Pp
ケーパビリティレコードをデータベースで検索する場合は、その検索で最初に
適合したレコードが返ります。ケーパビリティをレコードでスキャンする場合は、
最初に適合したケーパビリティが返ります。ケーパビリティ
.Ic :nameT@:
は、後に続く名前のタイプ
.Em T
の値の、あらゆる定義を隠します。また、ケーパビリティ
.Ic :name@:
は、後に続く名前のあらゆる値を不可視にします。
.Pp
.Ic tc
ケーパビリティと組み合わされたこれらの機能は、新しいケーパビリティを追
加したり、新しい定義によってこれまでの定義を上書きしたり、または `@' 
ケーパビリティによって後に続く定義を隠したりすることによって、ほかのデー 
タベースまたはレコードをさまざまに変化させることができます。 
.Sh 例
.Bd -unfilled -offset indent
example\||\|an example of binding multiple values to names:\e
	:foo%bar:foo^blah:foo@:\e
	:abc%xyz:abc^frap:abc$@:\e
	:tc=more:
.Ed
.Pp
ケーパビリティ foo にはそれに結合された2 つの値(タイプ `%' の bar および
タイプ `^' のblah)があります。結合されたほかのすべての値は隠されています。
ケーパビリティabc にも結合された2つの値がありますが、ケーパビリティレコード
 more での定義が禁止されているのは、タイプ `$' の値だけです。
.Pp
.Bd -unfilled -offset indent
file1:
 	new\||\|new_record\||\|a modification of "old":\e
		:fript=bar:who-cares@:tc=old:blah:tc=extensions:
file2:
	old\||\|old_record\||\|an old database record:\e
		:fript=foo:who-cares:glork#200:
.Ed
.Pp
これらのレコードを抜き出す場合は、file2の前にfile1で 
.Fn cgetent
を呼び出します。それによって file1 の新ケーパビリティレコード 
fript=bar が、file2 の旧ケーパビリティレコードから補間された fript=foo 
を上書きします。また、who-cares@ が旧レコードにあるすべての who-cares 
定義を不可視にします。さらに、glork#200 が旧レコードから持ち越され、 
blah および、このレコードの拡張によって定義された一切が旧レコード内の
それら定義に追加されます。ここでは、tc=old の前に fript=bar および 
who-cares@ の定義を置くことが重要です。それらの定義を tc=old の後に置
いた場合は、旧レコードの定義が優先されます。
.Sh CGETNUMおよびCGETSTRの構文と意味論
.Fn cgetnum
および
.Fn cgetstr
によって定義ずみの、2つのタイプがあります。次のとおりです。
.Bl -column "nameXnumber"
.Sm off
.It Em name No \&# Em number Ta "値"
.Em number
を持つ数値ケーパビリティ名
.It Em name No = Em string Ta "値"
.Em string
を持つストリングケーパビリティ名
.It Em name No \&#@ Ta "存在しない(非在)数値ケーパビリティ名"
.It Em name No \&=@ Ta "存在しない(非在)ストリングケーパビリティ名"
.El
.Pp
数値ケーパビリティ値は、3 つの基数のどれかで与えることができます。 
.Q1 0x
または 
.Q1 0X
で始まる数は、16 進数として解釈されます(大文字および小文字の a-f を使っ
て16 進数の拡張桁を示すことができます)。その他の 
.Q1 0
で始まる 
数字は、8 進数として解釈されます。残りの数字はすべて 10 進数として解釈
されます。 
.Pp
ストリングケーパビリティ値には、あらゆるキャラクタを含めることができます。
印刷可能ではない
.Dv ASCII
コード、改行コードやコロンなどが、エスケープシーケンスを使って簡単に表
せます。次のとおりです。
.Bl -column "\e\|X,X\e\|X" "(ASCII octal nnn)"
^X	('X' & 037)	コントロール X
\e\|b, \e\|B	(ASCII 010)	バックスペース
\e\|t, \e\|T	(ASCII 011)	タブ
\e\|n, \e\|N	(ASCII 012)	ラインフィード(改行)
\e\|f, \e\|F	(ASCII 014)	フォームフィード
\e\|r, \e\|R	(ASCII 015)	キャリッジリターン
\e\|e, \e\|E	(ASCII 027)	エスケープ
\e\|c, \e\|C	(:)	コロン
\e\|\e	(\e\|)	バックスラッシュ
\e\|^	(^)	キャレット
\e\|nnn	(ASCII 8進数 nnn)
.El
.Pp
`\|\e の後に最大 3 桁の 8 進数を続ければ、特定キャラクタの数値コードを 
直接指定することができます。ただし、エンコードは簡単でも 
.Dv ASCII 
.Dv NUL
を多用すると、あらゆる問題の原因となる可能性があります。
.Dv NUL
はふつうストリングの終わりを示しますから、使用に当たっては注意が必要
です。多くのアプリケーションで、
.Dv NUL
を表すのに `\e\|200' が使用されています。
.Sh 診断
.Fn Cgetent ,
.Fn cgetset ,
.Fn cgetmatch ,
.Fn cgetnum ,
.Fn cgetstr ,
.Fn cgetustr ,
.Fn cgetfirst , 
および
.Fn cgetnext
などは、いずれも成功した場合は 0またはそれを上回る価を返し、失敗した場
合は 0を下回る値を返します。
.Fn cgetcap
関数の場合は、成功するとキャラクタポインタを、失敗すると
.Dv NULL
を返します。
.Pp
.Fn cgetent
および
.Fn cgetseq
関数の失敗では、
.Va errno
が、ほかのライブラリ関数
.Xr fopen 2 ,
.Xr close 2 ,
.Xr open 2 ,
および
.Xr close 2
などのエラーに設定される場合があります。
.Pp
.Fn cgetent ,
.Fn cgetset ,
.Fn cgetstr
および
.Fn cgetustr
の失敗では、次のエラーに
.Va errno
が設定される場合があります。
.Bl -tag -width Er
.It Bq Er ENOMEM
割り振るメモリがありません。
.El
.Sh 関連項目
.Pp
.Xr cap_mkdb 1 ,
.Xr malloc 3
.Sh バグ
コロン (`:') が、名前、タイプ、値に使用できません。
.Pp
.Fn cgetent
に、
.Ic tc=name
ループのチェックがありません。
.Pp
.Fn cgetset
の呼び出しによってバッファをデータベースに追加することは、このデータベー
スに限りませんが、ほかの使用データベースに追加する場合は、後ではなく前
に付加する方が無難です。