User Commands rpcgen(1)
NAME
rpcgen - an RPC protocol compiler
SYNOPSIS
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]
DESCRIPTION
The rpcgen utility is a tool that generates C code to imple-
ment an RPC protocol. The input to rpcgen is a language
similar to C known as RPC Language (Remote Procedure Call Language).The rpcgen utility is normally used as in the first synopsis
where it takes an input file and generates three outputfiles. If the infile is named proto.x, then rpcgen generates
a header in proto.h, XDR routines in proto_xdr.c, server-
side stubs in proto_svc.c, and client-side stubs in
proto_clnt.c. With the -T option, it also generates the RPC
dispatch table in proto_tbl.i.
rpcgen can also generate sample client and server files that
can be customized to suit a particular application. The -Sc,
-Ss, and -Sm options generate sample client, server and
makefile, respectively. The -a option generates all files,
including sample files. If the infile is proto.x, then theclient side sample file is written to proto_client.c, the
server side sample file to proto_server.c and the sample
makefile to makefile.proto. The server created can be started both by the port monitors (for example, inetd or listen) or by itself. When it is started by a port monitor, it creates servers only for the transport for which the file descriptor 0 was passed. TheSunOS 5.11 Last change: 24 Aug 2009 1
User Commands rpcgen(1)
name of the transport must be specified by setting up theenvironment variable PM_TRANSPORT. When the server generated
by rpcgen is executed, it creates server handles for all the
transports specified in the NETPATH environment variable, orif it is unset, it creates server handles for all the visi-
ble transports from the /etc/netconfig file. Note: the tran-
sports are chosen at run time and not at compile time. Whenthe server is self-started, it backgrounds itself by
default. A special define symbol RPC_SVC_FG can be used to
run the server process in foreground. The second synopsis provides special features which allow for the creation of more sophisticated RPC servers. Thesefeatures include support for user-provided #defines and RPC
dispatch tables. The entries in the RPC dispatch table con-
tain: o pointers to the service routine corresponding to that procedure o a pointer to the input and output arguments o the size of these routines A server can use the dispatch table to check authorization and then to execute the service routine. A client library can use the dispatch table to deal with the details of storage management and XDR data conversion. The other three synopses shown above are used when one doesnot want to generate all the output files, but only a par-
ticular one. See the EXAMPLES section below for examples of
rpcgen usage. When rpcgen is executed with the -s option, it
creates servers for that particular class of transports.When executed with the -n option, it creates a server for
the transport specified by netid. If infile is not speci-
fied, rpcgen accepts the standard input.
All the options mentioned in the second synopsis can be used with the other three synopses, but the changes are made only to the specified output file.The C preprocessor cc -E is run on the input file before it
is actually interpreted by rpcgen. For each type of output
file, rpcgen defines a special preprocessor symbol for use
by the rpcgen programmer:
SunOS 5.11 Last change: 24 Aug 2009 2
User Commands rpcgen(1)
RPC_HDR defined when compiling into headers
RPC_XDR defined when compiling into XDR routines
RPC_SVC defined when compiling into server-side stubs
RPC_CLNT defined when compiling into client-side stubs
RPC_TBL defined when compiling into RPC dispatch tables
Any line beginning with ``%'' is passed directly into the
output file, uninterpreted by rpcgen, except that the lead-
ing ``%" is stripped off. To specify the path name of the C
preprocessor, use the -Y flag.
For every data type referred to in infile, rpcgen assumes
that there exists a routine with the string xdr_ prepended
to the name of the data type. If this routine does not existin the RPC/XDR library, it must be provided. Providing an undefined data type allows customization of XDR routines. Server Error Reporting
By default, errors detected by proto_svc.c is reported to
standard error and/or the system log. This behavior can be overridden by compiling the file with adefinition of RPC_MSGOUT, for example,
-DRPC_MSGOUT=mymsgfunc. The function specified is called to
report errors. It must conform to the following printf-like
signature:extern void RPC_MSGOUT(const char *fmt, ...);
OPTIONS The following options are supported:-a Generates all files, including sample
files.-A Enables the Automatic MT mode in the
server main program. In this mode, the RPCSunOS 5.11 Last change: 24 Aug 2009 3
User Commands rpcgen(1)
library automatically creates threads toservice client requests. This option gen-
erates multithread-safe stubs by impli-
citly turning on the -M option. Server
multithreading modes and parameters can beset using the rpc_control(3NSL) call.
rpcgen generated code does not change the
default values for the Automatic MT mode.-b Backward compatibility mode. Generates
transport-specific RPC code for older ver-
sions of the operating system.-c Compiles into XDR routines.
-C Generates header and stub files which can
be used with ANSI C compilers. Headers generated with this flag can also be used with C++ programs.-Dname[=value] Defines a symbol name. Equivalent to the
#define directive in the source. If no
value is given, value is defined as 1. This option can be specified more than once.-h Compiles into C data-definitions (a
header). The -T option can be used in con-
junction to produce a header which sup-
ports RPC dispatch tables.-i size Size at which to start generating inline
code. This option is useful for optimiza-
tion. The default size is 5.-I Compiles support for inetd(1M) in the
server side stubs. Such servers can beself-started or can be started by inetd.
When the server is self-started, it back-
grounds itself by default. A specialdefine symbol RPC_SVC_FG can be used to
run the server process in foreground, orthe user can simply compile without the -I
option.SunOS 5.11 Last change: 24 Aug 2009 4
User Commands rpcgen(1)
If there are no pending client requests, the inetd servers exit after 120 seconds (default). The default can be changed withthe -K option. All of the error messages
for inetd servers are always logged with syslog(3C).Note: This option is supported for back-
ward compatibility only. It should alwaysbe used in conjunction with the -b option
which generates backward compatibilitycode. By default (that is, when -b is not
specified), rpcgen generates servers that
can be invoked through portmonitors.-K seconds By default, services created using rpcgen
and invoked through port monitors wait 120 seconds after servicing a request before exiting. That interval can be changedusing the -K flag. To create a server that
exits immediately upon servicing arequest, use -K 0. To create a server that
never exits, the appropriate argument is-K -1.
When monitoring for a server, some port-
monitors, like listen(1M), always spawn a new process in response to a service request. If it is known that a server are used with such a monitor, the server should exit immediately on completion. Forsuch servers, rpcgen should be used with
-K 0.
-l Compiles into client-side stubs.
-L When the servers are started in fore-
ground, uses syslog(3C) to log the server errors instead of printing them on the standard error.-m Compiles into server-side stubs, but do
not generate a "main" routine. This optionis useful for doing callback-routines and
for users who need to write their own "main" routine to do initialization.SunOS 5.11 Last change: 24 Aug 2009 5
User Commands rpcgen(1)
-M Generates multithread-safe stubs for pass-
ing arguments and results between rpcgen-
generated code and user written code. This option is useful for users who want to use threads in their code.-N This option allows procedures to have mul-
tiple arguments. It also uses the style of parameter passing that closely resembles C. So, when passing an argument to a remote procedure, you do not have to pass a pointer to the argument, but can passthe argument itself. This behavior is dif-
ferent from the old style of rpcgen-
generated code. To maintain backward com-
patibility, this option is not the default.-n netid Compiles into server-side stubs for the
transport specified by netid. There should be an entry for netid in the netconfig database. This option can be specified more than once, so as to compile a server that serves multiple transports.-o outfile Specifies the name of the output file. If
none is specified, standard output is used(-c, -h, -l, -m, -n, -s, -Sc, -Sm, -Ss,
and -t modes only).
-s nettype Compiles into server-side stubs for all
the transports belonging to the class net-
type. The supported classes are netpath,visible, circuit_n, circuit_v, datagram_n,
datagram_v, tcp, and udp (see rpc(3NSL)
for the meanings associated with these classes). This option can be specified more than once. Note: The transports are chosen at run time and not at compile time.-Sc Generates sample client code that uses
remote procedure calls.-Sm Generates a sample Makefile which can be
used for compiling the application.SunOS 5.11 Last change: 24 Aug 2009 6
User Commands rpcgen(1)
-Ss Generates sample server code that uses
remote procedure calls.-t Compiles into RPC dispatch table.
-T Generates the code to support RPC dispatch
tables.The options -c, -h, -l, -m, -s, -Sc, -Sm,
-Ss, and -t are used exclusively to gen-
erate a particular type of file, while theoptions -D and -T are global and can be
used with the other options.-v Displays the version number.
-Y pathname Gives the name of the directory where
rpcgen starts looking for the C preproces-
sor. OPERANDS The following operand is supported: infile input fileEXAMPLES
Example 1 Generating the output files and dispatch table The following entryexample% rpcgen -T prot.x
generates all the five files: prot.h, prot_clnt.c,
prot_svc.c, prot_xdr.c, and prot_tbl.i.
Example 2 Sending headers to standard outputThe following example sends the C data-definitions (header)
to the standard output:SunOS 5.11 Last change: 24 Aug 2009 7
User Commands rpcgen(1)
example% rpcgen -h prot.x
Example 3 Sending a test versionTo send the test version of the -DTEST, server side stubs
for all the transport belonging to the class datagram_n to
standard output, use:example% rpcgen -s datagram_n -DTEST prot.x
Example 4 Creating server side stubs To create the server side stubs for the transport indicated by netid tcp, use:example% rpcgen -n tcp -o prot_svc.c prot.x
EXIT STATUS 0 Successful operation. >0 An error occurred.ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Availability | developer/object-file |
|_____________________________|_____________________________|
SEE ALSO
inetd(1M), listen(1M), rpc(3NSL), rpc_control(3NSL),
rpc_svc_calls(3NSL), syslog(3C), netconfig(4), attributes(5)
SunOS 5.11 Last change: 24 Aug 2009 8
User Commands rpcgen(1)
The rpcgen chapter in the ONC+ Developer's Guide manual.
SunOS 5.11 Last change: 24 Aug 2009 9