XDR(3)

名前
xdr - 外部データ表現(XDR)のためのライブラリルーティン

書式と説明
これらのルーティンは C プログラマーがマシン非依存な形式で 任意のデータ構造体を記述することを可能にする。 リモートプロシージャーコールのためのデータはこれらのルーティンを 使用して送信される。

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

        typedef int bool_t;

    typedef bool_t (*xdrproc_t) (XDR *, void *,...);

XDR 型の宣言については、 <rpc/xdr.h> を参照。

bool_t xdr_array(XDR *xdrs, char **arrp, unsigned int *sizep,
                 unsigned int maxsize, unsigned int elsize,
                 xdrproc_t elproc);

    可変長の配列とそれに対応する外部表現とを変換する基本フィルター。 引数 arrp は配列へのポインターのアドレスであり、 sizep は配列の要素数のアドレスである。 これらの要素数は maxsize を超えてはならない。 引数 elsize は各配列の要素の sizeof であり、 elproc は配列要素を C 形式からその外部表現に変換するための XDR フィルターである。 このルーティンは成功した場合には 1 を返す。 失敗した場合にはゼロを返す。

bool_t xdr_bool(XDR *xdrs, bool_t *bp);

    真偽値(C の int)とその外部表現とを変換する基本フィルター。 データをエンコードする時、このフィルターは 1 また 0 の値を生成する。 このルーティンは成功した場合には 1 を返す。 失敗した場合には 0 を返す。

bool_t xdr_bytes(XDR *xdrs, char **sp, unsigned int *sizep,
                 unsigned int maxsize);

    ある長さのバイト文字列とその外部表現とを変換する基本フィルター。 引数 sp は文字列ポインターのアドレスである。文字列の長さは sizep のアドレスに置く。文字列は maxsize より長くてはいけない。 このルーティンは成功した場合には 1 を返す。 失敗した場合には 0 を返す。

bool_t xdr_char(XDR *xdrs, char *cp);

    C の文字(char)とその外部表現との間を変換する基本フィルター。 このルーティンは成功した場合には 1 を返す。 失敗した場合には 0 を返す。 注意: エンコードされたデータは詰め込まれておらず、それぞれ 4 バイトを 占める。文字の配列の場合には xdr_bytes(), xdr_opaque(), xdr_string() などを考慮した方が良い。

void xdr_destroy(XDR *xdrs);

    このマクロは XDR ストリーム xdrs に関連付けられた破壊ルーティンを呼び出す。 破壊には通常、ストリームに関連付けられた私的データ構造体の解放が含まれている。 xdr_destroy() の呼び出しの後に xdrs を使用することは未定義である。

bool_t xdr_double(XDR *xdrs, double *dp);

    C の 倍精度数 (double) とその外部表現との変換を行なう基本フィルター。 このルーティンは成功した場合は 1 を返す。 失敗した場合は 0 を返す。

bool_t xdr_enum(XDR *xdrs, enum_t *ep);

    C の enum (実際には int)とその外部表現との変換を行なう基本フィルター。 このルーティンは成功した場合は 1 を返す。 失敗した場合は 0 を返す。

bool_t xdr_float(XDR *xdrs, float *fp);

    C の 浮動小数点数 (float) とその外部表現との変換を行なう基本フィルター。 このルーティンは成功した場合は 1 を返す。 失敗した場合は 0 を返す。

void xdr_free(xdrproc_t proc, char *objp);

    汎用解放(free)ルーティン。最初の引数はオブジェクトを解放するための XDR ルーティンである。二番目の引数はそのオブジェクト自身へのポインター である。注意: このルーティンに渡されるポインターは 解放されない が、このポインターの指すデータは(再帰的に) 解放される。

unsigned int xdr_getpos(XDR *xdrs);

    このマクロは XDR ストリーム xdrs に関連付けられた位置取得ルーティンを呼び出す。 このルーティンは XDR バイトストリームの位置を指示する符号無し整数を返す。 XDR ストリームの機能としてこの数値で単純な算術作業ができることが 期待されてるいる。しかしながら XDR ストリームの実体はこれを保証する必要はない。

long *xdr_inline(XDR *xdrs, int len);

    このマクロは XDR ストリーム xdrs に関連付けられた内部(inline)ルーティンを呼び出す。 ルーティンはストリームのバッファーの連続する断片へのポインターを返す。 len は要求するバッファーのバイト長である。 注意: ポインターは long * にキャストされる。

    警告: xdr_inline() はバッファーの連続する断片を割り当てることができなかった場合には NULL (0)を返すかもしれない。 どの場合もその動作はストリームの実体によって変化するかもしれない。 これは効率化のために存在している。

bool_t xdr_int(XDR *xdrs, int *ip);

    C の整数(int)とその外部表現とを変換するための基本フィルター。 このルーティンは成功した場合は 1 を返す。 失敗した場合はゼロを返す。

bool_t xdr_long(XDR *xdrs, long *lp);

    C の long 整数とそのその外部表現とを変換するための基本フィルター。 このルーティンは成功した場合は 1 を返す。 失敗した場合はゼロを返す。

