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

名称

rpc-远程过程调用的库例程

SYNOPSIS AND DESCRIPTION

这些例程允许C程序在网络上的其他计算机上进行过程调用。首先，客户端调用一个过程以将数据包发送到服务器。收到数据包后，服务器将调用分派例程以执行请求的服务，然后发回回复。最后，过程调用返回到客户端。

要使用这些例程，请包括头文件。

下面的原型使用以下类型：

typedef int bool_t;

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

typedef bool_t (*resultproc_t) (caddr_t resp,
                                struct sockaddr_in *raddr);

有关AUTH，CLIENT，SVCXPRT和XDR类型的声明，请参见头文件。

void auth_destroy(AUTH *auth);

销毁与auth关联的身份验证信息的宏。销毁通常涉及私有数据结构的重新分配。调用auth_destroy()后，尚未定义auth的使用。

AUTH *authnone_create(void);

创建并返回一个RPC身份验证句柄，该句柄在每个远程过程调用中传递不可用的身份验证信息。这是RPC使用的默认身份验证。

AUTH *authunix_create(char *host, int uid, int gid,
                      int len, int *aup_gids);

创建并返回一个包含身份验证信息的RPC身份验证句柄。参数主机是在其上创建信息的计算机的名称； uid是用户的用户标识； gid是用户的当前组ID； len和aup_gids指的是用户所属的一组计数的数组。冒充用户很容易。

AUTH *authunix_create_default(void);

使用适当的参数调用authunix_create()。

int callrpc(char *host, unsigned long prognum,
            unsigned long versnum, unsigned long procnum,
            xdrproc_t inproc, char *in,
            xdrproc_t outproc, char *out);

在计算机，主机上调用与prognum，versnum和procnum关联的远程过程。参数in是过程参数的地址，参数out是将结果放置在何处的地址； inproc用于对过程的参数进行编码，而outproc用于对过程的结果进行解码。如果成功，则此例程返回零；如果失败，则将enum clnt_stat的值强制转换为整数。例程clnt_perrno()可将故障状态转换为消息。

警告：使用此例程调用远程过程将使用UDP / IP作为传输；有关限制，请参见clntudp_create()。您无法使用此例程控制超时或身份验证。

enum clnt_stat clnt_broadcast(unsigned long prognum,
                     unsigned long versnum, unsigned long procnum,
                     xdrproc_t inproc, char *in,
                     xdrproc_t outproc, char *out,
                     resultproc_t eachresult);

像callrpc()一样，只是呼叫消息广播到所有本地连接的广播网。每次收到响应时，此例程都会调用eachresult()，其形式为：

eachresult(char *out, struct sockaddr_in *addr);

out与传递给clnt_broadcast()的out相同，只是远程过程的输出在此处解码。 addr指向发送结果的机器的地址。如果eachresult()返回零，则clnt_broadcast()等待更多答复；否则，它将以适当的状态返回。

警告：广播套接字的大小限制为数据链接的最大传输单位。对于以太网，此值为1500字节。

enum clnt_stat clnt_call(CLIENT *clnt, unsigned long procnum,
                    xdrproc_t inproc, char *in,
                    xdrproc_t outproc, char *out,
                    struct timeval tout);

一个宏，它调用与客户端句柄clnt相关联的远程过程procnum，该宏是通过RPC客户端创建例程(例如clnt_create())获得的。参数in是过程参数的地址，参数out是将结果放置在何处的地址； inproc用于对过程的参数进行编码，而outproc用于对过程的结果进行解码；吹捧是允许结果返回的时间。

clnt_destroy(CLIENT *clnt);

破坏客户端的RPC句柄的宏。销毁通常涉及私有数据结构(包括clnt本身)的重新分配。调用clnt_destroy()后，clnt的使用是不确定的。如果RPC库打开了关联的套接字，它将也将其关闭。否则，插座将保持打开状态。

CLIENT *clnt_create(char *host, unsigned long prog,
                    unsigned long vers, char *proto);

通用客户端创建例程。 host标识服务器所在的远程主机的名称。 proto指示要使用哪种传输协议。该字段当前支持的值为lqudprq和lqtcprq。设置了默认超时，但是可以使用clnt_control()进行修改。

警告：使用UDP有其缺点。由于基于UDP的RPC消息最多只能容纳8 KB的编码数据，因此该传输不能用于带有大参数或返回巨大结果的过程。

bool_t clnt_control(CLIENT *cl, int req, char *info);

用于更改或检索有关客户端对象的各种信息的宏。 req指示操作的类型，而info是指向该信息的指针。对于UDP和TCP，req的支持值及其参数类型及其作用是：

