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 output
files. If the infile is named proto.x, then rpcgen generates
a header in proto.h, XDR routines in protoxdr.c, server-
side stubs in protosvc.c, and client-side stubs in
protoclnt.c. With the -T option, it also generates the RPC
dispatch table in prototbl.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 the
client side sample file is written to protoclient.c, the
server side sample file to protoserver.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. The
SunOS 5.11 Last change: 7 Dec 2001 1
User Commands rpcgen(1)
name of the transport must be specified by setting up the
environment variable PMTRANSPORT. When the server generated
by rpcgen is executed, it creates server handles for all the
transports specified in the NETPATH environment variable, or
if 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. When
the server is self-started, it backgrounds itself by
default. A special define symbol RPCSVCFG 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. These
features 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
may 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 does
not 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 will be 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: 7 Dec 2001 2
User Commands rpcgen(1)
RPCHDR defined when compiling into headers
RPCXDR defined when compiling into XDR routines
RPCSVC defined when compiling into server-side stubs
RPCLNT defined when compiling into client-side stubs
RPCTBL 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 exist
in the RPC/XDR library, it must be provided. Providing an
undefined data type allows customization of XDR routines.
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 RPC
library automatically creates threads to
service client requests. This option gen-
erates multithread-safe stubs by impli-
citly turning on the -M option. Server
multithreading modes and parameters can be
set using the rpccontrol(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.
SunOS 5.11 Last change: 7 Dec 2001 3
User Commands rpcgen(1)
-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 may 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 be
self-started or can be started by inetd.
When the server is self-started, it back-
grounds itself by default. A special
define symbol RPCSVCFG can be used to
run the server process in foreground, or
the user may simply compile without the
-I option.
If there are no pending client requests,
the inetd servers exit after 120 seconds
(default). The default can be changed with
the -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 always
be used in conjunction with the -b option
which generates backward compatibility
code. By default (that is, when -b is not
specified), rpcgen generates servers that
can be invoked through portmonitors.
SunOS 5.11 Last change: 7 Dec 2001 4
User Commands rpcgen(1)
-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 changed
using the -K flag. To create a server that
exits immediately upon servicing a
request, 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 will
be used with such a monitor, the server
should exit immediately on completion. For
such 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 option
is useful for doing callback-routines and
for users who need to write their own
"main" routine to do initialization.
-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 pass
the argument itself. This behavior is dif-
ferent from the old style of rpcgen-
generated code. To maintain backward
SunOS 5.11 Last change: 7 Dec 2001 5
User Commands rpcgen(1)
compatibility, 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 may 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
nettype. The supported classes are net-
path, visible, circuitn, circuitv,
datagramn, datagramv, tcp, and udp (see
rpc(3NSL) for the meanings associated with
these classes). This option may be speci-
fied 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.
-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 the
options -D and -T are global and can be
SunOS 5.11 Last change: 7 Dec 2001 6
User Commands rpcgen(1)
used with the other options.
-v Displays the version number.
-Y pathname Gives the name of the directory where
rpcgen will start looking for the C
preprocessor.
OPERANDS
The following operand is supported:
infile input file
EXAMPLES
Example 1 Generating the output files and dispatch table
The following entry
example% rpcgen -T prot.x
generates all the five files: prot.h, protclnt.c,
protsvc.c, protxdr.c, and prottbl.i.
Example 2 Sending headers to standard output
The following example sends the C data-definitions (header)
to the standard output:
example% rpcgen -h prot.x
Example 3 Sending a test version
To send the test version of the -DTEST, server side stubs
for all the transport belonging to the class datagramn to
standard output, use:
SunOS 5.11 Last change: 7 Dec 2001 7
User Commands rpcgen(1)
example% rpcgen -s datagramn -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 protsvc.c prot.x
EXIT STATUS
0 Successful operation.
>0 An error occurred.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Availability SUNWbtool
SEE ALSO
cc(1B), inetd(1M), listen(1M), rpc(3NSL), rpccontrol(3NSL),
rpcsvccalls(3NSL), syslog(3C), netconfig(4), attributes(5)
The rpcgen chapter in the ONC] Developer's Guide manual.
SunOS 5.11 Last change: 7 Dec 2001 8
|