void xdrmem_create(XDR *xdrs, char *addr, unsigned int size,
                   enum xdr_op op);

    このルーティンは xdrs によって指されている XDR ストリームオブジェクトを初期化する。 ストリームのデータは addr 位置にあるメモリーの塊から読み書きされる。 その長さはバイト単位で size 超えてはいけない。 op は XDR ストリームの変換方向を決定する (XDR_ENCODE, XDR_DECODE, XDR_FREE のどれか)。

bool_t xdr_opaque(XDR *xdrs, char *cp, unsigned int cnt);

    固定長の不明データとその外部表現との変換を行なう基本フィルター。 引数 cp は不明オブジェクトのアドレスであり cnt はそのバイト単位の大きさである。 このルーティンは成功した場合は 1 を返す。 失敗した場合はゼロを返す。

bool_t xdr_pointer(XDR *xdrs, char **objpp,
                   unsigned int objsize, xdrproc_t xdrobj);

    xdr_reference() と同様であるが、これがヌルポインターを番号化するのに対して xdr_reference() はそうしない点が異なっている。これにより、 xdr_pointer() は二分木や連結リストのような再帰的なデータ構造体を 表現できる。

void xdrrec_create(XDR *xdrs, unsigned int sendsize,
                   unsigned int recvsize, char *handle,
                   int (*readit) (char *, char *, int),
                   int (*writeit) (char *, char *, int));

    このルーティンは xdrs で指された XDR ストリームオブジェクトを初期化する。 ストリームのデータは大きさ sendsize のバッファーへ書き込まれる。 sendsize をゼロにすると、システムに適切なデフォルトを使用するように指示する。 ストリームのデータは大きさ recvsize のバッファーから読み込まれる。これもゼロを渡すことで適切なデフォルトに 設定することができる。 ストリームの出力バッファーが一杯の場合は writeit が呼び出される。同様にストリーム入力バッファーが空の場合には readit が呼び出される。これらの二つのルーティンの動作はシステムコールの read(2) や write(2) と似ているが、前者のルーティンは最初の引数として handle が渡される点で異なっている。 注意: XDR ストリームの op は呼び出し側で設定しなければならない。

    警告: この API で作成された XDR ストリームから読み出すには、他の XDR API を呼び出す前に、まず最初に xdrrec_skiprecord() を呼び出す必要がある。この呼び出しは、レコード境界の情報を提供するためにストリームに追加のバイトを挿入する。また、同じ理由で、別の xdr*_create API で作成された XDR ストリームとは互換性がない。

bool_t xdrrec_endofrecord(XDR *xdrs, int sendnow);

    このルーティンは xdrrec_create() によって作成されたストリームに対してのみ呼び出すことができる。 出力バッファーのデータは完全なレコードとして印され、 sendnow がゼロでない場合には出力バッファーは書き出される。 このルーティンは成功した場合は 1 を返す。失敗した場合はゼロを返す。

bool_t xdrrec_eof(XDR *xdrs);

    このルーティンは xdrrec_create() によって作成されたストリームに対してのみ呼び出すことができる。 ストリームの現在のレコードの残りを消費した後に、 ストリームに入力が残っていない場合には 1 を返す。 それ以外の場合はゼロを返す。

bool_t xdrrec_skiprecord(XDR *xdrs);

    このルーティンは xdrrec_create() によって作成されたストリームに対してのみ呼び出すことができる。 XDR の実装にそのストリームの入力バッファーの現在のレコードの残りを 捨てるように伝える。このルーティンは成功した場合は 1 を返す。 失敗した場合はゼロを返す。

bool_t xdr_reference(XDR *xdrs, char **pp, unsigned int size,
                     xdrproc_t proc);

    構造体へのポインター追跡を提供する基本ルーティン。 引数 pp はポインターのアドレスである。 size は *pp が指している構造体の sizeof である。 proc はその構造体の C 形式と外部表現との変換を行なう XDR プロシージャーである。 このルーティンは成功した場合 1 を返す。 失敗した場合はゼロを返す。

    警告: このルーティンはヌルポインターを理解することができない。かわりに xdr_pointer() を使用すること。

xdr_setpos(XDR *xdrs, unsigned int pos);

    このマクロは XDR ストリーム xdrs に関連付けられた位置設定ルーティンを呼び出す。引数 pos は xdr_getpos() によって取得される位置数値である。 このルーティンは XDR ストリームの位置の変更ができた場合には 1 を返す。 それ以外の場合は 0 を返す。

    警告: ある種の XDR ストリームの場合は位置の変更を行なうことが困難である。 それでこのルーティンはある種のストリームの場合には成功し、別の種類の 場合には失敗するかもしれない。

bool_t xdr_short(XDR *xdrs, short *sp);

    C の short 整数とその外部表現との変換を行なう基本フィルター。 このルーティンは成功すると 1 を返す。 失敗した場合はゼロを返す。

void xdrstdio_create(XDR *xdrs, FILE *file, enum xdr_op op);

    このルーティンは xdrs で指された XDR ストリームオブジェクトを初期化する。 XDR ストリームに読み書きれたデータは stdio ストリーム file が使用される。 op 引数は XDR ストリームの変換方向を決定する (XDR_ENCODE, XDR_DECODE, XDR_FREE のどれか)。

    警告: このような XDR ストリームに関連付けられた破壊ルーティンは file ストリームに対して fflush(3) を呼び出すが fclose(3) を呼び出すことはない。

