属性

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

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

出版信息

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

另外参见

xdr(3)

以下手册：

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

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

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);

portmap服务的用户界面，该用户界面返回端口号，在该端口号上等待支持程序号prognum，版本versnum并说出与协议关联的传输协议的服务。协议的值很可能是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，协议]到xprt->xp_port的映射。过程分派具有以下形式：

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

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

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。服务实现者通常不需要此例程。

名称

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