XDR - Linux手册页

时间:2019-08-20 18:01:44  来源:igfitidea点击:

Linux程序员手册 第3部分
更新日期: 2017-09-15

名称

xdr-用于外部数据表示的库例程

SYNOPSIS AND DESCRIPTION

这些例程允许C程序员以独立于机器的方式描述任意数据结构。使用这些例程传输用于远程过程调用的数据。

以下原型在中声明,并使用以下类型:

typedef int bool_t;

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

有关XDR类型的声明,请参见。

bool_t xdr_array(XDR *xdrs, char **arrp, unsigned int *sizep,
                 unsigned int maxsize, unsigned int elsize,
                 xdrproc_t elproc);
在可变长度数组及其对应的外部表示之间转换的过滤器原语。 arrp参数是指向数组的指针的地址,而sizep是数组的元素计数的地址;此元素数不能超过maxsize。参数elsize是数组每个元素的大小,而elproc是一个XDR过滤器,它在数组元素的C形式与其外部表示之间进行转换。如果成功,此例程将返回1,否则返回0。
bool_t xdr_bool(XDR *xdrs, bool_t *bp);
在布尔值(C整数)及其外部表示之间转换的过滤器原语。在对数据进行编码时,此过滤器产生的值为一或零。如果成功,此例程将返回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字符及其外部表示之间转换的过滤器原语。如果成功,此例程将返回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个双精度数字及其外部表示之间转换的过滤器原语。如果成功,此例程将返回1,否则返回0。
bool_t xdr_enum(XDR *xdrs, enum_t *ep);
在C枚举(实际上是整数)与其外部表示之间转换的过滤器原语。如果成功,此例程将返回1,否则返回0。
bool_t xdr_float(XDR *xdrs, float *fp);
在C float和它们的外部表示之间转换的过滤器原语。如果成功,此例程将返回1,否则返回0。
void xdr_free(xdrproc_t proc, char *objp);
通用的释放例程。第一个参数是要释放的对象的XDR例程。第二个参数是指向对象本身的指针。注意:传递给该例程的指针不会释放,但是指向它的指针将被释放(递归)。
unsigned int xdr_getpos(XDR *xdrs);
宏,该宏调用与XDR流xdrs关联的get-position例程。该例程返回一个无符号整数,该整数指示XDR字节流的位置。 XDR流的一个理想功能是,该数字可以使用简单的算术运算,尽管XDR流实例不需要保证这一点。
long *xdr_inline(XDR *xdrs, int len);
宏,它调用与XDR流关联的内联例程xdrs。该例程返回一个指向流缓冲区的连续块的指针。 len是所需缓冲区的字节长度。注意:指针强制转换为long *。
警告:如果xdr_inline()无法分配连续的缓冲区,则可能返回NULL(0)。因此,行为可能在流实例之间有所不同。为了效率而存在。
bool_t xdr_int(XDR *xdrs, int *ip);
一个在C整数及其外部表示之间转换的过滤器原语。如果成功,此例程将返回1,否则返回0。
bool_t xdr_long(XDR *xdrs, long *lp);
在C个长整数及其外部表示之间转换的过滤器原语。如果成功,此例程将返回1,否则返回0。
void xdrmem_create(XDR *xdrs, char *addr, unsigned int size,
                   enum xdr_op op);
此例程初始化xdrs指向的XDR流对象。流的数据被写入或从位置addr处的一块内存中读取,该内存的长度不超过size个字节长。该操作确定XDR流的方向(XDR_ENCODE,XDR_DECODE或XDR_FREE)。
bool_t xdr_opaque(XDR *xdrs, char *cp, unsigned int cnt);
在固定大小的不透明数据与其外部表示之间转换的过滤器原语。参数cp是不透明对象的地址,而cnt是其大小(以字节为单位)。如果成功,此例程将返回1,否则返回0。
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流对象。流的数据写入大小为sendize的缓冲区;零值表示系统应使用适当的默认值。流的数据是从大小为recvsize的缓冲区中读取的;也可以通过传递零值将其设置为合适的默认值。当流的输出缓冲区已满时,将调用writeit。同样,当流的输入缓冲区为空时,将调用readit。这两个例程的行为类似于系统调用read(2)和write(2),不同之处在于将句柄作为第一个参数传递给前一个例程。注意:XDR流的op字段必须由调用方设置。
警告:要读取由此API创建的XDR流,您需要先调用xdrrec_skiprecord(),然后再调用其他XDR API。这将在流中插入其他字节以提供记录边界信息。同样,出于相同原因,使用不同xdr * _create API创建的XDR流也不兼容。
bool_t xdrrec_endofrecord(XDR *xdrs, int sendnow);
该例程只能在xdrrec_create()创建的流上调用。输出缓冲区中的数据被标记为已完成的记录,并且如果sendnow为非零,则可以选择写出输出缓冲区。如果成功,此例程将返回1,否则返回0。
bool_t xdrrec_eof(XDR *xdrs);
该例程只能在xdrrec_create()创建的流上调用。在流中消耗完当前记录的其余部分之后,如果流中没有更多输入,则此例程返回1,否则返回零。
bool_t xdrrec_skiprecord(XDR *xdrs);
该例程只能在xdrrec_create()创建的流上调用。它告诉XDR实现,应丢弃流输入缓冲区中的当前记录的其余部分。如果成功,此例程将返回1,否则返回0。
bool_t xdr_reference(XDR *xdrs, char **pp, unsigned int size,
                     xdrproc_t proc);
