.\" @(#)xdr.3n  2.2 88/08/03 4.0 RPCSRC; from 1.16 88/03/14 SMI
.\" $Id: xdr.3,v 1.5 2004-07-11 11:15:52 metal Exp $
.\"
.\" $FreeBSD$
.TH XDR 3 "16 February 1988"
.SH 名称
xdr \- 外部データ表現のライブラリルーチン
.SH 書式および解説
.LP
これらのルーチンによって、C プログラマは任意のデータ構造をマシン独立
に記述することができます。リモートプロシージャコール用の
データは、これらのルーチンを使って送信されます。
.LP
.ft B
.nf
.sp .5
xdr_array(xdrs, arrp, sizep, maxsize, elsize, elproc)
\s-1XDR\s0 *xdrs;
char **arrp;
u_int *sizep, maxsize, elsize;
xdrproc_t elproc;
.fi
.ft R
.IP
可変長配列とそれに対応する外部表現とを相互に変換する
フィルタプリミティブです。パラメータ
.I arrp
は配列へのポインタのアドレス、
.I sizep
は配列の要素カウントのアドレスであり、この要素カウントは
.I maxsize
を超えることはできません。パラメータ
.I elsize
は各配列要素の
.I sizeof
の値であり、
.I elproc
は配列要素の C 形式と外部表現とを相互に変換する
.SM XDR
フィルタです。このルーチンは、成功すれば 1
を、失敗すれば 0 を返します。
.br
.if t .ne 8
.LP
.ft B
.nf
.sp .5
xdr_bool(xdrs, bp)
\s-1XDR\s0 *xdrs;
bool_t *bp;
.fi
.ft R
.IP
ブール値 (C 言語整数) とその外部表現とを相互に変換する
フィルタプリミティブです。データをコード化するときは、このフィルタは 1
または 0 の値を作り出します。このルーチンは、成功すれば 1 を、失敗すれば
0 を返します。
.br
.if t .ne 10
.LP
.ft B
.nf
.sp .5
xdr_bytes(xdrs, sp, sizep, maxsize)
\s-1XDR\s0 *xdrs;
char **sp;
u_int *sizep, maxsize;
.fi
.ft R
.IP
カウントしたバイトストリングとその外部表現とを相互に変換する
フィルタプリミティブです。パラメータ
.I sp
はストリングポインタのアドレス
です。ストリングの長さはアドレス
.I sizep
に置かれ、ストリングの長さは
.I maxsize
よりも長くなることはできません。このルーチンは、成功すれば 1 を、
失敗すれば 0 を返します。
.br
.if t .ne 7
.LP
.ft B
.nf
.sp .5
xdr_char(xdrs, cp)
\s-1XDR\s0 *xdrs;
char *cp;
.fi
.ft R
.IP
C 言語のキャラクタとその外部表現とを相互に変換するフィルタプリミティブ
です。このルーチンは、成功すれば 1 を、失敗すれば 0 を返します。
注：コード化されたキャラクタは圧縮されず、それぞれは 4 バイトを
占有します。キャラクタの配列については、
.BR xdr_bytes(\|) ,
.BR xdr_opaque(\|) ,
.B xdr_string(\|)
を使うことを考える価値があります。
.br
.if t .ne 8
.LP
.ft B
.nf
.sp .5
void
xdr_destroy(xdrs)
\s-1XDR\s0 *xdrs;
.fi
.ft R
.IP
.SM XDR
ストリーム
.I xdrs
に結合された破壊ルーチンを呼び出すマクロです。破壊とは、通常は
そのストリームに結合されたプライベートデータ構造を解放することを
意味します。
.B xdr_destroy(\|)
を呼び出した後で
.I xdrs
を使うことは、未定義です。
.br
.if t .ne 7
.LP
.ft B
.nf
.sp .5
xdr_double(xdrs, dp)
\s-1XDR\s0 *xdrs;
double *dp;
.fi
.ft R
.IP
C 言語の倍精度数 (
.B double
) とその外部表現とを相互に変換する
フィルタプリミティブです。このルーチンは、成功すれば 1 を、
失敗すれば 0 を返します。
.br
.if t .ne 7
.LP
.ft B
.nf
.sp .5
xdr_enum(xdrs, ep)
\s-1XDR\s0 *xdrs;
enum_t *ep;
.fi
.ft R
.IP
C 言語の
.B enum
(実際は整数) とその外部表現とを相互に変換する
フィルタプリミティブです。このルーチンは、成功すれば 1 を、
失敗すれば 0 を返します。
.br
.if t .ne 8
.LP
.ft B
.nf
.sp .5
xdr_float(xdrs, fp)
\s-1XDR\s0 *xdrs;
float *fp;
.fi
.ft R
.IP
C 言語の
.B float
とその外部表現とを相互に変換する
フィルタプリミティブです。このルーチンは、成功すれば 1 を、
失敗すれば 0 を返します。
.br
.if t .ne 9
.LP
.ft B
.nf
.sp .5
void
xdr_free(proc, objp)
xdrproc_t proc;
char *objp;
.fi
.ft R
.IP
ジェネリックな解放ルーチンです。最初の引数は、解放するオブジェクトの
.SM XDR
ルーチンです。2 番目の引数は、そのオブジェクト自体への
ポインタです。注：このルーチンに渡されるポインタは解放されませんが、それが
指すものは解放 (反復的に) されます。
.br
.if t .ne 8
.LP
.ft B
.nf
.sp .5
u_int
xdr_getpos(xdrs)
\s-1XDR\s0 *xdrs;
.fi
.ft R
.IP
.SM XDR
ストリーム
.I xdrs
に結合された位置検索ルーチンを呼び出すマクロです。このルーチンは、
.SM XDR
バイトストリームの位置を示す符号なしの整数を返します。
.SM XDR
ストリームのよいところは、
.SM XDR
ストリームインスタンスがそれを保証しているとは限らない場合であっても、
この数字に対して簡単な算術計算が使えることです。
.br
.if t .ne 4
.LP
.ft B
.nf
.sp .5
.br
long *
xdr_inline(xdrs, len)
\s-1XDR\s0 *xdrs;
int len;
.fi
.ft R
.IP
.SM XDR
ストリーム
.I xdrs
に結合されたインラインルーチンを呼び出すマクロです。このルーチンは、
ストリームのバッファの連続した部分へのポインタを返します。
.I len
は、希望するバッファのバイト長です。注：ポインタは
.B "long *"
にキャストされます。
.IP
警告:
.B xdr_inline(\|)
は、連続するバッファの部分を割り当てられない場合は、
.SM NULL
(0) を返すことがあります。従って、ストリームインスタンスによって
挙動が異なる場合があります。このルーチンは、効率を上げるために
用意されています。
.br
.if t .ne 7
.LP
.ft B
.nf
.sp .5
xdr_int(xdrs, ip)
\s-1XDR\s0 *xdrs;
int *ip;
.fi
.ft R
.IP
C 言語の整数とその外部表現とを相互に変換するフィルタプリミティブ
です。このルーチンは、成功すれば 1 を、失敗すれば 0 を返します。
.br
.if t .ne 7
.LP
.ft B
.nf
.sp .5
xdr_long(xdrs, lp)
\s-1XDR\s0 *xdrs;
long *lp;
.fi
.ft R
.IP
C 言語
の長整数 (
.B long
) とその外部表現とを相互に変換するフィルタプリミティブです。
このルーチンは、成功すれば 1 を、失敗すれば 0 を返します。
.br
.if t .ne 12
.LP
.ft B
.nf
.sp .5
void
xdrmem_create(xdrs, addr, size, op)
\s-1XDR\s0 *xdrs;
char *addr;
u_int size;
enum xdr_op op;
.fi
.ft R
.IP
このルーチンは、
.I xdrs
によって指される
.SM XDR
ストリームオブジェクトを初期化します。ストリームのデータは、長さが
.I size
バイトを超えない
.I addr
の位置にあるメモリに書込まれるか、またはそこから読み出されます。
.I op
は、
.SM XDR
ストリームの方向 (
.BR \s-1XDR_ENCODE\s0 ,
.BR \s-1XDR_DECODE\s0 ,
.B \s-1XDR_FREE\s0
のいずれか) を決定します。
.br
.if t .ne 10
.LP
.ft B
.nf
.sp .5
xdr_opaque(xdrs, cp, cnt)
\s-1XDR\s0 *xdrs;
char *cp;
u_int cnt;
.fi
.ft R
.IP
固定サイズの不透明 (opaque) データとその外部表現とを相互に変換する
フィルタプリミティブです。パラメータ
.I cp
は不透明データのアドレスであり、
.I cnt
はそのサイズをバイトで表したものです。このルーチンは、
成功すれば 1 を、失敗すれば 0 を返します。
.br
.if t .ne 10
.LP
.ft B
.nf
.sp .5
xdr_pointer(xdrs, objpp, objsize, xdrobj)
\s-1XDR\s0 *xdrs;
char **objpp;
u_int objsize;
xdrproc_t xdrobj;
.fi
.ft R
.IP
.B xdr_reference(\|)
と同じ働きをします。但し、このルーチンが
.SM NULL
ポインタをシリアル化するのに対して、
.B xdr_reference(\|)
はシリアル化しません。
従って、
.B xdr_pointer(\|)
はバイナリツリーやリンクリストのような反復的データ構造を
表すことができます。
.br
.if t .ne 15
.LP
.ft B
.nf
.sp .5
void
xdrrec_create(xdrs, sendsize, recvsize, handle, readit, writeit)
\s-1XDR\s0 *xdrs;
u_int sendsize, recvsize;
char *handle;
int (*readit) (\|), (*writeit) (\|);
.fi
.ft R
.IP
このルーチンは、
.I xdrs
によって指される
.SM XDR
ストリームオブジェクトを初期化します。ストリームのデータはサイズ
.I sendsize
のバッファに書込まれ、値 0 はシステムが適切なデフォルトを使う
必要があることを示します。ストリームのデータは、サイズ
.I recvsize
のバッファから読み込まれ、このルーチンも値 0 を渡すことによって
適切なデフォルトを設定することができます。ストリームの出力バッファが
一杯のときは、
.I writeit
が呼ばれます。同様に、ストリームの入力バッファが空のときは、
.I readit
が呼ばれます。これらの 2 つのルーチンの挙動は、システムコール
.BR read ,
.B write
と似ています。但し、
.B read
には最初のパラメータとして
.I handle
が渡されることが異なります。注:
.SM XDR
ストリームの
.I op
フィールドは、呼び出し元が設定しなければなりません。
.IP
警告: この
.SM XDR
ストリームは、中間レコードストリームを実装しています。
従って、ストリームにはレコードの境界情報を与える追加バイトが入っています。
.br
.if t .ne 9
.LP
.ft B
.nf
.sp .5
xdrrec_endofrecord(xdrs, sendnow)
\s-1XDR\s0 *xdrs;
int sendnow;
.fi
.ft R
.IP
このルーチンは、
.B xdrrec_create(\|)
によって作成されたストリームについてのみ呼び出すことができます。
出力バッファにあるデータは完全なレコードとしてマークされ、
出力バッファは
.I sendnow
が 0 でない場合はオプションで書き出されます。
このルーチンは、成功すれば 1 を、失敗すれば 0 を返します。
.br
.if t .ne 8
.LP
.ft B
.nf
.sp .5
xdrrec_eof(xdrs)
\s-1XDR\s0 *xdrs;
int empty;
.fi
.ft R
.IP
このルーチンは、
.B xdrrec_create(\|)
によって作成されたストリームについてのみ呼び出すことができます。
ストリーム中の現在のレコードの残りの部分を処理した後に、
このルーチンはストリームにそれ以上の入力がない場合は 1 を返し、
ある場合は 0 を返します。
.br
.if t .ne 3
.LP
.ft B
.nf
.sp .5
xdrrec_skiprecord(xdrs)
\s-1XDR\s0 *xdrs;
.fi
.ft R
.IP
このルーチンは、
.B xdrrec_create(\|)
によって作成されたストリームについてのみ呼び出すことができます。
これは、
.SM XDR
のインプリメンテーションに対して、
ストリームの入力バッファにある現在のレコードの残りの部分を
廃棄するように指示します。
このルーチンは、成功すれば 1 を、失敗すれば 0 を返します。
.br
.if t .ne 11
.LP
.ft B
.nf
.sp .5
xdr_reference(xdrs, pp, size, proc)
\s-1XDR\s0 *xdrs;
char **pp;
u_int size;
xdrproc_t proc;
.fi
.ft R
.IP
構造体の中を追いかけるポインタを与えるプリミティブです。
パラメータ
.I pp
はポインタのアドレス、
.I size
は
.I *pp
が指す構造体のサイズ、
.I proc
は構造体をその C 言語形式と外部表現との間でフィルタする
.SM XDR
プロシージャです。
このルーチンは、成功すれば 1 を、失敗すれば 0 を返します。
.IP
警告: このルーチンは　
.SM NULL
ポインタを理解しません。代りに
.B xdr_pointer(\|)
を使ってください。
.br
.if t .ne 10
.LP
.ft B
.nf
.sp .5
xdr_setpos(xdrs, pos)
\s-1XDR\s0 *xdrs;
u_int pos;
.fi
.ft R
.IP
.SM XDR
ストリーム
.I xdrs
に結合された位置設定ルーチンを呼び出すマクロです。
パラメータ
.I pos
は、
.B xdr_getpos(\|)
から取得した位置を示す値です。このルーチンは、
.SM XDR
ストリームの位置を再設定できる場合は 1 を、そうでない
場合は 0 を返します。
.IP
警告:
.SM XDR
ストリームの種類によっては、再設定は困難です。
従って、このルーチンはある種類のストリームには成功し、別の種類のストリーム
には失敗する場合があります。
.br
.if t .ne 8
.LP
.ft B
.nf
.sp .5
xdr_short(xdrs, sp)
\s-1XDR\s0 *xdrs;
short *sp;
.fi
.ft R
.IP
C 言語の短整数 (
.B short
) とその外部表現とを相互に変換するフィルタプリミティブです。
このルーチンは、成功すれば 1 を、失敗すれば 0 を返します。
.br
.if t .ne 10
.LP
.ft B
.nf
.sp .5
void
xdrstdio_create(xdrs, file, op)
\s-1XDR\s0 *xdrs;
\s-1FILE\s0 *file;
enum xdr_op op;
.fi
.ft R
.IP
このルーチンは、
.I xdrs
によって指される
.SM XDR
ストリームオブジェクトを初期化します。
.SM XDR
ストリームデータは、標準
.B I/O
ストリーム
.I file
に書込まれるか、またはそこから読み出されます。パラメータ
.I op
は、
.SM XDR
ストリームの方向 (
.BR \s-1XDR_ENCODE\s0 ,
.BR \s-1XDR_DECODE\s0 ,
.B \s-1XDR_FREE\s0
か) を決定します。
.IP
警告: このような
.SM XDR
ストリームに結合された破壊ルーチンは、
.I file
ストリームについて
.B fflush(\|)
は呼び出しますが、
.B fclose(\|)
は決して呼び出しません。
.br
.if t .ne 9
.LP
.ft B
.nf
.sp .5
xdr_string(xdrs, sp, maxsize)
\s-1XDR\s0
*xdrs;
char **sp;
u_int maxsize;
.fi
.ft R
.IP
C 言語の文字列とそれに対応する外部表現とを相互に変換する
フィルタプリミティブです。文字列の長さは
.I maxsize
を超えることはできません。注:
.I sp
は、ストリングのポインタのアドレスです。
このルーチンは、成功すれば 1 を、失敗すれば 0 を返します。
.br
.if t .ne 8
.LP
.ft B
.nf
.sp .5
xdr_u_char(xdrs, ucp)
\s-1XDR\s0 *xdrs;
unsigned char *ucp;
.fi
.ft R
.IP
符号なしの C 言語のキャラクタとその外部表現とを相互に変換する
フィルタプリミティブです。このルーチンは、成功すれば 1 を、
失敗すれば 0 を返します。
.br
.if t .ne 9
.LP
.ft B
.nf
.sp .5
xdr_u_int(xdrs, up)
\s-1XDR\s0 *xdrs;
unsigned *up;
.fi
.ft R
.IP
C 言語の符号なし整数 (
.B unsigned
) とその外部表現とを相互に変換するフィルタプリミティブです。
このルーチンは成功すれば 1 を、失敗すれば 0 を返します。
.br
.if t .ne 7
.LP
.ft B
.nf
.sp .5
xdr_u_long(xdrs, ulp)
\s-1XDR\s0 *xdrs;
unsigned long *ulp;
.fi
.ft R
.IP
C 言語の符号なし長整数 (
.B "unsigned long"
) とその外部表現とを相互に変換するフィルタプリミティブです。
このルーチンは、成功すれば 1 を、失敗すれば 0 を返します。
.br
.if t .ne 7
.LP
.ft B
.nf
.sp .5
xdr_u_short(xdrs, usp)
\s-1XDR\s0 *xdrs;
unsigned short *usp;
.fi
.ft R
.IP
C 言語の符号なし短整数 (
.B "unsigned short"
) とその外部表現とを相互に変換するフィルタプリミティブです。
このルーチンは、成功すれば 1 を、失敗すれば 0 を返します。
.br
.if t .ne 16
.LP
.ft B
.nf
.sp .5
xdr_union(xdrs, dscmp, unp, choices, dfault)
\s-1XDR\s0 *xdrs;
int *dscmp;
char *unp;
struct xdr_discrim *choices;
bool_t (*defaultarm) (\|);  /* may equal \s-1NULL\s0 */
.fi
.ft R
.IP
ディスクリミナントで識別された C 言語の共用体 (
.B union
) とそれに対応する外部表現とを相互に変換する
フィルタプリミティブです。まず最初に
.I dscmp
に位置するその共用体のディスクリミナントを翻訳します。
このディスクリミナントは、常に
.B enum_t
です。次に、
.I unp
に位置する共用体が翻訳されます。パラメータ
.I choices
は、
.B xdr_discrim(\|)
構造体の配列へのポインタです。各構造には、順序付きペアの
.RI [ value , proc ]
が入っています。共用体のディスクリミナントが結合された
.I value
に等しい場合は、
.I proc
が呼び出されてその共用体を翻訳します。
.B xdr_discrim(\|)
構造体配列の最後は、値
.SM NULL\s0
のルーチンによって印がつけられます。
配列
.I choices
にディスクリミナントが見つからない場合は、
.I defaultarm
プロシージャが呼び出されます (このプロシージャが
.SM NULL\s0
でないならば)。それに成功すれば 1 を、失敗すれば 0 を返します。
.br
.if t .ne 6
.LP
.ft B
.nf
.sp .5
xdr_vector(xdrs, arrp, size, elsize, elproc)
\s-1XDR\s0 *xdrs;
char *arrp;
u_int size, elsize;
xdrproc_t elproc;
.fi
.ft R
.IP
固定長配列とそれに対応する外部表現とを相互に変換する
フィルタプリミティブです。パラメータ
.I arrp
は、その配列へのポインタのアドレス、
.I size
は配列の要素数です。パラメータ
.I elsize
は配列の各要素のサイズ、
.I elproc
は配列要素の C 言語形式とその外部表現とを相互に翻訳する
.SM XDR
フィルタです。このルーチンは、成功すれば 1 を、失敗すれば 0 を返します。
.br
.if t .ne 5
.LP
.ft B
.nf
.sp .5
xdr_void(\|)
.fi
.ft R
.IP
このルーチンは常に 1 を返します。これは、関数パラメータを
必要とするが何もしない
.SM RPC
ルーチンに渡すことができます。
.br
.if t .ne 10
.LP
.ft B
.nf
.sp .5
xdr_wrapstring(xdrs, sp)
\s-1XDR\s0 *xdrs;
char **sp;
.fi
.ft R
.IP
.B "xdr_string(xdrs, sp, \s-1MAXUN.UNSIGNED\s0 );"
を呼び出すプリミティブで、
.SM MAXUN.UNSIGNED
は符号なし整数の最大値です。
.SM RPC
パッケージが最大で 2 つの
.SM XDR
ルーチンをパラメータとして渡しますが、
最も頻繁に使用されるプリミティブであるにもかかわらず
.B xdr_string(\|)
は 3 つのルーチンを必要とするため、
.B xdr_wrapstring(\|)
は大変便利です。成功すれば 1 を、失敗すれば 0 を返します。
.SH 参照
.BR rpc (3)
.LP
次のマニュアルを参照してください。
.RS
.ft I
eXternal Data Representation Standard: Protocol Specification
.br
eXternal Data Representation: Sun Technical Notes
.ft R
.br
.IR "\s-1XDR\s0: External Data Representation Standard" ,
.SM RFC1014, Sun Microsystems, Inc.,
.SM USC-ISI\s0