Go to main content

手册页部分 1:用户命令

退出打印视图

更新时间: 2018年8月8日 星期三
 
 

rpcgen(1)

名称

rpcgen - RPC 协议编译器

用法概要

rpcgen infile
rpcgen [-a] [-A] [-b] [-C] [-D name [= value]] [-i size] 
     [-I [-K seconds]] [-L] [-M] [-N] [- T] [-v] 
     [-Y pathname] infile
rpcgen [-c | -h | -l | -m | -t | -Sc | -Ss | -Sm] 
     [-o outfile] infile
rpcgen [-s nettype] [-o outfile] infile
rpcgen [-n netid] [-o outfile] infile

描述

rpcgen 实用程序是生成 C 代码以实现 RPC 协议的工具。rpcgen 的输入是类似 C 语言的语言,被称为 RPC 语言(远程过程调用语言)。

rpcgen 实用程序通常用于第一个用法概要中,它会采用输入文件并生成三个输出文件。如果 infile 是指定的 proto.x,那么 rpcgen 会在 proto.h 中生成标题,在 proto_xdr.c 中生成 XDR 例程,在 proto_svc.c 中生成服务器端桩并在 proto_clnt.c 中生成客户端桩。使用 –T 选项,它还会在 proto_tbl.i 中生成 RPC 分发表。

rpcgen 还可以生成样例客户机和服务器文件,可对其进行定制以适应特定应用程序。–Sc–Ss–Sm 选项分别生成样例客户机、服务器和 makefile。–a 选项生成所有文件,包括样例文件。如果 infileproto.x,则客户端样例文件将写入 proto_client.c、服务器端样例文件将写入 proto_server.c 以及样例 makefile 将写入 makefile.proto

所创建的服务器可由端口监视器(例如 inetd)启动或自行启动。由端口监视器启动时,它仅为传递文件描述符 0 的传输创建服务器。必须通过设置环境变量 PM_TRANSPORT 来指定传输的名称。当执行由 rpcgen 生成的服务器时,它会为在 NETPATH 环境变量中指定的所有传输创建服务器句柄,如果没有设置,则它会为来自 /etc/netconfig 文件的所有可见传输创建服务器句柄。注:传输是在运行时选择的,而不是编译时。当服务器自行启动时,它会在缺省情况下将自己作为后台。可使用特殊定义符号 RPC_SVC_FG 在前台运行服务器进程。

第二个用法概要提供了特殊功能,允许创建更为复杂的 RPC 服务器。这些功能包括对用户提供的 #defines 和 RPC 分发表的支持。RPC 分发表中的条目包括:

  • 指向与该过程对应的服务例程的指针

  • 指向输入和输出参数的指针

  • 这些例程的大小

服务器可使用分发表来检查授权,然后执行服务例程。客户机库可使用分发表来处理存储管理和 XDR 数据转换的详细信息。

如果用户不希望生成所有输出文件,只希望生成特定输出文件,则可使用上面显示的其他三个用法概要。请参见下文的“示例”部分以了解 rpcgen 用法的示例。使用 –s 选项执行 rpcgen 时,会为该特定传输类创建服务器。使用 –n 选项执行时,它将为 netid 指定的传输创建服务器。如果没有指定 infile,则 rpcgen 接受标准输入。

在第二个用法概要中提到的所有选项都可用于其他三个用法概要,但只能对指定输出文件进行更改。

rpcgen 实际解释 C 预处理程序 cc –E 前,该预处理程序会在输入文件上运行。对于每种类型的输出文件,rpcgen 会定义 rpcgen 程序员所使用的特殊预处理程序符号:

RPC_HDR

在编译为标题时定义

RPC_XDR

在编译为 XDR 例程时定义

RPC_SVC

在编译为服务器端桩时定义

RPC_CLNT

在编译为客户端桩时定义

RPC_TBL

在编译为 RPC 分发表时定义

任何以 "%" 开头的行都会直接传递至输出文件,无需 rpcgen 解释,除非删除了前导 "%"。要指定 C 预处理程序的路径名,请使用 –Y 标志。

对于每个在 infile 中引用的数据类型,rpcgen 会假设存在一个例程,其中的字符串 xdr_ 会附加到数据类型名称之前。如果 RPC/XDR 库中不存在该例程,则必须提供该例程。提供未定义的数据类型允许对 XDR 例程进行定制。

服务器错误报告

缺省情况下会将 proto_svc.c 检测到的错误报告到标准错误和/或系统日志。

可通过编译带有 RPC_MSGOUT 定义的文件来覆盖该行为,例如 -DRPC_MSGOUT=mymsgfunc。可调用指定的函数以报告错误。它必须符合以下类似 printf 的签名:

extern void RPC_MSGOUT(const char *fmt, ...);

选项

支持以下选项:

–a

生成所有文件,包括样例文件。

–A

在服务器主程序中启用自动 MT 模式。在此模式中,RPC 库会自动将线程创建到服务客户机请求。该选项可通过隐式启用 –M 选项来生成多线程安全桩。可使用 rpc_control(3C) 调用来设置服务器多线程模式和参数。rpcgen 生成的代码不会更改自动 MT 模式的缺省值。

–b