提供在结构内追踪指针的原语。参数pp是指针的地址。 size是* pp指向的结构的大小; proc是一个XDR过程,它过滤C形式与其外部表示之间的结构。如果成功,此例程将返回1,否则返回0。
警告:此例程无法理解空指针。使用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个短整数及其外部表示之间转换的过滤器原语。如果成功,此例程将返回1,否则返回0。
void xdrstdio_create(XDR *xdrs, FILE *file, enum xdr_op op);
此例程初始化xdrs指向的XDR流对象。 XDR流数据被写入或从stdio流文件中读取。参数op确定XDR流的方向(XDR_ENCODE,XDR_DECODE或XDR_FREE)。
警告:与此类XDR流关联的销毁例程在文件流上调用fflush(3),但从不调用fclose(3)。
bool_t xdr_string(XDR *xdrs, char **sp, unsigned int maxsize);
在C字符串及其对应的外部表示之间转换的过滤器原语。字符串不能超过maxsize。注意:sp是字符串指针的地址。如果成功,此例程将返回1,否则返回0。
bool_t xdr_u_char(XDR *xdrs, unsigned char *ucp);
在无符号C字符及其外部表示之间转换的过滤器原语。如果成功,此例程将返回1,否则返回0。
bool_t xdr_u_int(XDR *xdrs, unsigned *up);
在C个无符号整数及其外部表示之间转换的过滤器原语。如果成功,此例程将返回1,否则返回0。
bool_t xdr_u_long(XDR *xdrs, unsigned long *ulp);
在C个无符号长整数及其外部表示之间转换的过滤器原语。如果成功,此例程将返回1,否则返回0。
bool_t xdr_u_short(XDR *xdrs, unsigned short *usp);
在C个无符号短整数及其外部表示之间转换的过滤器原语。如果成功,此例程将返回1,否则返回0。
bool_t xdr_union(XDR *xdrs, int *dscmp, char *unp,
                 struct xdr_discrim *choices,
                 xdrproc_t defaultarm);     /* may equal NULL */
在已区分的C联合及其对应的外部表示之间转换的过滤器原语。它首先翻译位于dscmp的联合的判别式。此判别式始终是enum_t。接下来,将翻译位于unp的联合。参数choices是指向xdr_discrim()结构数组的指针。每个结构都包含[value,proc]的有序对。如果联合的判别式等于关联值,则调用proc转换联合。 xdr_discrim()结构数组的末尾由值为NULL的例程表示。如果在choices数组中找不到判别式,则将调用defaultarm过程(如果它不是NULL)。如果成功,则返回1,否则返回0。
bool_t xdr_vector(XDR *xdrs, char *arrp, unsigned int size,
                  unsigned int elsize, xdrproc_t elproc);
在固定长度数组及其对应的外部表示之间转换的过滤器原语。参数arrp是指向数组的指针的地址,而size是数组的元素数。参数elsize是数组每个元素的大小,而elproc是一个XDR过滤器,它在数组元素的C形式与其外部表示之间进行转换。如果成功,此例程将返回1,否则返回0。
bool_t xdr_void(void);
此例程始终返回一个。它可以传递给需要函数参数的RPC例程,而无需执行任何操作。
bool_t xdr_wrapstring(XDR *xdrs, char **sp);
调用xdr_string(xdrs,sp,MAXUN.UNSIGNED)的基元;其中MAXUN.UNSIGNED是无符号整数的最大值。 xdr_wrapstring()很方便,因为RPC程序包最多传递两个XDR例程作为参数,而xdr_string()是最常用的原语之一,则需要三个。如果成功,则返回1,否则返回0。

属性

有关本节中使用的术语的说明,请参见attribute(7)。

InterfaceAttributeValue
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 safetyMT-Safe

另外参见

rpc(3)

以下手册:

外部数据表示标准:协议规范 外部数据表示形式:Sun技术说明 XDR:外部数据表示标准RFC 1014,Sun Microsystems,Inc.,USC-ISI。

出版信息

这个页面是Linux手册页项目5.08版的一部分。有关项目的说明、有关报告错误的信息以及此页面的最新版本,请访问https://www.kernel.org/doc/man-pages/