CLSET_TIMEOUT  struct timeval // set total timeout
CLGET_TIMEOUT  struct timeval // get total timeout

注意：如果使用clnt_control()设置超时，则在以后的所有调用中将忽略传递给clnt_call()的timeout参数。

CLGET_SERVER_ADDR  struct sockaddr_in  // get server's address

以下操作仅对UDP有效：

CLSET_RETRY_TIMEOUT  struct timeval // set the retry timeout
CLGET_RETRY_TIMEOUT  struct timeval // get the retry timeout

重试超时是" UDP RPC"在重新传输请求之前等待服务器答复的时间。

clnt_freeres(CLIENT * clnt, xdrproc_t outproc, char *out);

宏，它在解码RPC调用的结果时释放RPC / XDR系统分配的所有数据。参数out是结果的地址，而outproc是描述结果的XDR例程。如果成功释放结果，此例程将返回1，否则返回零。

void clnt_geterr(CLIENT *clnt, struct rpc_err *errp);

将错误结构从客户端句柄复制到地址errp处的宏的宏。

void clnt_pcreateerror(char *s);

将消息打印到标准错误，指示为什么无法创建客户端RPC句柄。该消息以字符串s和冒号开头。当clnt_create()，clntraw_create()，clnttcp_create()或clntudp_create()调用失败时使用。

void clnt_perrno(enum clnt_stat stat);

将消息打印到与stat指示的条件相对应的标准错误。在callrpc()之后使用。

clnt_perror(CLIENT *clnt, char *s);

将消息打印到标准错误，指示RPC调用失败的原因； clnt是用于执行呼叫的句柄。该消息以字符串s和冒号开头。在clnt_call()之后使用。

char *clnt_spcreateerror(char *s);

与clnt_pcreateerror()类似，除了它返回一个字符串而不是打印到标准错误之外。

错误：返回指向每次调用都会被覆盖的静态数据的指针。

char *clnt_sperrno(enum clnt_stat stat);

采用与clnt_perrno()相同的参数，而不是向标准错误发送消息以指示RPC调用失败的原因，而是返回指向包含消息的字符串的指针。字符串以NEWLINE结尾。

如果程序没有标准错误(因为程序很可能没有在服务器上运行)，或者程序员不希望通过printf(3)输出消息，则使用clnt_sperrno()代替clnt_perrno()。 ，或者是否要使用不同于clnt_perrno()支持的消息格式。注意：与clnt_sperror()和clnt_spcreateerror()不同，clnt_sperrno()返回指向静态数据的指针，但结果不会在每次调用时被覆盖。

char *clnt_sperror(CLIENT *rpch, char *s);

像clnt_perror()一样，除了像clnt_sperrno()一样，它返回一个字符串而不是打印到标准错误。

错误：返回指向每次调用都会被覆盖的静态数据的指针。

CLIENT *clntraw_create(unsigned long prognum, unsigned long versnum);

此例程为远程程序版本(版本)创建玩具RPC客户端。用于将消息传递给服务的传输实际上是进程地址空间中的缓冲区，因此相应的RPC服务器应位于相同的地址空间中；参见svcraw_create()。这样可以模拟RPC并获取RPC开销，例如往返时间，而不会受到任何内核干扰。如果该例程失败，则返回NULL。

CLIENT *clnttcp_create(struct sockaddr_in *addr,
                unsigned long prognum, unsigned long versnum,
                int *sockp, unsigned int sendsz, unsigned int recvsz);

该例程为远程程序版本versnum创建RPC客户端。客户端使用TCP / IP作为传输。远程程序位于Internet地址* addr。如果addr->sin_port为零，则将其设置为远程程序正在侦听的实际端口(有关此信息，请参考远程端口映射服务)。参数sockp是一个套接字。如果是RPC_ANYSOCK，则此例程将打开一个新例程并设置sockp。由于基于TCP的RPC使用缓冲的I / O，因此用户可以使用sends和recvsz参数指定发送和接收缓冲区的大小。零值选择合适的默认值。如果该例程失败，则返回NULL。

CLIENT *clntudp_create(struct sockaddr_in *addr,
                unsigned long prognum, unsigned long versnum,
                struct timeval wait, int *sockp);

该例程为远程程序版本versnum创建RPC客户端。客户端使用UDP / IP作为传输。远程程序位于Internet地址addr。如果addr->sin_port为零，则将其设置为远程程序正在侦听的实际端口(有关此信息，请参考远程端口映射服务)。参数sockp是一个套接字。如果是RPC_ANYSOCK，则此例程将打开一个新例程并设置sockp。 UDP传输在等待时间间隔内重新发送呼叫消息，直到收到响应或呼叫超时为止。超时调用的总时间由clnt_call()指定。

