Update README

[linuxjm/LDP_man-pages.git] / draft / man3 / xdr.3

.\" This page was taken from the 4.4BSD-Lite CDROM (BSD license)
.\"
.\" %%%LICENSE_START(BSD_ONELINE_CDROM)
.\" This page was taken from the 4.4BSD-Lite CDROM (BSD license)
.\" %%%LICENSE_END
.\"
.\" @(#)xdr.3n  2.2 88/08/03 4.0 RPCSRC; from 1.16 88/03/14 SMI
.\"
.\" 2007-12-30, mtk, Convert function prototypes to modern C syntax
.\"
.\"*******************************************************************
.\"
.\" This file was generated with po4a. Translate the source file.
.\"
.\"*******************************************************************
.\"
.\" Japanese Version Copyright (c) 1999 HANATAKA Shinya
.\"         all rights reserved.
.\" Translated Tue Jan  4 20:48:51 JST 2000
.\"         by HANATAKA Shinya <hanataka@abyss.rim.or.jp>
.\"
.TH XDR 3 2007\-12\-30 "" "Linux Programmer's Manual"
.SH 名前
xdr \- 外部データ表現(XDR)のためのライブラリルーティン
.SH 書式と説明
.LP
これらのルーティンは C プログラマーがマシン非依存な形式で 任意のデータ構造体を記述することを可能にする。
リモートプロシージャーコールのためのデータはこれらのルーティンを 使用して送信される。

以下に示すプロトタイプ宣言は \fI<rpc/xdr.h>\fP で行われており、その中では次の型が使用される。
.in +4n
.nf

\fBtypedef int \fP\fIbool_t\fP\fB;\fP

