EN JA
GETCAP(3)
GETCAP(3) FreeBSD Library Functions Manual GETCAP(3)

名称

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

ライブラリ

Standard C Library (libc, -lc)

書式

#include < stdlib.h>

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

int
cgetset( const char *ent);

int
cgetmatch( const char *buf, const char *name);

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

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

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

int
cgetustr( char *buf, const 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 を抽出し、それをコピーした malloc(3) で割り付けた領域のポインタを buf に返します。 cgetent() 関数は、アスキーファイルにアクセスする前に .db ( cap_mkdb(1) を参照) で終わるファイルを最初に探します。 buf 引数は、 cgetmatch(), cgetcap(), cgetnum(), cgetstr() と cgetustr() へのすべてのそれに続く呼び出しを通して保持されなければならないが、その後 free(3) で解放できます。成功すれば 0 が返されます。返されたレコードが未決着の tc 拡張を含んでいるなら、1 が返されます。要求されたレコードを見つけることができなかったなら、-1 が返されます。 (ファイルをオープンできない、読み込みできない、など) システムエラーに遭遇したなら errno を設定して、-2 が返されます。そして、潜在的な参照がループが検知されるなら (下記の tc= 解説を参照) -3 が返されます。

cgetset() 関数は、ケーパビリティデータベースへの一つのケーパビリティレコードエントリを含んでいる文字バッファの追加を可能にします。概念的に、エントリは、データベースに最初の ``ファイル'' として加えられ、そのため cgetent() への呼び出しの最初に検索されます。エントリは、 ent に渡されます。 entNULL である場合、現在のエントリは、データベースから取り除かれます。 cgetset() への呼び出しは、データベース横断に先行しなければなりません。それは、 cgetent() 呼び出しの前に呼ばれなければなりません。シーケンシャルアクセスが実行されている場合 (以下を参照)、それは、最初のシーケンシャルアクセス呼び出し ( cgetfirst() または cgetnext()) の前に呼び出さなければなりません。あるいは、 cgetclose() 呼び出しに直接先行しなければなりません。成功した場合 0 が返され、失敗した場合-1 が返されます。

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

cgetcap() 関数は、タイプ type でケーパビリティ cap を求めてケーパビリティレコード buf を検索します。 type は、任意の単一の文字を使用して指定されます。コロン (`:') が使用される場合、タイプされていないケーパビリティは、検索されるでしょう (タイプの説明に関しては、下記を参照)。成功した場合 buf 中の cap の値へのポインタが返されます。要求されたケーパビリティを見つけることができなかった場合 NULL が返されます。ケーパビリティ値の終了は、`:' または ASCII NUL で示されます (ケーパビリティデータベースの構文については、下記を参照)。

cgetnum() 関数、 buf によって指されるケーパビリティレコードから数値のケーパビリティ cap の値を検索し (取り出し) ます。数値は、 num によって指される long で返されます。成功したなら、0 が返されます。要求された数値ケーパビリティを見つけることができなかった場合-1 が返されます。

cgetstr() 関数は、 buf によって指されるケーパビリティレコードから文字列のケーパビリティ cap の値を検索し (取り出し) ます。ポインタは、デコードされ、ヌル文字で終了した文字列の malloc(3) されたコピーは、 str によって指される char * で返されます。成功すれば、後続するヌル文字を含まない、デコード (解読) された文字列の文字数が返されます。要求された文字列ケーパビリティを見つけることができなかった場合-1 が返されます。システムエラーに遭遇した場合 (記憶割り付け失敗) -2 が返されます。

特別の文字を拡張しないという点を除いて、 cgetustr() 関数は、 cgetstr() と同一です。むしろ、ケーパビリティ文字列の各文字を文字通りに返します。

cgetfirst() と cgetnext() 関数は、 db_array ファイル名の NULL ポインタで終了した配列のシーケンシャルアクセスのために提供される関数グループを含みます。 cgetfirst() 関数は、データベース中の最初のレコードを返し、最初のレコードへのアクセスをリセットします。 cgetnext() 関数は、前の cgetfirst() か cgetnext() 呼び出しによって返されたレコードに関してデータベース中の次のレコードを返します。そのような前の呼び出しがない場合、データベース中の最初のレコードが返されます。各レコードは、 buf によって指される malloc(3) された領域にコピーして返されます。 tc の拡張が行なわれます (下記の tc= 解説を参照)。データベースの終了で 0 が返されます。たぶんレコードがまだ残っていて、 (データベースの終りにまだ到着していない) 成功して返れば 1 が返されます。レコードが未決着の tc 拡張を含んでいる場合、2 が返されます。システムエラーが生じた場合、-1 が返されます。また、潜在的な参照のループが検出された場合、-2 が返されます (下記の tc= 解説を参照)。データベースが終了した (0 の返り) 場合、データベースは、クローズされます。

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

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

ケーパビリティデータベースは、通常 ASCII で、標準のテキストエディタで編集できます。ブランク (空白) の行と `#' で始まる行は、コメントで無視されます。 `\' で終わる行は、次の行が現在の行の継続であることを示します。そして、`\' と次の改行は、無視されます。長い行は、普通、いくつかの物理的な行で継続され、最後の行を除いて各行末に `\' がつけられます。

ケーパビリティデータベースは、論理的な行について一つの一連のレコードから成ります。各レコードは、可変数の `:' で分離されたフィールド (ケーパビリティ) を含んでいます。全てが空白類文字 (スペースとタブ) から成る空のフィールドは、無視されます。

各レコードの最初のケーパビリティは、`|' 文字で分離された名前 (複数) を指定します。これらの名前は、データベースの中で参照レコードとして使用されます。慣例によって、最後の名前は、通常コメントで検索タグとして意図されません。例えば、 termcap(5) データベースからの vt100 レコードは、次のように始まります。

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

この例は、レコードにアクセスするために使用することができる 4 つの名前が与えられています。

残る空でないケーパビリティは、次のように、名前とオプションで後に続くタイプ値からなる (名前、値) 結合セットについて記述します:

name
タイプのない [ブール] ケーパビリティ name は、存在します [真]
name Tvalue
ケーパビリティ ( name, T) には値 value があります
name@
ケーパビリティなし name 存在します
name T@
ケーパビリティ ( name, T) は、存在しません

名前は、1 文字以上から成ります。名前は、`:' を除く、どんな文字も含むことができます。しかし、印刷可能な文字に制限して、`#', `=', `%', `@', その他のようなグラフィックス文字の使用を避けることが通常は、最良です。タイプは、それらに関連するタイプ値からケーパビリティ名を分けるために使用される単一の文字です。タイプは、`:' を除く任意の文字を使用できます。一般的に、`#', `=', `%', その他のようなグラフィックス文字が使用されます。値は、任意の文字数を使用でき、`:' を除くどんな文字も含むことができます。

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

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

タイプ `#' と `=' は、従来通りに数値と文字列タイプ値を示すために使われます。しかし、それらのタイプに対する制限は、強制されません。関数 cgetnum() と cgetstr() は、`#' と `=' の従来の構文および意味論を実装するために使用できます。タイプのないケーパビリティは、真と偽の値をそれぞれ示す存在あるいは不在でブールオブジェクトを示すために典型的に使用されます。この解釈は、次のように便利に表わされます。

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

特別のケーパビリティ tc= name は、 name (名前) によって指定されたレコードが tc ケーパビリティに置き換えるべきであることを示すために使用されます。 tc ケーパビリティは、さらに tc ケーパビリティを含んでいるレコードを差し挟むことができます。また、2 つ以上の tc ケーパビリティをレコードの中で使用できます。 tc 拡張範囲 (すなわち引数が検索される場合) は、 tc が宣言されるファイルとファイル配列中のすべての後続のファイルを含んでいます。

データベースがケーパビリティレコードを検索される場合、検索での最初に一致するレコードが返されます。レコードがケーパビリティのためにスキャンされる場合、最初に一致するケーパビリティが返されます。ケーパビリティ :nameT@: は、 name に対してタイプ T の値のどんな後に続く定義も隠します。またケーパビリティ :name@: は、 name のどんな後に続く値も見つからないように抑制します。

tc ケーパビリティと結びつけられたこれらの特徴は、新しいケーパビリティを加えるか、新しい定義で定義を上書きするか、 `@' ケーパビリティによって後に続く定義を隠すことのいずれかにより、他のデータベースとレコードの変化させるために使用できます。

使用例

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

ケーパビリティ foo は、それ (タイプ `%' の bar とタイプ `^' の blah) に 2 つの値を結合させます。また、他の値の結合も隠されます。ケーパビリティ 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 中のケーパビリティレコード new では、 fript=bar は、file2 中のケーパビリティレコード old から差し挟まれた fript=foo の定義を上書きします。 who-cares@ は、任意の who-cares 定義の定義を見つからないように抑制します。 glork#200 は、old から継承されます。また、blah とレコード拡張によって定義されたものは、old の中のそれらの定義に加えられます。 fript=bar と tc=old の前の who-cares@ の定義の位置は、ここで重要であることに注意してください。もしそれらが後にあれば、old 中の定義は、先行されます。

CGETNUM と CGETSTR の構文と意味論

2 つのタイプが cgetnum() と cgetstr() によってあらかじめ定義されます:

name# number
数値ケーパビリティ name には、値 number があります
name= string
文字列ケーパビリティ name には、値 string があります
name#@
数値ケーパビリティ name は、存在しません
name=@
文字列ケーパビリティ name は、存在しません

数値のケーパビリティ値は、3 つの基数のうちの 1 つで与えられることができます。数が‘ 0x’または‘ 0X’のいずれかで始まる場合、それは、16 進数として解釈されます (大文字小文字の両方の a-f は、拡張した 16 進数を示すために使用できます)。そうでなければ、数が‘ 0’で始まる場合、それは、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' を使用します。

診断

cgetent(), cgetset(), cgetmatch(), cgetnum(), cgetstr(), cgetustr(), cgetfirst() と cgetnext() 関数は、成功すれば 0 以上の値を返します。そして、失敗すれば 0 未満の値を返します。 cgetcap() 関数は、成功すれば文字ポインタを返します。そして、失敗すれば NULL を返します。

cgetent() と cgetset() 関数が失敗する場合、ライブラリ関数 fopen(3), fclose(3), open(2)close(2) で明記されたエラーのいずれかが errno に設定されます。

cgetent(), cgetset(), cgetstr() と cgetustr() 関数は、失敗した場合、次のように errno を設定します。

[ ENOMEM]
割り付けるメモリがありません。

関連項目

cap_mkdb(1), malloc(3)

バグ

コロン (`:') は、名前、タイプまたは値で使用することができません。

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

cgetset() への呼び出しによってデータベースに加えられたバッファは、データベースに固有ではありませんが、むしろ使用される任意のデータベースの先頭に追加されます。

March 22, 2002 FreeBSD