警告：由于基于UDP的RPC消息最多只能容纳8 KB的编码数据，因此该传输不能用于带有大参数或返回巨大结果的过程。

CLIENT *clntudp_bufcreate(struct sockaddr_in *addr,
            unsigned long prognum, unsigned long versnum,
            struct timeval wait, int *sockp,
            unsigned int sendsize, unsigned int recosize);

这个例程在versnum上为远程程序prognum创建一个RPC客户端。客户端使用UDP / IP作为传输。远程程序位于Internet地址addr。如果addr->sin_port为零，则将其设置为远程程序正在侦听的实际端口(有关此信息，请参考远程端口映射服务)。参数sockp是一个套接字。如果是RPC_ANYSOCK，则此例程将打开一个新例程并设置sockp。 UDP传输在等待时间间隔内重新发送呼叫消息，直到收到响应或呼叫超时为止。超时调用的总时间由clnt_call()指定。

这使用户可以指定用于发送和接收基于UDP的RPC消息的最大数据包大小。

void get_myaddress(struct sockaddr_in *addr);

将机器的IP地址塞入* addr，而无需咨询处理/ etc / hosts的库例程。端口号始终设置为htons(PMAPPORT)。

struct pmaplist *pmap_getmaps(struct sockaddr_in *addr);

端口映射服务的用户界面，该服务界面返回位于IP地址* addr的主机上当前RPC程序到端口的映射列表。该例程可以返回NULL。命令rpcinfo -p使用此例程。

unsigned short pmap_getport(struct sockaddr_in *addr,
                    unsigned long prognum, unsigned long versnum,
                    unsigned int protocol);

端口映射服务的用户界面，该界面返回端口号，在端口号上等待支持程序号程序版本(版本号)的服务，并说出与协议关联的传输协议。协议的值很可能是IPPROTO_UDP或IPPROTO_TCP。返回值零表示该映射不存在，或者RPC系统无法联系远程端口映射服务。在后一种情况下，全局变量rpc_createerr包含RPC状态。

enum clnt_stat pmap_rmtcall(struct sockaddr_in *addr,
                    unsigned long prognum, unsigned long versnum,
                    unsigned long procnum,
                    xdrproc_t inproc, char *in,
                    xdrproc_t outproc, char *out,
                    struct timeval tout, unsigned long *portp);

portmap服务的用户界面，它指示IP地址为* addr的主机上的portmap代表您对该主机上的过程进行RPC调用。如果过程成功，则参数* portp将被修改为程序的端口号。其他参数的定义在callrpc()和clnt_call()中讨论。此过程应用于lqpingrq而不是其他任何东西。另请参见clnt_broadcast()。

bool_t pmap_set(unsigned long prognum, unsigned long versnum,
                unsigned int protocol, unsigned short port);

portmap服务的用户界面，该界面在三元组[prognum，versnum，protocol]和计算机的portmap服务上的端口之间建立映射。协议的值很可能是IPPROTO_UDP或IPPROTO_TCP。如果成功，此例程将返回1，否则返回0。由svc_register()自动完成。

bool_t pmap_unset(unsigned long prognum, unsigned long versnum);

portmap服务的用户界面，该用户界面破坏了三元组[prognum，versnum，*]与计算机portmap服务上的端口之间的所有映射。如果成功，此例程将返回1，否则返回0。

int registerrpc(unsigned long prognum, unsigned long versnum,
                unsigned long procnum, char *(*procname)(char *),
                xdrproc_t inproc, xdrproc_t outproc);

向RPC服务包注册过程procname。如果对程序prognum，版本versnum和过程procnum的请求到达，则procname会使用指向其参数的指针进行调用； procname应该返回一个指向其静态结果的指针； inproc用于解码参数，而outproc用于编码结果。如果注册成功，则此例程返回零，否则返回-1。

警告：使用UDP / IP传输访问以这种形式注册的远程过程。有关限制，请参见svcudp_create()。

struct rpc_createerr rpc_createerr;

一个全局变量，其值由任何不成功的RPC客户端创建例程设置。使用例程clnt_pcreateerror()打印原因。

void svc_destroy(SVCXPRT *xprt);

破坏RPC服务传输句柄xprt的宏。销毁通常涉及私有数据结构(包括xprt本身)的重新分配。调用此例程后，xprt的使用未定义。