\fBtypedef bool_t (*\fP\fIxdrproc_t\fP\fB) (XDR *, void *,...);\fP
.fi
.in
.LP
\fIXDR\fP 型の宣言については、 \fI<rpc/xdr.h>\fP を参照。
.LP
.nf
\fBbool_t xdr_array(XDR *\fP\fIxdrs\fP\fB, char **\fP\fIarrp\fP\fB, unsigned int *\fP\fIsizep\fP\fB,\fP
\fB                 unsigned int \fP\fImaxsize\fP\fB, unsigned int \fP\fIelsize\fP\fB,\fP
\fB                 xdrproc_t \fP\fIelproc\fP\fB);\fP
.fi
.IP
可変長の配列とそれに対応する外部表現とを変換する基本フィルター。 引き数 \fIarrp\fP は配列へのポインターのアドレスであり、 \fIsizep\fP
は配列の要素数のアドレスである。 これらの要素数は \fImaxsize\fP を超えてはならない。 引き数 \fIelsize\fP は各配列の要素の
\fIsizeof\fP であり、 \fIelproc\fP は配列要素を C 形式からその外部表現に変換するための XDR フィルターである。
このルーティンは成功した場合には 1 を返す。 失敗した場合にはゼロを返す。
.LP
.nf
\fBbool_t xdr_bool(XDR *\fP\fIxdrs\fP\fB, bool_t *\fP\fIbp\fP\fB);\fP
.fi
.IP
真偽値(C の int)とその外部表現とを変換する基本フィルター。 データをエンコードする時、このフィルターは 1 また 0 の値を生成する。
このルーティンは成功した場合には 1 を返す。 失敗した場合には 0 を返す。
.LP
.nf
\fBbool_t xdr_bytes(XDR *\fP\fIxdrs\fP\fB, char **\fP\fIsp\fP\fB, unsigned int *\fP\fIsizep\fP\fB,\fP
\fB                 unsigned int \fP\fImaxsize\fP\fB);\fP
.fi
.IP
ある長さのバイト文字列とその外部表現とを変換する基本フィルター。 引き数 \fIsp\fP は文字列ポインターのアドレスである。文字列の長さは
\fIsizep\fP のアドレスに置く。文字列は \fImaxsize\fP より長くてはいけない。 このルーティンは成功した場合には 1 を返す。
失敗した場合には 0 を返す。
.LP
.nf
\fBbool_t xdr_char(XDR *\fP\fIxdrs\fP\fB, char *\fP\fIcp\fP\fB);\fP
.fi
.IP
C の文字(char)とその外部表現との間を変換する基本フィルター。 このルーティンは成功した場合には 1 を返す。 失敗した場合には 0 を返す。
注意: エンコードされたデータは詰め込まれておらず、それぞれ 4 バイトを 占める。文字の配列の場合には \fBxdr_bytes\fP(),
\fBxdr_opaque\fP(), \fBxdr_string\fP()  などを考慮した方が良い。
.LP
.nf
\fBvoid xdr_destroy(XDR *\fP\fIxdrs\fP\fB);\fP
.fi
.IP
このマクロは XDR ストリーム \fIxdrs\fP に関連付けられた破壊ルーティンを呼び出す。
破壊には通常、ストリームに関連付けられた私的データ構造体の解放が含まれている。 \fBxdr_destroy\fP()  の呼び出しの後に \fIxdrs\fP
を使用することは未定義である。
.LP
.nf
\fBbool_t xdr_double(XDR *\fP\fIxdrs\fP\fB, double *\fP\fIdp\fP\fB);\fP
.fi
.IP
C の \fI倍精度数 (double)\fP とその外部表現との変換を行なう基本フィルター。 このルーティンは成功した場合は 1 を返す。 失敗した場合は
0 を返す。
.LP
.nf
\fBbool_t xdr_enum(XDR *\fP\fIxdrs\fP\fB, enum_t *\fP\fIep\fP\fB);\fP
.fi
.IP
C の \fIenum\fP (実際には int)とその外部表現との変換を行なう基本フィルター。 このルーティンは成功した場合は 1 を返す。 失敗した場合は
0 を返す。
.LP
.nf
\fBbool_t xdr_float(XDR *\fP\fIxdrs\fP\fB, float *\fP\fIfp\fP\fB);\fP
.fi
.IP
C の \fI浮動小数点数 (float)\fP とその外部表現との変換を行なう基本フィルター。 このルーティンは成功した場合は 1 を返す。 失敗した場合は
0 を返す。
.LP
.nf
\fBvoid xdr_free(xdrproc_t \fP\fIproc\fP\fB, char *\fP\fIobjp\fP\fB);\fP
.fi
.IP
汎用解放(free)ルーティン。最初の引き数はオブジェクトを解放するための XDR ルーティンである。二番目の引き数はそのオブジェクト自身へのポインター
である。注意: このルーティンに渡されるポインターは \fI解放されない\fP が、このポインターの指すデータは(再帰的に)  \fI解放される\fP。
.LP
.nf
\fBunsigned int xdr_getpos(XDR *\fP\fIxdrs\fP\fB);\fP
.fi
.IP
このマクロは XDR ストリーム \fIxdrs\fP に関連付けられた位置取得ルーティンを呼び出す。 このルーティンは XDR
バイトストリームの位置を指示する符号無し整数を返す。 XDR ストリームの機能としてこの数値で単純な算術作業ができることが
期待されてるいる。しかしながら XDR ストリームの実体はこれを保証する必要はない。
.LP
.nf
\fBlong *xdr_inline(XDR *\fP\fIxdrs\fP\fB, int \fP\fIlen\fP\fB);\fP
.fi
.IP
このマクロは XDR ストリーム \fIxdrs\fP に関連付けられた内部(inline)ルーティンを呼び出す。
ルーティンはストリームのバッファーの連続する断片へのポインターを返す。 \fIlen\fP は要求するバッファーのバイト長である。 注意: ポインターは
\fIlong\ *\fP にキャストされる。
.IP
警告: \fBxdr_inline\fP()  はバッファーの連続する断片を割り当てることができなかった場合には NULL (0)を返すかもしれない。
どの場合もその動作はストリームの実体によって変化するかもしれない。 これは効率化のために存在している。
.LP
.nf
\fBbool_t xdr_int(XDR *\fP\fIxdrs\fP\fB, int *\fP\fIip\fP\fB);\fP
.fi
.IP
C の整数(int)とその外部表現とを変換するための基本フィルター。 このルーティンは成功した場合は 1 を返す。 失敗した場合はゼロを返す。
.LP
.nf
\fBbool_t xdr_long(XDR *\fP\fIxdrs\fP\fB, long *\fP\fIlp\fP\fB);\fP
.fi
.IP
C の \fIlong\fP 整数とそのその外部表現とを変換するための基本フィルター。 このルーティンは成功した場合は 1 を返す。
失敗した場合はゼロを返す。
.LP
.nf
\fBvoid xdrmem_create(XDR *\fP\fIxdrs\fP\fB, char *\fP\fIaddr\fP\fB, unsigned int \fP\fIsize\fP\fB,\fP
\fB                   enum xdr_op \fP\fIop\fP\fB);\fP
.fi
.IP
このルーティンは \fIxdrs\fP によって指されている XDR ストリームオブジェクトを初期化する。 ストリームのデータは \fIaddr\fP
位置にあるメモリーの塊から読み書きされる。 その長さはバイト単位で \fIsize\fP 超えてはいけない。 \fIop\fP は XDR
ストリームの変換方向を決定する (\fBXDR_ENCODE\fP, \fBXDR_DECODE\fP, \fBXDR_FREE\fP のどれか)。
.LP
.nf
\fBbool_t xdr_opaque(XDR *\fP\fIxdrs\fP\fB, char *\fP\fIcp\fP\fB, unsigned int \fP\fIcnt\fP\fB);\fP
.fi
.IP
固定長の不明データとその外部表現との変換を行なう基本フィルター。 引き数 \fIcp\fP は不明オブジェクトのアドレスであり \fIcnt\fP
はそのバイト単位の大きさである。 このルーティンは成功した場合は 1 を返す。 失敗した場合はゼロを返す。
.LP
.nf
\fBbool_t xdr_pointer(XDR *\fP\fIxdrs\fP\fB, char **\fP\fIobjpp\fP\fB,\fP
\fB                   unsigned int \fP\fIobjsize\fP\fB, xdrproc_t \fP\fIxdrobj\fP\fB);\fP
.fi
.IP
\fBxdr_reference\fP()  と同様であるが、これがヌルポインターを番号化するのに対して \fBxdr_reference\fP()
はそうしない点が異なっている。これにより、 \fBxdr_pointer\fP()  は二分木や連結リストのような再帰的なデータ構造体を 表現できる。
.LP
.nf
\fBvoid xdrrec_create(XDR *\fP\fIxdrs\fP\fB, unsigned int \fP\fIsendsize\fP\fB,\fP
\fB                   unsigned int \fP\fIrecvsize\fP\fB, char *\fP\fIhandle\fP\fB,\fP
\fB                   int (*\fP\fIreadit\fP\fB) (char *, char *, int),\fP
\fB                   int (*\fP\fIwriteit\fP\fB) (char *, char *, int));\fP
.fi
.IP
このルーティンは \fIxdrs\fP で指された XDR ストリームオブジェクトを初期化する。 ストリームのデータは大きさ \fIsendsize\fP
のバッファーへ書き込まれる。 \fIsendsize\fP をゼロにすると、システムに適切なデフォルトを使用するように指示する。 ストリームのデータは大きさ
\fIrecvsize\fP のバッファーから読み込まれる。これもゼロを渡すことで適切なデフォルトに 設定することができる。
ストリームの出力バッファーが一杯の場合は \fIwriteit\fP が呼び出される。同様にストリーム入力バッファーが空の場合には \fIreadit\fP
が呼び出される。これらの二つのルーティンの動作はシステムコールの \fBread\fP(2)  や \fBwrite\fP(2)
と似ているが、前者のルーティンは最初の引き数として \fIhandle\fP が渡される点で異なっている。 注意: XDR ストリームの \fIop\fP
は呼び出し側で設定しなければならない。
.IP
警告: この XDR ストリームは中間レコードストリームを実装している。 レコード境界の情報を提供するためにストリームには余分なバイトが存在する。
.LP
.nf
\fBbool_t xdrrec_endofrecord(XDR *\fP\fIxdrs\fP\fB, int \fP\fIsendnow\fP\fB);\fP
.fi
.IP
このルーティンは \fBxdrrec_create\fP()  によって作成されたストリームに対してのみ呼び出すことができる。
出力バッファーのデータは完全なレコードとして印され、 \fIsendnow\fP がゼロでない場合には出力バッファーは書き出される。
このルーティンは成功した場合は 1 を返す。失敗した場合はゼロを返す。
.LP
.nf
\fBbool_t xdrrec_eof(XDR *\fP\fIxdrs\fP\fB);\fP
.fi
.IP
このルーティンは \fBxdrrec_create\fP()  によって作成されたストリームに対してのみ呼び出すことができる。
ストリームの現在のレコードの残りを消費した後に、 ストリームに入力が残っていない場合には 1 を返す。 それ以外の場合はゼロを返す。
.LP
.nf
\fBbool_t xdrrec_skiprecord(XDR *\fP\fIxdrs\fP\fB);\fP
.fi
.IP
このルーティンは \fBxdrrec_create\fP()  によって作成されたストリームに対してのみ呼び出すことができる。 XDR
の実装にそのストリームの入力バッファーの現在のレコードの残りを 捨てるように伝える。このルーティンは成功した場合は 1 を返す。
失敗した場合はゼロを返す。
.LP
.nf
\fBbool_t xdr_reference(XDR *\fP\fIxdrs\fP\fB, char **\fP\fIpp\fP\fB, unsigned int \fP\fIsize\fP\fB,\fP
\fB                     xdrproc_t \fP\fIproc\fP\fB);\fP
.fi
.IP
構造体へのポインター追跡を提供する基本ルーティン。 引き数 \fIpp\fP はポインターのアドレスである。 \fIsize\fP は \fI*pp\fP
が指している構造体の \fIsizeof\fP である。 \fIproc\fP はその構造体の C 形式と外部表現との変換を行なう XDR プロシージャーである。
このルーティンは成功した場合 1 を返す。 失敗した場合はゼロを返す。
.IP
警告: このルーティンはヌルポインターを理解することができない。かわりに \fBxdr_pointer\fP()  を使用すること。
.LP
.nf
\fBxdr_setpos(XDR *\fP\fIxdrs\fP\fB, unsigned int \fP\fIpos\fP\fB);\fP
.fi
.IP
このマクロは XDR ストリーム \fIxdrs\fP に関連付けられた位置設定ルーティンを呼び出す。引き数 \fIpos\fP は \fBxdr_getpos\fP()
によって取得される位置数値である。 このルーティンは XDR ストリームの位置の変更ができた場合には 1 を返す。 それ以外の場合は 0 を返す。
.IP
警告: ある種の XDR ストリームの場合は位置の変更を行なうことが困難である。 それでこのルーティンはある種のストリームの場合には成功し、別の種類の
場合には失敗するかもしれない。
.LP
.nf
\fBbool_t xdr_short(XDR *\fP\fIxdrs\fP\fB, short *\fP\fIsp\fP\fB);\fP
.fi
.IP
C の \fIshort\fP 整数とその外部表現との変換を行なう基本フィルター。 このルーティンは成功すると 1 を返す。 失敗した場合はゼロを返す。
.LP
.nf
\fBvoid xdrstdio_create(XDR *\fP\fIxdrs\fP\fB, FILE *\fP\fIfile\fP\fB, enum xdr_op \fP\fIop\fP\fB);\fP
.fi
.IP
このルーティンは \fIxdrs\fP で指された XDR ストリームオブジェクトを初期化する。 XDR ストリームに読み書きれたデータは \fIstdio\fP
ストリーム \fIfile\fP が使用される。 \fIop\fP 引き数は XDR ストリームの変換方向を決定する (\fBXDR_ENCODE\fP,
\fBXDR_DECODE\fP, \fBXDR_FREE\fP のどれか)。
.IP
警告: このような XDR ストリームに関連付けられた破壊ルーティンは \fIfile\fP ストリームに対して \fBfflush\fP(3)  を呼び出すが
\fBfclose\fP(3)  を呼び出すことはない。
.LP
.nf
\fBbool_t xdr_string(XDR *\fP\fIxdrs\fP\fB, char **\fP\fIsp\fP\fB, unsigned int \fP\fImaxsize\fP\fB);\fP
.fi
.IP
C の文字列とそれに対応する外部表現とを変換するための基本フィルター。 文字列は \fImaxsize\fP より長くはできない。 注意: \fIsp\fP
は文字列へのポインターのアドレスである。 このルーティンは成功した場合は 1 を返す。 失敗した場合はゼロを返す。
.LP
.nf
\fBbool_t xdr_u_char(XDR *\fP\fIxdrs\fP\fB, unsigned char *\fP\fIucp\fP\fB);\fP
.fi
.IP
C の \fI符号無し文字 (unsigned char)\fP とその外部表現とを変換する基本フィルター。 このルーティンは成功した場合は 1 を返す。
失敗した場合はゼロを返す。
.LP
.nf
\fBbool_t xdr_u_int(XDR *\fP\fIxdrs\fP\fB, unsigned *\fP\fIup\fP\fB);\fP
.fi
.IP
C の \fI符号無し整数 (unsigned)\fP とその外部表現を変換するための基本フィルター。 このルーティンは成功した場合は 1 を返す。
失敗した場合はゼロを返す。
.LP
.nf
\fBbool_t xdr_u_long(XDR *\fP\fIxdrs\fP\fB, unsigned long *\fP\fIulp\fP\fB);\fP
.fi
.IP
C の \fIunsigned long\fP 整数とその外部表現を変換するための基本フィルター。 このルーティンは成功した場合は 1 を返す。
失敗した場合はゼロを返す。
.LP
.nf
\fBbool_t xdr_u_short(XDR *\fP\fIxdrs\fP\fB, unsigned short *\fP\fIusp\fP\fB);\fP
.fi
.IP
C の \fIunsigned short\fP 整数とその外部表現を変換するための基本フィルター。 このルーティンは成功した場合は 1 を返す。
失敗した場合はゼロを返す。
.LP
.nf
\fBbool_t xdr_union(XDR *\fP\fIxdrs\fP\fB, int *\fP\fIdscmp\fP\fB, char *\fP\fIunp\fP\fB,\fP
\fB                 struct xdr_discrim *\fP\fIchoices\fP\fB,\fP
\fB                 xdrproc_t \fP\fIdefaultarm\fP\fB);     /* may equal NULL */\fP
.fi
.IP
分別可能な C の \fI共用体 (union)\fP とその外部形式とを変換する基本フィルター。 最初に \fIdscmp\fP
として与えられた共用体の分別要素が変換される。 この分別要素は常に \fIenum_t\fP である。 次に \fIunp\fP の位置の共用体が変換される。引き数
\fIchoices\fP は \fBxdr_discrim\fP()  構造体の配列へのポインターである。各構造体は [\fIvalue\fP,\fIproc\fP]
の順序付きペアを格納している。 もし共用体の分別要素が関連付けられた \fIvalue\fP と等しい場合には、共用体を変換するために \fIproc\fP
が呼び出される。 \fBxdr_discrim\fP()  構造体の配列の最後は、値 NULL のルーティン を指定することで示される。 分別要素が
\fIchoices\fP 配列の中に見つからなかった場合、 \fIdefaultarm\fP が (NULL でなければ) 呼び出される。 成功した場合は 1
を返す。失敗した場合はゼロを返す。
.LP
.nf
\fBbool_t xdr_vector(XDR *\fP\fIxdrs\fP\fB, char *\fP\fIarrp\fP\fB, unsigned int \fP\fIsize\fP\fB,\fP
\fB                  unsigned int \fP\fIelsize\fP\fB, xdrproc_t \fP\fIelproc\fP\fB);\fP
.fi
.IP
固定長の配列とそれらが対応する外部表現とを変換する基本フィルター。 引き数 \fIarrp\fP は配列へのポインターのアドレスである。一方で \fIsize\fP
は配列の要素数そのものである。引き数 \fIelsize\fP は配列の各要素の \fIsizeof\fP で、 \fIelproc\fP は配列の要素を C
形式からその外部表現へと変換する XDR フィルターである。 このルーティンは成功した場合 1 を返す。 失敗した場合はゼロを返す。
.LP
.nf
\fBbool_t xdr_void(void);\fP
.fi
.IP
このルーティンは常に 1 を返す。 これは何も行なわないが、関数引き数が必要な RPC ルーティンに渡すことができる。
.LP
.nf
\fBbool_t xdr_wrapstring(XDR *\fP\fIxdrs\fP\fB, char **\fP\fIsp\fP\fB);\fP
.fi
.IP
\fBxdr_string(xdrs, sp, \s-1MAXUN.UNSIGNED\s0 );\fP を呼び出す基本ルーティン。 ここで
\fBMAXUN.UNSIGNED\fP は符号無し整数(unsigned int)の最大値である。 \fBxdr_wrapstring\fP()  は、 RPC
パッケージは二つの XDR ルーティンの最大値を引き数として渡すため便利である。 \fBxdr_string\fP()
は最も頻繁に利用される基本ルーティンであるが三つを要求する。 成功した場合は 1 を返す、失敗した場合はゼロを返す。
.SH 関連項目
\fBrpc\fP(3)
.LP
以下のマニュアル:
.RS
eXternal Data Representation Standard: Protocol Specification
.br
eXternal Data Representation: Sun Technical Notes
.br
\fIXDR: External Data Representation Standard\fP, RFC\ 1014, Sun Microsystems,
Inc., USC\-ISI.
.RE
.SH この文書について
この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.79 の一部
である。プロジェクトの説明とバグ報告に関する情報は
http://www.kernel.org/doc/man\-pages/ に書かれている。