cgetfirst(3)

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

#include <stdlib.h>

int

cgetent(char **buf, char **db_array, char *name);

int

cgetset(char *ent);

int

cgetmatch(char *buf, char *name);

char *

cgetcap(char *buf, char *cap, int type);

int

cgetnum(char *buf, char *cap, long *num);

int

cgetstr(char *buf, char *cap, char **str);

int

cgetustr(char *buf, char *cap, char **str);

int

cgetfirst(char **buf, char **db_array);

int

cgetnext(char **buf, char **db_array);

int

cgetclose(void);

解説

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

タイプ ‘#’ および ‘=’ は慣用で、数値およびストリングタイプ指定の値を示し ますが、これらのタイプのそうした用途限定は強制的なものではありません。関 数 cgetnum() および 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で cgetent() を呼び出し ます。それによって file1 の新ケーパビリティレコード fript=bar が、file2 の旧ケーパビリティレコードから補間された fript=foo を上書きします。ま た、who-cares@ が旧レコードにあるすべての who-cares 定義を不可視にしま す。さらに、glork#200 が旧レコードから持ち越され、 blah および、このレ コードの拡張によって定義された一切が旧レコード内のそれら定義に追加されま す。ここでは、tc=old の前に fript=bar および who-cares@ の定義を置くこと が重要です。それらの定義を tc=old の後に置いた場合は、旧レコードの定義が 優先されます。

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

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

数値ケーパビリティ値は、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 進数を続ければ、特定キャラクタの数値コードを直接指 定することができます。ただし、エンコードは簡単でも ASCIINULを多用すると、 あらゆる問題の原因となる可能性があります。 NULはふつうストリングの終わり を示しますから、使用に当たっては注意が必要です。多くのアプリケーション で、 NULを表すのに ‘\200’ が使用されています。

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

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

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

割り振るメモリがありません。

関連項目

cap_mkdb(1),malloc(3)

コロン (‘:’) が、名前、タイプ、値に使用できません。

cgetent()に、 tc=nameループのチェックがありません。

cgetset()の呼び出しによってバッファをデータベースに追加することは、この データベースに限りませんが、ほかの使用データベースに追加する場合は、後で はなく前に付加する方が無難です。

FreeBSD 10.0 May 13, 1994 FreeBSD 10.0