fd_set svc_fdset;

反映RPC服务端读取文件描述符位掩码的全局变量；它适合作为select(2)系统调用的参数。仅当服务实现者执行自己的异步事件处理而不是调用svc_run()时，这才有意义。该变量是只读的(不要将其地址传递给select(2)！)，但是在调用svc_getreqset()或任何创建例程之后，它可能会更改。

int svc_fds;

与svc_fdset相似，但限于32个文件描述符。 svc_fdset已废弃此接口。

svc_freeargs(SVCXPRT *xprt, xdrproc_t inproc, char *in);

当宏使用svc_getargs()解码服务过程的参数时，该宏将释放RPC / XDR系统分配的所有数据。如果成功释放结果，此例程将返回1，否则返回零。

svc_getargs(SVCXPRT *xprt, xdrproc_t inproc, char *in);

宏，用于解码与RPC服务传输句柄xprt关联的RPC请求的参数。 in中的参数是将放置参数的地址； inproc是用于解码参数的XDR例程。如果解码成功，则此例程返回1，否则返回0。

struct sockaddr_in *svc_getcaller(SVCXPRT *xprt);

获得与RPC服务传输句柄xprt相关的过程的调用者的网络地址的批准方法。

void svc_getreqset(fd_set *rdfds);

仅当服务实现者不调用svc_run()而是实现自定义异步事件处理时，此例程才有意义。当select(2)系统调用确定某个RPC套接字上已到达RPC请求时，将调用该方法。 rdfds是结果读取文件描述符位掩码。当与rdfds值关联的所有套接字都得到服务后，该例程返回。

void svc_getreq(int rdfds);

与svc_getreqset()类似，但限于32个文件描述符。 svc_getreqset()废弃了此接口。

bool_t svc_register(SVCXPRT *xprt, unsigned long prognum,
                    unsigned long versnum,
                    void (*dispatch)(svc_req *, SVCXPRT *),
                    unsigned long protocol);

将prognum和versnum与服务分发过程，分发相关联。如果protocol为零，则该服务未在portmap服务中注册。如果协议非零，则使用本地端口映射服务(通常协议为零，IPPROTO_UDP或IPPROTO_TCP)建立三元组[prognum，versnum，protocol]到xprt->xp_port的映射。过程分派具有以下形式：

dispatch(struct svc_req *request, SVCXPRT *xprt);

如果成功，则svc_register()例程返回1，否则返回零。

void svc_run(void);

该例程永远不会返回。它等待RPC请求到达，并在到达时使用svc_getreq()调用适当的服务过程。此过程通常在等待select(2)系统调用返回。

bool_t svc_sendreply(SVCXPRT *xprt, xdrproc_t outproc, char *out);

由RPC服务的分派例程调用，以发送远程过程调用的结果。参数xprt是请求的关联传输句柄； outproc是用于编码结果的XDR例程；结果是地址。如果成功，此例程将返回1，否则返回0。

void svc_unregister(unsigned long prognum, unsigned long versnum);

删除所有双[prognum，versnum]到调度例程的映射，以及所有三元组[prognum，versnum，*]到端口号的映射。

void svcerr_auth(SVCXPRT *xprt, enum auth_stat why);

由服务分派例程调用，由于身份验证错误，该例程拒绝执行远程过程调用。

void svcerr_decode(SVCXPRT *xprt);

由无法成功解码其参数的服务分派例程调用。另请参见svc_getargs()。

void svcerr_noproc(SVCXPRT *xprt);

由服务分派例程调用，该例程没有实现调用方请求的过程号。

void svcerr_noprog(SVCXPRT *xprt);

当所需程序未在RPC软件包中注册时调用。服务实现者通常不需要此例程。

void svcerr_progvers(SVCXPRT *xprt);

当所需的程序版本未在RPC软件包中注册时调用。服务实现者通常不需要此例程。

void svcerr_systemerr(SVCXPRT *xprt);

服务调度例程在检测到任何特定协议未涵盖的系统错误时由服务调用例程调用。例如，如果服务无法再分配存储，则可以调用此例程。

void svcerr_weakauth(SVCXPRT *xprt);

由服务分派例程调用，由于身份验证参数不足，该例程拒绝执行远程过程调用。该例程调用svcerr_auth(xprt，AUTH_TOOWEAK)。

SVCXPRT *svcfd_create(int fd, unsigned int sendsize,
                      unsigned int recvsize);

在任何打开的文件描述符之上创建一个服务。通常，此文件描述符是流协议(如TCP)的连接套接字。 sendize和recvsize指示发送和接收缓冲区的大小。如果它们为零，则选择一个合理的默认值。