向后兼容性模式。为早期版本的操作系统生成特定于传输的 RPC 代码。

–c

编译到 XDR 例程。

–C

生成 ANSI C 编译器可使用的标题和桩文件。使用此标志生成的标题也可用于 C++ 程序。

–Dname[=value]

定义符号 name。等效于源中的 #define 指令。如果未提供 value,则会将 value 定义为 1。可多次指定此选项。

–h

编译到 C 数据定义(一个标题)。可结合使用 –T 选项以生成支持 RPC 分发表的标题。

–i size

开始生成内联代码时的大小。该选项是实用的优化选项。缺省 size 为 5。

–I

编译支持服务器端桩中的 inetd(8)。此类服务器可自行启动,也可由 inetd 启动。当服务器自行启动时,它会在缺省情况下将自己作为后台。可使用特殊定义符号 RPC_SVC_FG 在前台运行服务器进程,用户也可不使用 –I 选项,直接进行编译。

如果没有暂挂的客户机请求,则 inetd 服务器会在 120 秒(缺省值)后退出。可使用 –K 选项更改缺省值。inetd 服务器的所有错误消息始终都由 syslog(3C) 记录。


注 -  提供此选项只是为了向后兼容。它始终应该与生成向后兼容性代码的 –b 选项结合使用。缺省情况下(即未指定 –b 的情况下),rpcgen 会生成可通过端口监视器调用的服务器。
–K seconds

缺省情况下,使用 rpcgen 创建且通过端口监视器调用的服务会在处理请求后等待 120 再退出。可使用 –K 标志更改该间隔。要创建在处理请求后立即退出的服务器,请使用 –K 0。要创建从不退出的服务器,相应的参数为 –K -1

监视服务器时,某些端口监视器始终会派生一个新进程以响应服务请求。如果已知服务器使用此类监视器,则服务器应该在完成后立即退出。对于此类服务器,rpcgen 应该与 –K 0 一起使用。

–l

编译到客户端桩。

–L

如果服务器是在前台启动的,请使用syslog(3C) 记录服务器错误,而不是将其输出到标准错误。

–m

编译到服务器端桩,但不生成“主”例程。对于处理回调例程和需要编写自己的“主”例程以处理初始化的用户而言,该选项十分有用。

–M

生成多线程安全桩以在 rpcgen 生成的代码和用户编写的代码间传递参数和结果。对于希望在其代码中使用线程的用户而言,该选项十分有用。

–N

该选项允许过程拥有多个参数。它同样会使用与 C 非常类似的传递参数的样式。所以,向远程过程传递参数时,您不应该向该参数传递指针,但可以传递参数本身。此行为与 rpcgen 生成的代码的旧样式不同。为维护向后兼容性,此选项并非缺省值。

–n netid

netid 指定的传输编译到服务器端桩。netconfig 数据库中应该有一个 netid 条目。应该多次指定该选项以编译为多个传输提供服务的服务器。

–o  outfile

指定输出文件的名称。如果没有指定任何选项,则应该使用标准输出(仅适用于 –c–h–l–m–n–s–Sc–Sm–Ss–t 模式)。

–s nettype

为属于 nettype 类的所有传输编译到服务器端桩。支持的类有 netpathvisiblecircuit_ncircuit_vdatagram_ndatagram_vtcpudp(请参见 rpc(3C) 了解与这些类相关联的含义)。可多次指定此选项。注:传输是在运行时选择的,而不是编译时。

–Sc

生成使用远程过程调用的样例客户机代码。

–Sm

生成可用于编译应用程序的样例 Makefile

–Ss

生成使用远程过程调用的样例服务器代码。

–t

编译到 RPC 分发表。

–T

生成代码以支持 RPC 分发表。

–c–h–l–m–s–Sc–Sm–Ss–t 选项专用于生成特定文件类型,而 –D–T 选项是全局性的,可与其他选项一起使用。

–v

显示版本号。

–Y pathname

提供 rpcgen 开始查找 C 预处理程序的目录的名称。

操作数

支持下列操作数:

infile

输入文件

示例

示例 1 生成输出文件和派送表

以下条目

example% rpcgen -T prot.x

生成全部五个文件:prot.hprot_clnt.cprot_svc.cprot_xdr.cprot_tbl.i

示例 2 将头发送到标准输出

以下示例将 C 数据定义(标题)发送到标准输出:

example% rpcgen -h prot.x
示例 3 发送测试版本

要为属于 datagram_n 类的所有传输将服务器端桩的 –DTEST 测试版本发送到标准输出,请使用:

example% rpcgen -s datagram_n -DTEST prot.x
示例 4 创建服务器端桩

要为 netid tcp 指定的传输创建服务器端桩,请使用:

example% rpcgen -n tcp -o prot_svc.c prot.x

退出状态

0

操作成功。

>0

出现错误。

属性

有关下列属性的说明,请参见 attributes(7)

属性类型
属性值
可用性
developer/base-developer-utilities

另请参见

rpc(3C)rpc_control(3C)rpc_svc_calls(3C)syslog(3C)netconfig(5)attributes(7)inetd(8)

ONC+ RPC Developer’s Guide手册中的 rpcgen 一章。