日本語 man コマンド類 (ja-man-1.1j_5) と日本語 man ドキュメント (ja-man-doc-5.4 (5.4-RELEASE 用) など) をインストールすると、以下のような man コマンド閲覧、キーワード検索が コンソールからできるようになります。
4.11-RELEASE-K, 5.4-RELEASE-K, 5.5-RELEASE-K, 6.0-RELEASE-K から 6.4-RELEASE-K, 7.0-RELEASE-K から 7.4-RELEASE-K, 8.0-RELEASE-K から 8.4-RELEASE-K, 9.0-RELEASE-K から 9.3-RELEASE-K, 10.0-RELEASE-K から 10.3-RELEASE-K, 11.0-RELEASE-K から 11.4-RELEASE-K, 12.0-RELEASE-K, 12.1-RELEASE-K は、 プライベート版 (小金丸が編集してまとめたもの) ですが、 より多くの翻訳したファイルが含まれています。 (5.4-RELEASE-K から 6.4-RELEASE-K, 7.0-RELEASE-K から 7.4-RELEASE-K, 8.0-RELEASE-K から 8.4-RELEASE-K, 9.0-RELEASE-K から 9.3-RELEASE-K, 10.0-RELEASE-K から 10.3-RELEASE-K, 11.0-RELEASE-K から 11.4-RELEASE-K, 12.0-RELEASE-K から 12.3-RELEASE-K, 13.0-RELEASE-K から 13.2-RELEASE-K は、全翻訳済み)
13.3-STABLE-K, 15.0-CURRENT-K は現在、作成中で日々更新されています。
Table of Contents
GETCAP(3) FreeBSD ライブラリ関数マニュアル GETCAP(3)
名称
cgetent, cgetset, cgetmatch, cgetcap, cgetnum, cgetstr, cgetustr,
cgetfirst, cgetnext, cgetclose -- ケーパビリティデータベースのアクセス
ルーチン
ライブラリ
標準 C ライブラリ (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() 関数は、ASCII ファイル
にアクセスする前に、.db (cap_mkdb(1) を参照) で終わるファイルを最初に検索
します。buf 引数は、cgetmatch(), cgetcap(), cgetnum(), cgetstr() と
cgetustr() へのすべてのその後の呼び出しを通して保持されなければなりません
が、その後 free(3) で解放されます。成功すると、0 が返され、返されたレコー
ドが未解決の tc 拡張を含んでいるなら、1 が返され、要求されたレコードが見
つけられないなら、-1 が返され、また (ファイルをオープン/読み込みできな
かった、など) システムエラーに遭遇したなら、errno を設定して、-2 が返さ
れ、そして潜在的な参照ループが検出されるなら (以下の tc= のコメントを参
照) 3 が返されます。
cgetset() 関数は、ケーパビリティデータベースへの単一のケーパビリティレ
コードのエントリを含んでいる文字バッファの追加を有効にします。概念的に、
エントリは、データベースの最初の ``ファイル'' として追加され、したがっ
て、cgetent() への呼び出しで最初に検索されます。エントリは、ent に渡され
ます。ent が NULL であるなら、現在のエントリは、データベースから削除され
ます。cgetset() への呼び出しは、データベースの横断に先行しなければなりま
せん。それは、cgetent() 呼び出しの前に呼び出されなければなりません。シー
ケンシャルアクセスが実行されている (下記参照) なら、それは、最初のシーケ
ンシャルアクセス呼び出しの前に (cgetfirst() または cgetnext())、または
cgetclose() 呼び出しに直接先行して呼び出されなければなりません。成功すれ
ば、0 が返され、失敗すれば、-1 が返されます。
cgetmatch() 関数は、name がケーパビリティレコード buf の名前の 1 つである
なら、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 が返され、潜在的な参照ループが検出されるなら (下
記の tc= コメントを参照)、-2 が返されます。データベースの完了 (0 返り) に
おいて、データベースは、クロースされます。
cgetclose() 関数は、シーケンシャルアクセスをクローズして、使用されている
あらゆるメモリとファイル記述子を解放します。cgetset() への呼び出しによっ
てプッシュされたバッファを削除しないことに注意してください。
ケーパビリティデータベースの構文
ケーパビリティデータベースは、通常 ASCII であり、標準のテキストエディタに
よって編集することができます。空行と `#' で始まる行は、コメントであり、無
視されます。`\' で終わる行は、次の行が現在の行の継続であることを示しま
す。`\' と続く改行は、無視されます。長い行は、通常、最後を除いて `\' をつ
けて各行を終ることによっていくつかの物理的な行を継続します。
ケーパビリティデータベースは、論理的な行ごとに 1 つの一連のレコードから成
ます。各レコードは、可変の数の `:' で区切られたフィールド (ケーパビリ
ティ) を含んでいます。空白類文字 (空白とタブ) のすべてから成る空のフィー
ルドは、無視されます。
各レコードの最初のケーパビリティは、`|' 文字によって区切られる、(複数の)
名前を指定します。これらの名前は、データベースの参照レコードに使用されま
す。慣例によって、最後の名前は、通常コメントであり、検索タグとして意図さ
れません。例えば、termcap(5) データベースの vt100 レコードは、次で始まり
ます:
d0|vt100|vt100-am|vt100am|dec vt100:
レコードにアクセスするために使用することができる 4 つの名前を与えます。
残りの空でないケーパビリティは、タイプされた値がオプションで続いている名
前から成る、バインディングのセット (名前、値) を記述しています:
name タイプのない [ブール値] のケーパビリティの名前は、存在します
[真]
nameTvalue ケーパビリティ (名前, T) には、value があります
name@ ケーパビリティのない名前は、存在します
nameT@ ケーパビリティ (名前, T) は、存在しません
名前は、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@ は、見られることから old のあらゆる who-cares 定義の定義を防止
し、glork#200 は、old から継承され、blah とレコード拡張によって定義された
ものは、old のそれらの定義に追加されます。ここで、tc=old の前の fript=bar
と 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() 関数は、失敗し、次のライブラリ関数に対して指定され
たエラーのいずれかを errno に設定します: fopen(3), fclose(3), open(2) と
close(2)。
cgetent(), cgetset(), cgetstr() と cgetustr() 関数は、失敗して、次のよう
に errno を設定します:
[ENOMEM] 割り付ける無メモリがありません。
関連項目
cap_mkdb(1), malloc(3)
バグ
コロン (`:') は、名前、タイプまたは値で使用することはできません。
cgetent() の tc=name ループのチェックは、ありません。
cgetset() への呼び出しによってデータベースに追加されたバッファは、データ
ベースにユニークではありませんが、むしろ、使用されたあらゆるデータベース
の前に付け加えられます。
FreeBSD 11.2 March 22, 2002 FreeBSD 11.2