SVCXPRT *svcraw_create(void);

此例程创建玩具RPC服务传输，并向其返回指针。传输实际上是进程地址空间内的缓冲区，因此，相应的RPC客户端应位于相同的地址空间中。请参阅clntraw_create()。该例程可以模拟RPC和获取RPC开销(例如往返时间)，而不会受到任何内核干扰。如果该例程失败，则返回NULL。

SVCXPRT *svctcp_create(int sock, unsigned int send_buf_size,
                       unsigned int recv_buf_size);

该例程创建一个基于TCP / IP的RPC服务传输，并向其返回一个指针。传输与套接字套接字(可能是RPC_ANYSOCK)相关联，在这种情况下，将创建一个新的套接字。如果套接字未绑定到本地TCP端口，则此例程将其绑定到任意端口。完成后，xprt->xp_sock是传输的套接字描述符，xprt->xp_port是传输的端口号。如果该例程失败，则返回NULL。由于基于TCP的RPC使用缓冲的I / O，因此用户可以指定缓冲区的大小。零值选择合适的默认值。

SVCXPRT *svcudp_bufcreate(int sock, unsigned int sendsize,
                          unsigned int recosize);

此例程创建基于UDP / IP的RPC服务传输，并向其返回指针。传输与套接字套接字(可能是RPC_ANYSOCK)相关联，在这种情况下，将创建一个新的套接字。如果套接字未绑定到本地UDP端口，则此例程将其绑定到任意端口。完成后，xprt->xp_sock是传输的套接字描述符，xprt->xp_port是传输的端口号。如果该例程失败，则返回NULL。

这使用户可以指定用于发送和接收基于UDP的RPC消息的最大数据包大小。

SVCXPRT *svcudp_create(int sock);

对于某些默认大小SZ，此调用等效于svcudp_bufcreate(sock，SZ，SZ)。

bool_t xdr_accepted_reply(XDR *xdrs, struct accepted_reply *ar);

用于编码RPC回复消息。该例程对于希望在不使用RPC包的情况下生成RPC样式的消息的用户很有用。

bool_t xdr_authunix_parms(XDR *xdrs, struct authunix_parms *aupp);

用于描述UNIX凭据。该例程对于希望在不使用RPC身份验证包的情况下生成这些凭据的用户很有用。

void xdr_callhdr(XDR *xdrs, struct rpc_msg *chdr);

用于描述RPC调用标头消息。该例程对于希望在不使用RPC包的情况下生成RPC样式的消息的用户很有用。

bool_t xdr_callmsg(XDR *xdrs, struct rpc_msg *cmsg);

用于描述RPC调用消息。该例程对于希望在不使用RPC包的情况下生成RPC样式的消息的用户很有用。

bool_t xdr_opaque_auth(XDR *xdrs, struct opaque_auth *ap);

用于描述RPC身份验证信息消息。该例程对于希望在不使用RPC包的情况下生成RPC样式的消息的用户很有用。

bool_t xdr_pmap(XDR *xdrs, struct pmap *regs);

用于在外部描述各种portmap过程的参数。该例程对希望在不使用pmap接口的情况下生成这些参数的用户很有用。

bool_t xdr_pmaplist(XDR *xdrs, struct pmaplist **rp);

用于在外部描述端口映射列表。该例程对希望在不使用pmap接口的情况下生成这些参数的用户很有用。

bool_t xdr_rejected_reply(XDR *xdrs, struct rejected_reply *rr);

用于描述RPC回复消息。该例程对于希望在不使用RPC包的情况下生成RPC样式的消息的用户很有用。

bool_t xdr_replymsg(XDR *xdrs, struct rpc_msg *rmsg);

用于描述RPC回复消息。该例程对于希望在不使用RPC包的情况下生成RPC样式消息的用户很有用。

void xprt_register(SVCXPRT *xprt);

创建RPC服务传输句柄后，它们应该在RPC服务包中注册自己。该例程修改全局变量svc_fds。服务实现者通常不需要此例程。

void xprt_unregister(SVCXPRT *xprt);

在销毁RPC服务传输句柄之前，应先向RPC服务包注销其自身。该例程修改全局变量svc_fds。服务实现者通常不需要此例程。

属性

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

另外参见

xdr(3)

以下手册：

远程过程调用：协议规范 远程过程调用编程指南 rpcgen编程指南

RPC：远程过程调用协议规范，RFC 1050，Sun Microsystems，Inc.，USC-ISI。

出版信息

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