diff options
Diffstat (limited to 'documentation/manual-pages/ja/man3/getcap.3')
| -rw-r--r-- | documentation/manual-pages/ja/man3/getcap.3 | 505 |
1 files changed, 505 insertions, 0 deletions
diff --git a/documentation/manual-pages/ja/man3/getcap.3 b/documentation/manual-pages/ja/man3/getcap.3 new file mode 100644 index 0000000000..c4871a4204 --- /dev/null +++ b/documentation/manual-pages/ja/man3/getcap.3 @@ -0,0 +1,505 @@ +.\" 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 +の呼び出しによってバッファをデータベースに追加することは、このデータベー +スに限りませんが、ほかの使用データベースに追加する場合は、後ではなく前 +に付加する方が無難です。 |