GETCAP

Section: C Library Functions (3)
索引 jman

BSD mandoc

名称

cgetent cgetset cgetmatch cgetcap cgetnum cgetstr cgetustr cgetfirst cgetnext cgetclose - ケーパビリティデータベースにアクセスするルーチン

索引

書式

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

索引

解説

Fn cgetent は、 NULL で終わるファイル配列 Fa db_array で指定したデータベースから、ケーパビリティ name を抜き出し、 Fa buf 内に malloc したそのコピーのポインタを返します。 Fn cgetent 関数は ASCII ファイルにアクセスする前に、まず、 .db で終わるファイルを探します( cap_mkdb1 参照)。 Fa Buf は、以後の Fn cgetmatch , Fn cgetcap , Fn cgetnum , Fn cgetstr および Fn cgetustr の呼び出しすべてを通じて保持されなければなりませんが、呼び出しの完了後は free(3) できます。抜き出しに成功した場合は 0が、返すレコードに未解決な tc 拡張の含まれている場合は 1が、要求されたレコードの見付からなかった場合は -1 が返ります。システムエラー(ファイルがオープンできなかった/読み取れなかった、など)が発生した場合は -2 が返るとともに、 errno が設定されます。また、潜在的な参照ループが検出された場合は -3 が返ります(後述の tc= 参照)。

Fn cgetset 関数は、1 つのケーパビリティレコードエントリが含まれた、キャラクタバッファのケーパビリティデータベースへの追加を有効にします。概念的には、このエントリが最初の ``ファイル'' としてデータベースに追加されるので、 Fn cgetent の呼び出しでは最初に検索されます。エントリは Fa ent に渡されますが、 Fa ent が NULL の場合、現在のエントリはデータベースから除去されます。 Fn cgetset の呼び出しは、データベースの走査に先行しなければなりません。 Fn cgetent 呼び出しの前に、呼び出す必要があります。シーケンシャルなアクセスを実行する場合は、最初のシーケンシャルアクセス呼び出し( Fn cgetfirst または Fn cgetnext )の前に呼び出すか、 Fn cgetclose 呼び出しの直後に呼び出す必要があります(後掲参照)。呼び出しに成功した場合は 0 が、失敗した場合は -1 が返ります。

Fn cgetmatch 関数は、 name がケーパビリティレコード Fa buf の名前の 1つならば 0を、そうでなければ -1 を返します。

