release/man3/xdr.3

   1 .\" This page was taken from the 4.4BSD-Lite CDROM (BSD license)
   2 .\"
   3 .\" @(#)xdr.3n  2.2 88/08/03 4.0 RPCSRC; from 1.16 88/03/14 SMI
   4 .\"
   5 .\" 2007-12-30, mtk, Convert function prototypes to modern C syntax
   6 .\"
   7 .\"*******************************************************************
   8 .\"
   9 .\" This file was generated with po4a. Translate the source file.
  10 .\"
  11 .\"*******************************************************************
  12 .TH XDR 3 2007\-12\-30 "" "Linux Programmer's Manual"
  13 .SH 名前
  14 xdr \- 外部データ表現(XDR)のためのライブラリ・ルーティン
  15 .SH 書式と説明
  16 .LP
  17 これらのルーティンは C プログラマーがマシン非依存な形式で 任意のデータ構造体を記述することを可能にする。
  18 リモート・プロシジャ・コールのためのデータはこれらのルーティンを 使用して送信される。
  19
  20 以下に示すプロトタイプ宣言は \fI<rpc/xdr.h>\fP で行われており、その中では次の型が使用される。
  21 .in +4n
  22 .nf
  23
  24 typedef int \fIbool_t\fP;
  25
  26 typedef bool_t (*\fIxdrproc_t\fP) (XDR *, void *,...);
  27 .fi
  28 .in
  29 .LP
  30 \fIXDR\fP 型の宣言については、 \fI<rpc/xdr.h>\fP を参照。
  31 .LP
  32 .nf
  33 \fBbool_t xdr_array(XDR *\fP\fIxdrs\fP\fB, char **\fP\fIarrp\fP\fB, unsigned int *\fP\fIsizep\fP\fB,\fP
  34 \fB                 unsigned int \fP\fImaxsize\fP\fB, unsigned int \fP\fIelsize\fP\fB,\fP
  35 \fB                 xdrproc_t \fP\fIelproc\fP\fB);\fP
  36 .fi
  37 .IP
  38 可変長の配列とそれに対応する外部表現とを変換する基本フィルター。 引き数 \fIarrp\fP は配列へのポインターのアドレスであり、 \fIsizep\fP
  39 は配列の要素数のアドレスである。 これらの要素数は \fImaxsize\fP を超えてはならない。 引き数 \fIelsize\fP は各配列の要素の
  40 \fIsizeof\fP であり、 \fIelproc\fP は配列要素を C 形式からその外部表現に変換するための XDR フィルターである。
  41 このルーティンは成功した場合には 1 を返す。 失敗した場合にはゼロを返す。
  42 .LP
  43 .nf
  44 \fBbool_t xdr_bool(XDR *\fP\fIxdrs\fP\fB, bool_t *\fP\fIbp\fP\fB);\fP
  45 .fi
  46 .IP
  47 真偽値(C の int)とその外部表現とを変換する基本フィルター。 データをエンコードする時、このフィルターは 1 また 0 の値を生成する。
  48 このルーティンは成功した場合には 1 を返す。 失敗した場合には 0 を返す。
  49 .LP
  50 .nf
  51 \fBbool_t xdr_bytes(XDR *\fP\fIxdrs\fP\fB, char **\fP\fIsp\fP\fB, unsigned int *\fP\fIsizep\fP\fB,\fP
  52 \fB                 unsigned int \fP\fImaxsize\fP\fB);\fP
  53 .fi
  54 .IP
  55 ある長さのバイト文字列とその外部表現とを変換する基本フィルター。 引き数 \fIsp\fP は文字列ポインターのアドレスである。文字列の長さは
  56 \fIsizep\fP のアドレスに置く。文字列は \fImaxsize\fP より長くてはいけない。 このルーティンは成功した場合には 1 を返す。
  57 失敗した場合には 0 を返す。
  58 .LP
  59 .nf
  60 \fBbool_t xdr_char(XDR *\fP\fIxdrs\fP\fB, char *\fP\fIcp\fP\fB);\fP
  61 .fi
  62 .IP
  63 C の文字(char)とその外部表現との間を変換する基本フィルター。 このルーティンは成功した場合には 1 を返す。 失敗した場合には 0 を返す。
  64 注意: エンコードされたデータは詰め込まれておらず、それぞれ 4 バイトを 占める。文字の配列の場合には \fBxdr_bytes\fP(),
  65 \fBxdr_opaque\fP(), \fBxdr_string\fP()  などを考慮した方が良い。
  66 .LP
  67 .nf
  68 \fBvoid xdr_destroy(XDR *\fP\fIxdrs\fP\fB);\fP
  69 .fi
  70 .IP
  71 このマクロは XDR ストリーム \fIxdrs\fP に関連付けられた破壊ルーティンを呼び出す。
  72 破壊には通常、ストリームに関連付けられた私的データ構造体の解放が含まれている。 \fBxdr_destroy\fP()  の呼び出しの後に \fIxdrs\fP
  73 を使用することは未定義である。
  74 .LP
  75 .nf
  76 \fBbool_t xdr_double(XDR *\fP\fIxdrs\fP\fB, double *\fP\fIdp\fP\fB);\fP
  77 .fi
  78 .IP
  79 C の \fI倍精度数 (double)\fP とその外部表現との変換を行なう基本フィルター。 このルーティンは成功した場合は 1 を返す。 失敗した場合は
  80 0 を返す。
  81 .LP
  82 .nf
  83 \fBbool_t xdr_enum(XDR *\fP\fIxdrs\fP\fB, enum_t *\fP\fIep\fP\fB);\fP
  84 .fi
  85 .IP
  86 C の \fIenum\fP (実際には int)とその外部表現との変換を行なう基本フィルター。 このルーティンは成功した場合は 1 を返す。 失敗した場合は
  87 0 を返す。
  88 .LP
  89 .nf
  90 \fBbool_t xdr_float(XDR *\fP\fIxdrs\fP\fB, float *\fP\fIfp\fP\fB);\fP
  91 .fi
  92 .IP
  93 C の \fI浮動小数点数 (float)\fP とその外部表現との変換を行なう基本フィルター。 このルーティンは成功した場合は 1 を返す。 失敗した場合は
  94 0 を返す。
  95 .LP
  96 .nf
  97 \fBvoid xdr_free(xdrproc_t \fP\fIproc\fP\fB, char *\fP\fIobjp\fP\fB);\fP
  98 .fi
  99 .IP
 100 汎用解放(free)ルーティン。最初の引き数はオブジェクトを解放するための XDR ルーティンである。二番目の引き数はそのオブジェクト自身へのポインター
 101 である。注意: このルーティンに渡されるポインターは \fI解放されない\fP が、このポインターの指すデータは(再帰的に)  \fI解放される\fP。
 102 .LP
 103 .nf
 104 \fBunsigned int xdr_getpos(XDR *\fP\fIxdrs\fP\fB);\fP
 105 .fi
 106 .IP
 107 このマクロは XDR ストリーム \fIxdrs\fP に関連付けられた位置取得ルーティンを呼び出す。 このルーティンは XDR
 108 バイト・ストリームの位置を指示する符号無し整数を返す。 XDR ストリームの機能としてこの数値で単純な算術作業ができることが
 109 期待されてるいる。しかしながら XDR ストリームの実体はこれを保証する必要はない。
 110 .LP
 111 .nf
 112 \fBlong *xdr_inline(XDR *\fP\fIxdrs\fP\fB, int \fP\fIlen\fP\fB);\fP
 113 .fi
 114 .IP
 115 このマクロは XDR ストリーム \fIxdrs\fP に関連付けられた内部(inline)ルーティンを呼び出す。
 116 ルーティンはストリームのバッファーの連続する断片へのポインターを返す。 \fIlen\fP は要求するバッファーのバイト長である。 注意: ポインターは
 117 \fIlong *\fP にキャストされる。
 118 .IP
 119 警告: \fBxdr_inline\fP()  はバッファーの連続する断片を割り当てることができなかった場合には NULL (0)を返すかもしれない。
 120 どの場合もその動作はストリームの実体によって変化するかもしれない。 これは効率化のために存在している。
 121 .LP
 122 .nf
 123 \fBbool_t xdr_int(XDR *\fP\fIxdrs\fP\fB, int *\fP\fIip\fP\fB);\fP
 124 .fi
 125 .IP
 126 C の整数(int)とその外部表現とを変換するための基本フィルター。 このルーティンは成功した場合は 1 を返す。 失敗した場合はゼロを返す。
 127 .LP
 128 .nf
 129 \fBbool_t xdr_long(XDR *\fP\fIxdrs\fP\fB, long *\fP\fIlp\fP\fB);\fP
 130 .fi
 131 .IP
 132 C の \fIlong\fP 整数とそのその外部表現とを変換するための基本フィルター。 このルーティンは成功した場合は 1 を返す。
 133 失敗した場合はゼロを返す。
 134 .LP
 135 .nf
 136 \fBvoid xdrmem_create(XDR *\fP\fIxdrs\fP\fB, char *\fP\fIaddr\fP\fB, unsigned int \fP\fIsize\fP\fB,\fP
 137 \fB                   enum xdr_op \fP\fIop\fP\fB);\fP
 138 .fi
 139 .IP
 140 このルーティンは \fIxdrs\fP によって指されている XDR ストリーム・オブジェクトを初期化する。 ストリームのデータは \fIaddr\fP
 141 位置にあるメモリーの塊から読み書きされる。 その長さはバイト単位で \fIsize\fP 超えてはいけない。 \fIop\fP は XDR
 142 ストリームの変換方向を決定する (\fBXDR_ENCODE\fP, \fBXDR_DECODE\fP, \fBXDR_FREE\fP のどれか)。
 143 .LP
 144 .nf
 145 \fBbool_t xdr_opaque(XDR *\fP\fIxdrs\fP\fB, char *\fP\fIcp\fP\fB, unsigned int \fP\fIcnt\fP\fB);\fP
 146 .fi
 147 .IP
 148 固定長の不明データとその外部表現との変換を行なう基本フィルター。 引き数 \fIcp\fP は不明オブジェクトのアドレスであり \fIcnt\fP
 149 はそのバイト単位の大きさである。 このルーティンは成功した場合は 1 を返す。 失敗した場合はゼロを返す。
 150 .LP
 151 .nf
 152 \fBbool_t xdr_pointer(XDR *\fP\fIxdrs\fP\fB, char **\fP\fIobjpp\fP\fB,\fP
 153 \fB                   unsigned int \fP\fIobjsize\fP\fB, xdrproc_t \fP\fIxdrobj\fP\fB);\fP
 154 .fi
 155 .IP
 156 \fBxdr_reference\fP()  と同様であるが、これが NULL ポインターを番号化するのに対して \fBxdr_reference\fP()
 157 はそうしない点が異なっている。これにより、 \fBxdr_pointer\fP()  は二分木や連結リストのような再帰的なデータ構造体を 表現できる。
 158 .LP
 159 .nf
 160 \fBvoid xdrrec_create(XDR *\fP\fIxdrs\fP\fB, unsigned int \fP\fIsendsize\fP\fB,\fP
 161 \fB                   unsigned int \fP\fIrecvsize\fP\fB, char *\fP\fIhandle\fP\fB,\fP
 162 \fB                   int (*\fP\fIreadit\fP\fB) (char *, char *, int),\fP
 163 \fB                   int (*\fP\fIwriteit\fP\fB) (char *, char *, int));\fP
 164 .fi
 165 .IP
 166 このルーティンは \fIxdrs\fP で指された XDR ストリーム・オブジェクトを初期化する。 ストリームのデータは大きさ \fIsendsize\fP
 167 のバッファへ書き込まれる。 \fIsendsize\fP をゼロにすると、システムに適切なデフォルトを使用するように指示する。 ストリームのデータは大きさ
 168 \fIrecvsize\fP のバッファから読み込まれる。これもゼロを渡すことで適切なデフォルトに 設定することができる。
 169 ストリームの出力バッファが一杯の場合は \fIwriteit\fP が呼び出される。同様にストリーム入力バッファが空の場合には \fIreadit\fP
 170 が呼び出される。これらの二つのルーティンの動作はシステムコールの \fBread\fP(2)  や \fBwrite\fP(2)
 171 と似ているが、前者のルーティンは最初の引き数として \fIhandle\fP が渡される点で異なっている。 注意: XDR ストリームの \fIop\fP
 172 は呼び出し側で設定しなければならない。
 173 .IP
 174 警告: この XDR ストリームは中間レコード・ストリームを実装している。 レコード境界の情報を提供するためにストリームには余分なバイトが存在する。
 175 .LP
 176 .nf
 177 \fBbool_t xdrrec_endofrecord(XDR *\fP\fIxdrs\fP\fB, int \fP\fIsendnow\fP\fB);\fP
 178 .fi
 179 .IP
 180 このルーティンは \fBxdrrec_create\fP()  によって作成されたストリームに対してのみ呼び出すことができる。
 181 出力バッファのデータは完全なレコードとして印され、 \fIsendnow\fP がゼロでない場合には出力バッファは書き出される。
 182 このルーティンは成功した場合は 1 を返す。失敗した場合はゼロを返す。
 183 .LP
 184 .nf
 185 \fBbool_t xdrrec_eof(XDR *\fP\fIxdrs\fP\fB);\fP
 186 .fi
 187 .IP
 188 このルーティンは \fBxdrrec_create\fP()  によって作成されたストリームに対してのみ呼び出すことができる。
 189 ストリームの現在のレコードの残りを消費した後に、 ストリームに入力が残っていない場合には 1 を返す。 それ以外の場合はゼロを返す。
 190 .LP
 191 .nf
 192 \fBbool_t xdrrec_skiprecord(XDR *\fP\fIxdrs\fP\fB);\fP
 193 .fi
 194 .IP
 195 このルーティンは \fBxdrrec_create\fP()  によって作成されたストリームに対してのみ呼び出すことができる。 XDR
 196 の実装にそのストリームの入力バッファーの現在のレコードの残りを 捨てるように伝える。このルーティンは成功した場合は 1 を返す。
 197 失敗した場合はゼロを返す。
 198 .LP
 199 .nf
 200 \fBbool_t xdr_reference(XDR *\fP\fIxdrs\fP\fB, char **\fP\fIpp\fP\fB, unsigned int \fP\fIsize\fP\fB,\fP
 201 \fB                     xdrproc_t \fP\fIproc\fP\fB);\fP
 202 .fi
 203 .IP
 204 構造体へのポインター追跡を提供する基本ルーティン。 引き数 \fIpp\fP はポインターのアドレスである。 \fIsize\fP は \fI*pp\fP
 205 が指している構造体の \fIsizeof\fP である。 \fIproc\fP はその構造体の C 形式と外部表現との変換を行なう XDR プロシジャである。
 206 このルーティンは成功した場合 1 を返す。 失敗した場合はゼロを返す。
 207 .IP
 208 警告: このルーティンは NULL ポインターを理解することができない。かわりに \fBxdr_pointer\fP()  を使用すること。
 209 .LP
 210 .nf
 211 \fBxdr_setpos(XDR *\fP\fIxdrs\fP\fB, unsigned int \fP\fIpos\fP\fB);\fP
 212 .fi
 213 .IP
 214 このマクロは XDR ストリーム \fIxdrs\fP に関連付けられた位置設定ルーティンを呼び出す。引き数 \fIpos\fP は \fBxdr_getpos\fP()
 215 によって取得される位置数値である。 このルーティンは XDR ストリームの位置の変更ができた場合には 1 を返す。 それ以外の場合は 0 を返す。
 216 .IP
 217 警告: ある種の XDR ストリームの場合は位置の変更を行なうことが困難である。 それでこのルーティンはある種のストリームの場合には成功し、別の種類の
 218 場合には失敗するかもしれない。
 219 .LP
 220 .nf
 221 \fBbool_t xdr_short(XDR *\fP\fIxdrs\fP\fB, short *\fP\fIsp\fP\fB);\fP
 222 .fi
 223 .IP
 224 C の \fIshort\fP 整数とその外部表現との変換を行なう基本フィルター。 このルーティンは成功すると 1 を返す。 失敗した場合はゼロを返す。
 225 .LP
 226 .nf
 227 \fBvoid xdrstdio_create(XDR *\fP\fIxdrs\fP\fB, FILE *\fP\fIfile\fP\fB, enum xdr_op \fP\fIop\fP\fB);\fP
 228 .fi
 229 .IP
 230 このルーティンは \fIxdrs\fP で指された XDR ストリーム・オブジェクトを初期化する。 XDR ストリームに読み書きれたデータは \fIstdio\fP
 231 ストリーム \fIfile\fP が使用される。 \fIop\fP 引き数は XDR ストリームの変換方向を決定する (\fBXDR_ENCODE\fP,
 232 \fBXDR_DECODE\fP, \fBXDR_FREE\fP のどれか)。
 233 .IP
 234 警告: このような XDR ストリームに関連付けられた破壊ルーティンは \fIfile\fP ストリームに対して \fBfflush\fP(3)  を呼び出すが
 235 \fBfclose\fP(3)  を呼び出すことはない。
 236 .LP
 237 .nf
 238 \fBbool_t xdr_string(XDR *\fP\fIxdrs\fP\fB, char **\fP\fIsp\fP\fB, unsigned int \fP\fImaxsize\fP\fB);\fP
 239 .fi
 240 .IP
 241 C の文字列とそれに対応する外部表現とを変換するための基本フィルター。 文字列は \fImaxsize\fP より長くはできない。 注意: \fIsp\fP
 242 は文字列へのポインターのアドレスである。 このルーティンは成功した場合は 1 を返す。 失敗した場合はゼロを返す。
 243 .LP
 244 .nf
 245 \fBbool_t xdr_u_char(XDR *\fP\fIxdrs\fP\fB, unsigned char *\fP\fIucp\fP\fB);\fP
 246 .fi
 247 .IP
 248 C の \fI符号無し文字 (unsigned char)\fP とその外部表現とを変換する基本フィルター。 このルーティンは成功した場合は 1 を返す。
 249 失敗した場合はゼロを返す。
 250 .LP
 251 .nf
 252 \fBbool_t xdr_u_int(XDR *\fP\fIxdrs\fP\fB, unsigned *\fP\fIup\fP\fB);\fP
 253 .fi
 254 .IP
 255 C の \fI符号無し整数 (unsigned)\fP とその外部表現を変換するための基本フィルター。 このルーティンは成功した場合は 1 を返す。
 256 失敗した場合はゼロを返す。
 257 .LP
 258 .nf
 259 \fBbool_t xdr_u_long(XDR *\fP\fIxdrs\fP\fB, unsigned long *\fP\fIulp\fP\fB);\fP
 260 .fi
 261 .IP
 262 C の \fIunsigned long\fP 整数とその外部表現を変換するための基本フィルター。 このルーティンは成功した場合は 1 を返す。
 263 失敗した場合はゼロを返す。
 264 .LP
 265 .nf
 266 \fBbool_t xdr_u_short(XDR *\fP\fIxdrs\fP\fB, unsigned short *\fP\fIusp\fP\fB);\fP
 267 .fi
 268 .IP
 269 C の \fIunsigned short\fP 整数とその外部表現を変換するための基本フィルター。 このルーティンは成功した場合は 1 を返す。
 270 失敗した場合はゼロを返す。
 271 .LP
 272 .nf
 273 \fBbool_t xdr_union(XDR *\fP\fIxdrs\fP\fB, int *\fP\fIdscmp\fP\fB, char *\fP\fIunp\fP\fB,\fP
 274 \fB                 struct xdr_discrim *\fP\fIchoices\fP\fB,\fP
 275 \fB                 xdrproc_t \fP\fIdefaultarm\fP\fB);     /* may equal NULL */\fP
 276 .fi
 277 .IP
 278 分別可能な C の \fI共用体 (union)\fP とその外部形式とを変換する基本フィルター。 最初に \fIdscmp\fP
 279 として与えられた共用体の分別要素が変換される。 この分別要素は常に \fIenum_t\fP である。 次に \fIunp\fP の位置の共用体が変換される。引き数
 280 \fIchoices\fP は \fBxdr_discrim\fP()  構造体の配列へのポインターである。各構造体は [\fIvalue\fP,\fIproc\fP]
 281 の順序付きペアを格納している。 もし共用体の分別要素が関連付けられた \fIvalue\fP と等しい場合には、共用体を変換するために \fIproc\fP
 282 が呼び出される。 \fBxdr_discrim\fP()  構造体の配列の最後は、値 NULL のルーティン を指定することで示される。 分別要素が
 283 \fIchoices\fP 配列の中に見つからなかった場合、 \fIdefaultarm\fP が (NULL でなければ) 呼び出される。 成功した場合は 1
 284 を返す。失敗した場合はゼロを返す。
 285 .LP
 286 .nf
 287 \fBbool_t xdr_vector(XDR *\fP\fIxdrs\fP\fB, char *\fP\fIarrp\fP\fB, unsigned int \fP\fIsize\fP\fB,\fP
 288 \fB                  unsigned int \fP\fIelsize\fP\fB, xdrproc_t \fP\fIelproc\fP\fB);\fP
 289 .fi
 290 .IP
 291 固定長の配列とそれらが対応する外部表現とを変換する基本フィルター。 引き数 \fIarrp\fP は配列へのポインターのアドレスである。一方で \fIsize\fP
 292 は配列の要素数そのものである。引き数 \fIelsize\fP は配列の各要素の \fIsizeof\fP で、 \fIelproc\fP は配列の要素を C
 293 形式からその外部表現へと変換する XDR フィルターである。 このルーティンは成功した場合 1 を返す。 失敗した場合はゼロを返す。
 294 .LP
 295 .nf
 296 \fBbool_t xdr_void(void);\fP
 297 .fi
 298 .IP
 299 このルーティンは常に 1 を返す。 これは何も行なわないが、関数引き数が必要な RPC ルーティンに渡すことができる。
 300 .LP
 301 .nf
 302 \fBbool_t xdr_wrapstring(XDR *\fP\fIxdrs\fP\fB, char **\fP\fIsp\fP\fB);\fP
 303 .fi
 304 .IP
 305 \fBxdr_string(xdrs, sp, \s-1MAXUN.UNSIGNED\s0 );\fP を呼び出す基本ルーティン。 ここで
 306 \fBMAXUN.UNSIGNED\fP は符号無し整数(unsigned int)の最大値である。 \fBxdr_wrapstring\fP()  は、 RPC
 307 パッケージは二つの XDR ルーティンの最大値を引き数として渡すため便利である。 \fBxdr_string\fP()
 308 は最も頻繁に利用される基本ルーティンであるが三つを要求する。 成功した場合は 1 を返す、失敗した場合はゼロを返す。
 309 .SH 関連項目
 310 \fBrpc\fP(3)
 311 .LP
 312 以下のマニュアル:
 313 .RS
 314 eXternal Data Representation Standard: Protocol Specification
 315 .br
 316 eXternal Data Representation: Sun Technical Notes
 317 .br
 318 \fIXDR: External Data Representation Standard\fP, RFC\ 1014, Sun Microsystems,
 319 Inc., USC\-ISI.
 320 .RE