bool_t xdr_string(XDR *xdrs, char **sp, unsigned int maxsize);

    C の文字列とそれに対応する外部表現とを変換するための基本フィルター。 文字列は maxsize より長くはできない。 注意: sp は文字列へのポインターのアドレスである。 このルーティンは成功した場合は 1 を返す。 失敗した場合はゼロを返す。

bool_t xdr_u_char(XDR *xdrs, unsigned char *ucp);

    C の 符号無し文字 (unsigned char) とその外部表現とを変換する基本フィルター。 このルーティンは成功した場合は 1 を返す。 失敗した場合はゼロを返す。

bool_t xdr_u_int(XDR *xdrs, unsigned *up);

    C の 符号無し整数 (unsigned) とその外部表現を変換するための基本フィルター。 このルーティンは成功した場合は 1 を返す。 失敗した場合はゼロを返す。

bool_t xdr_u_long(XDR *xdrs, unsigned long *ulp);

    C の unsigned long 整数とその外部表現を変換するための基本フィルター。 このルーティンは成功した場合は 1 を返す。 失敗した場合はゼロを返す。

bool_t xdr_u_short(XDR *xdrs, unsigned short *usp);

    C の unsigned short 整数とその外部表現を変換するための基本フィルター。 このルーティンは成功した場合は 1 を返す。 失敗した場合はゼロを返す。

bool_t xdr_union(XDR *xdrs, int *dscmp, char *unp,
                 struct xdr_discrim *choices,
                 xdrproc_t defaultarm);     /* may equal NULL */

    分別可能な C の 共用体 (union) とその外部形式とを変換する基本フィルター。 最初に dscmp として与えられた共用体の分別要素が変換される。 この分別要素は常に enum_t である。 次に unp の位置の共用体が変換される。引数 choices は xdr_discrim() 構造体の配列へのポインターである。各構造体は [value,proc] の順序付きペアを格納している。 もし共用体の分別要素が関連付けられた value と等しい場合には、共用体を変換するために proc が呼び出される。 xdr_discrim() 構造体の配列の最後は、値 NULL のルーティン を指定することで示される。 分別要素が choices 配列の中に見つからなかった場合、 defaultarm が (NULL でなければ) 呼び出される。 成功した場合は 1 を返す。失敗した場合はゼロを返す。

bool_t xdr_vector(XDR *xdrs, char *arrp, unsigned int size,
                  unsigned int elsize, xdrproc_t elproc);

    固定長の配列とそれらが対応する外部表現とを変換する基本フィルター。 引数 arrp は配列へのポインターのアドレスである。一方で size は配列の要素数そのものである。引数 elsize は配列の各要素の sizeof で、 elproc は配列の要素を C 形式からその外部表現へと変換する XDR フィルターである。 このルーティンは成功した場合 1 を返す。 失敗した場合はゼロを返す。

bool_t xdr_void(void);

    このルーティンは常に 1 を返す。 これは何も行なわないが、関数引数が必要な RPC ルーティンに渡すことができる。

bool_t xdr_wrapstring(XDR *xdrs, char **sp);

    xdr_string(xdrs, sp, MAXUN.UNSIGNED ); を呼び出す基本ルーティン。 ここで MAXUN.UNSIGNED は符号無し整数(unsigned int)の最大値である。 xdr_wrapstring() は、 RPC パッケージは二つの XDR ルーティンの最大値を引数として渡すため便利である。 xdr_string() は最も頻繁に利用される基本ルーティンであるが三つを要求する。 成功した場合は 1 を返す、失敗した場合はゼロを返す。

属性
この節で使用されている用語の説明については、 attributes(7) を参照。
インターフェース | 属性 | 値
xdr_array(), xdr_bool(), xdr_bytes(), xdr_char(), xdr_destroy(), xdr_double(), xdr_enum(), xdr_float(), xdr_free(), xdr_getpos(), xdr_inline(), xdr_int(), xdr_long(), xdrmem_create(), xdr_opaque(), xdr_pointer(), xdrrec_create(), xdrrec_eof(), xdrrec_endofrecord(), xdrrec_skiprecord(), xdr_reference(), xdr_setpos(), xdr_short(), xdrstdio_create(), xdr_string(), xdr_u_char(), xdr_u_int(), xdr_u_long(), xdr_u_short(), xdr_union(), xdr_vector(), xdr_void(), xdr_wrapstring() | Thread safety | MT-Safe

関連項目
rpc(3)

以下のマニュアル:
    eXternal Data Representation Standard: Protocol Specification
    eXternal Data Representation: Sun Technical Notes
    XDR: External Data Representation Standard, RFC 1014, Sun Microsystems, Inc., USC-ISI.

この文書について
この man ページは Linux man-pages プロジェクトのリリース 5.10 の一部である。プロジェクトの説明とバグ報告に関する情報は https://www.kernel.org/doc/man-pages/ に書かれている。