Fn cgetcap 関数は、タイプ Fa type によってケーパビリティ Fa cap を、ケーパビリティレコード Fa buf で検索します。タイプは、1 つのキャラクタを使用して指定します。コロン (`:')を使用した場合は、タイプのないケーパビリティが検索されます(後掲のタイプの説明を参照してください)。検索が成功した場合は Fa buf にある Fa cap 値のポインタが返ります。要求されたケーパビリティが見付からない場合は、 NULL が返ります。ケーパビリティ値の終わりは、 `:' または ASCII NUL で示されます(後掲のケーパビリティデータベースの構文を、参照してください)。

Fn cgetnum 関数は、 Fa buf で示されたケーパビリティレコードから、数値ケーパビリティ Fa cap の値を取り出します。この数値は Fa num に示される Ft long で返されます。成功した場合は 0が返ります。要求された数値ケーパビリティが見付からない場合は -1 が返ります。

Fn cgetstr 関数は、 Fa buf で示されたケーパビリティレコードから、ストリングケーパビリティ Fa cap の値を取り出します。そのストリングのデコードされ、 NUL で終わる malloc されたコピーのポインタが、 Fa str に示される Ft char * で返されます。成功した場合は、デコードされたストリングの終端の NUL を含まない数が返ります。要求されたストリングケーパビリティが見付からない場合は -1 が返り、システムエラー(ストレージ割り振りエラー)が発生した場合は -2 が返ります。

Fn cgetustr 関数は Fn cgetstr と同様な機能ですが、特殊キャラクタを拡張しないで、むしろケーパビリティストリングの、文字どおり各キャラクタを返すところが違います。

Fn cgetfirst および Fn cgetnext 関数は、ファイル名が NULL ポインタで終わる配列 Fa db_array への、シーケンシャルなアクセスができる関数グループを構成します。 Fn cgetfirst 関数は、指定データベースにある最初のレコードを返し、最初のレコードへのアクセスをリセットします。 Fn cgetnext 関数は、前の Fn cgetfirst または Fn cgetnext 呼び出しによって返ったレコードの、指定データベースにある次のレコードを返します。前の呼び出しがない場合は、指定データベースにある最初のレコードを返します。各レコードは Fa buf で示される Xt malloc されたコピーで返り、 tc 拡張がなされます。(後掲の tc= の説明を参照してください。) データベース検索を完了して、返すレコードがない場合は 0が返ります。検索に成功して返すレコードがあり、さらに次のレコードの残っている可能性がある(データベースの終わりにまだ達していない)場合は 1が返ります。返すレコードに、未解決な tc 拡張の含まれている場合は 2が返ります。システムエラーの発生した場合は -1 が返ります。潜在的な参照ループが検出された場合は -2 が返ります。 (後掲の tc= の説明を参照してください。)データベースが完了した(0が返った)場合、データベースはクローズされます。

Fn cgetclose 関数は、シーケンシャルなアクセスをクローズし、すべてのメモリおよび使用されていたファイル記述子を解放します。 Fn cgetset の呼び出しによってプッシュされたバッファは、消去されないことに注意してください。

索引

ケーパビリティデータベースの構文

ケーパビリティデータベースは一般に ASCII です。標準のテキストエディタで編集できます。空白行および `#' で始まる行はコメントなので無視されます。`\' で終わる行は、次の行が現在の行の続きであることを示します。この `\' および後に続く改行は無視されます。長い行はふつういくつかの物理行に分割され、最終行を除いて各行末に `\' が付けられます。

ケーパビリティデータベースは、一連のレコード(1論理行当たり1つ)によって構成されます。各レコードには、可変数の `:' で分けられたフィールド(ケーパビリティ)が含まれます。空白スペースキャラクタ(スペースおよびタブ)で、すべて構成されるフィールドは無視されます。

各レコードの最初のケーパビリティは、 `|' キャラクタで分けられた名前(複数)を指定します。取り決めによって最後の名前は常にコメントで、ルックアップタグとしての意図はありません。たとえば、 termcap データベースの vt100 レコードの最初は次のとおりです。

"d0|vt100|vt100-am|vt100am|dec vt100:"

ここでは最初から 4つの名前が、このレコードのアクセスに使用できます。

残りの空白ではないケーパビリティはそれぞれ、オプションでタイプ指定値が後に続く名前を、(名前、値)結合セットで記述します。次のとおりです。

名前 Ta タイプのない[ブール] ケーパビリティ名 [真の]
name T value Ta 値: value をもつケーパビリティ (name , T )
name@ Ta 存在する非ケーパビリティ: name
nameT@ Ta 存在しない(非在の)ケーパビリティ: (name , T )

名前は、1つまたは複数のキャラクタで構成されます。名前には `:' を除くあらゆるキャラクタを含めることができますが、印刷可能キャラクタに限定して、 `#' 、`=' 、`%' 、`@' などのグラフィックキャラクタの使用を避けるのが、通常は最良です。タイプは、ケーパビリティ名をそれぞれの関連タイプ指定値から区別するのに使用される 1つのキャラクタです。`:' を除くすべてのキャラクタが使用できますが、ふつうは `#'、`=' 、`%' 、などのグラフィックキャラクタが使用されます。値は無制限な数のキャラクタで、`:' を除くすべてのキャラクタが使用できます。

索引

ケーパビリティデータベースの意味論

ケーパビリティレコードは、(名前、値)結合のセットを記述します。名前は、それらに結合された複数の値を持つことができます。1つの名前に対する異なる値は、それぞれの Fa type によって識別されます。 Fn cgetcap 関数は、ケーパビリティ名およびその値のタイプが与えられた、名前の値のポインタを返します。

タイプ `#' および `=' は慣用で、数値およびストリングタイプ指定の値を示しますが、これらのタイプのそうした用途限定は強制的なものではありません。関数 Fn cgetnum および Fn cgetstr によって、`#' および `=' の従来の構文および意味論が実行できます。タイプのないケーパビリティは、ふつう真値および偽値をそれぞれ示す存在または非在付きの、ブールオブジェクトを示します。この解釈は簡単に次のように表すことができます。

"(getcap(buf, name, ':') != NULL)"

特殊ケーパビリティ tc= name は、名前によって指定したレコードを tc ケーパビリティに置き換えるように指示します。 tc ケーパビリティは、同じく tc ケーパビリティが含まれたレコードを補間できます。1つのレコード内で、複数の tc ケーパビリティが使用できます。 tc の拡張範囲(すなわち引数が検索される範囲)には、 tc が宣言されたファイル以降の、そのファイル配列にあるすべてのファイルが含まれます。

ケーパビリティレコードをデータベースで検索する場合は、その検索で最初に適合したレコードが返ります。ケーパビリティをレコードでスキャンする場合は、最初に適合したケーパビリティが返ります。ケーパビリティ :nameT@: は、後に続く名前のタイプ T の値の、あらゆる定義を隠します。また、ケーパビリティ :name@: は、後に続く名前のあらゆる値を不可視にします。

tc ケーパビリティと組み合わされたこれらの機能は、新しいケーパビリティを追加したり、新しい定義によってこれまでの定義を上書きしたり、または `@' ケーパビリティによって後に続く定義を隠したりすることによって、ほかのデータベースまたはレコードをさまざまに変化させることができます。

索引

例

example|an example of binding multiple values to names:\
        :foo%bar:foo^blah:foo@:\
        :abc%xyz:abc^frap:abc$@:\
        :tc=more:

ケーパビリティ foo にはそれに結合された2 つの値(タイプ `%' の bar およびタイプ `^' のblah)があります。結合されたほかのすべての値は隠されています。ケーパビリティabc にも結合された2つの値がありますが、ケーパビリティレコード
more での定義が禁止されているのは、タイプ `$' の値だけです。

file1:
        new|new_record|a modification of "old":\
                :fript=bar:who-cares@:tc=old:blah:tc=extensions:
file2:
        old|old_record|an old database record:\
                :fript=foo:who-cares:glork#200:

これらのレコードを抜き出す場合は、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 の後に置いた場合は、旧レコードの定義が優先されます。

索引

CGETNUMおよびCGETSTRの構文と意味論

Fn cgetnum および Fn cgetstr によって定義ずみの、2つのタイプがあります。次のとおりです。

name # number Ta 値: number を持つ数値ケーパビリティ名
name = string Ta 値: string を持つストリングケーパビリティ名
name #@ Ta 存在しない(非在)数値ケーパビリティ名
name =@ Ta 存在しない(非在)ストリングケーパビリティ名

数値ケーパビリティ値は、3 つの基数のどれかで与えることができます。またはで始まる数は、16 進数として解釈されます(大文字および小文字の a-f を使って16 進数の拡張桁を示すことができます)。その他ので始まる数字は、8 進数として解釈されます。残りの数字はすべて 10 進数として解釈されます。

ストリングケーパビリティ値には、あらゆるキャラクタを含めることができます。印刷可能ではない ASCII コード、改行コードやコロンなどが、エスケープシーケンスを使って簡単に表せます。次のとおりです。

^X     ('X' & 037)     コントロール X
\b, \B  (ASCII 010)     バックスペース
\t, \T  (ASCII 011)     タブ
\n, \N  (ASCII 012)     ラインフィード(改行)
\f, \F  (ASCII 014)     フォームフィード
\r, \R  (ASCII 015)     キャリッジリターン
\e, \E  (ASCII 027)     エスケープ
\c, \C  (:)     コロン
\\      (\)     バックスラッシュ
\^      (^)     キャレット
\nnn    (ASCII 8進数 nnn)

`\ の後に最大 3 桁の 8 進数を続ければ、特定キャラクタの数値コードを直接指定することができます。ただし、エンコードは簡単でも ASCII NUL を多用すると、あらゆる問題の原因となる可能性があります。 NUL はふつうストリングの終わりを示しますから、使用に当たっては注意が必要です。多くのアプリケーションで、 NUL を表すのに `\200' が使用されています。

索引

診断

Fn Cgetent , Fn cgetset , Fn cgetmatch , Fn cgetnum , Fn cgetstr , Fn cgetustr , Fn cgetfirst , および Fn cgetnext などは、いずれも成功した場合は 0またはそれを上回る価を返し、失敗した場合は 0を下回る値を返します。 Fn cgetcap 関数の場合は、成功するとキャラクタポインタを、失敗すると NULL を返します。

Fn cgetent および Fn cgetseq 関数の失敗では、 errno が、ほかのライブラリ関数 fopen(2), close(2), open(2), および close(2) などのエラーに設定される場合があります。

Fn cgetent , Fn cgetset , Fn cgetstr および Fn cgetustr の失敗では、次のエラーに errno が設定される場合があります。