553 lines
12 KiB
Groff
553 lines
12 KiB
Groff
.\" @(#)rpcgen.1 1.35 93/06/02 SMI
|
|
'\"macro stdmacro
|
|
.\" Copyright 1985-1993 Sun Microsystems, Inc.
|
|
.nr X
|
|
.TH rpcgen 1 "28 Mar 1993"
|
|
.SH NAME
|
|
rpcgen \- an RPC protocol compiler
|
|
.SH SYNOPSIS
|
|
.BI rpcgen " infile"
|
|
.LP
|
|
.B rpcgen
|
|
[
|
|
.B \-a
|
|
] [
|
|
.B \-b
|
|
] [
|
|
.B \-C
|
|
] [
|
|
.BI \-D name
|
|
[ =
|
|
.I value
|
|
] ]
|
|
.if n .ti +5n
|
|
[
|
|
.BI \-i " size"
|
|
]
|
|
[
|
|
.B \-I
|
|
[
|
|
.BI \-K " seconds"
|
|
] ]
|
|
[
|
|
.B \-L
|
|
] [
|
|
.B \-M
|
|
]
|
|
.if n .ti +5n
|
|
.if t .ti +5n
|
|
[
|
|
.B \-N
|
|
]
|
|
[
|
|
.B \-T
|
|
] [
|
|
.BI \-Y " pathname"
|
|
]
|
|
.I infile
|
|
.LP
|
|
.B rpcgen
|
|
[
|
|
.B \-c
|
|
|
|
|
.B \-h
|
|
|
|
|
.B \-l
|
|
|
|
|
.B \-m
|
|
|
|
|
.B \-t
|
|
|
|
|
.B \-Sc
|
|
|
|
|
.B \-Ss
|
|
|
|
|
.B \-Sm
|
|
]
|
|
.if n .ti +5n
|
|
[
|
|
.BI \-o " outfile"
|
|
] [
|
|
.I infile
|
|
]
|
|
.LP
|
|
.B rpcgen
|
|
[
|
|
.BI \-s " nettype"
|
|
] [
|
|
.BI \-o " outfile"
|
|
] [
|
|
.I infile
|
|
]
|
|
.LP
|
|
.B rpcgen
|
|
[
|
|
.BI \-n " netid"
|
|
] [
|
|
.BI \-o " outfile"
|
|
] [
|
|
.I infile
|
|
]
|
|
.\" .SH AVAILABILITY
|
|
.\" .LP
|
|
.\" SUNWcsu
|
|
.SH DESCRIPTION
|
|
.IX "rpcgen" "" "\fLrpcgen\fP \(em RPC protocol compiler"
|
|
.IX "RPC" "protocol compiler" "" "protocol compiler \(em \fLrpcgen\fP"
|
|
.IX "RPC Language" "RPC protocol compiler" "" "RPC protocol compiler \(em \fLrpcgen\fP"
|
|
.IX "compilers" "RPC protocol compiler" "" "RPC protocol compiler \(em \fLrpcgen\fP"
|
|
.IX "programming tools" "RPC protocol compiler" "" "RPC protocol compiler \(em \fLrpcgen\fP"
|
|
.LP
|
|
\f3rpcgen\f1
|
|
is a tool that generates C code to implement an RPC protocol.
|
|
The input to
|
|
\f3rpcgen\f1
|
|
is a language similar to C known as
|
|
RPC Language (Remote Procedure Call Language).
|
|
.LP
|
|
\f3rpcgen\f1
|
|
is normally used as in the first synopsis where
|
|
it takes an input file and generates three output files.
|
|
If the
|
|
\f2infile\f1
|
|
is named
|
|
\f3proto.x\f1,
|
|
then
|
|
\f3rpcgen\f1
|
|
generates a header in
|
|
\f3proto.h\f1,
|
|
XDR routines in
|
|
\f3proto_xdr.c\f1,
|
|
server-side stubs in
|
|
\f3proto_svc.c\f1,
|
|
and client-side stubs in
|
|
\f3proto_clnt.c\f1.
|
|
With the
|
|
\f3\-T\f1
|
|
option,
|
|
it also generates the RPC dispatch table in
|
|
\f3proto_tbl.i\f1.
|
|
.LP
|
|
.B rpcgen
|
|
can also generate sample client and server files
|
|
that can be customized to suit a particular application. The
|
|
\f3\-Sc\f1,
|
|
\f3\-Ss\f1
|
|
and
|
|
\f3\-Sm\f1
|
|
options generate sample client, server and makefile, respectively.
|
|
The
|
|
\f3\-a\f1
|
|
option generates all files, including sample files. If the infile
|
|
is \f3proto.x\f1, then the client side sample file is written to
|
|
\f3proto_client.c\f1, the server side sample file to \f3proto_server.c\f1
|
|
and the sample makefile to \f3makefile.proto\f1.
|
|
.LP
|
|
The server created can be started both by the port monitors
|
|
(for example, \f3inetd\f1)
|
|
or by itself.
|
|
When it is started by a port monitor,
|
|
it creates servers only for the transport for which
|
|
the file descriptor \f30\fP was passed.
|
|
The name of the transport must be specified
|
|
by setting up the environment variable
|
|
\f3PM_TRANSPORT\f1.
|
|
When the server generated by
|
|
\f3rpcgen\f1
|
|
is executed,
|
|
it creates server handles for all the transports
|
|
specified in
|
|
\f3NETPATH\f1
|
|
environment variable,
|
|
or if it is unset,
|
|
it creates server handles for all the visible transports from
|
|
\f3/etc/netconfig\f1
|
|
file.
|
|
Note:
|
|
the transports 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
|
|
\f3RPC_SVC_FG\f1
|
|
can be used to run the server process in foreground.
|
|
.LP
|
|
The second synopsis provides special features which allow
|
|
for the creation of more sophisticated RPC servers.
|
|
These features include support for user provided
|
|
\f3#defines\f1
|
|
and RPC dispatch tables.
|
|
The entries in the RPC dispatch table contain:
|
|
.RS
|
|
.PD 0
|
|
.TP 3
|
|
\(bu
|
|
pointers to the service routine corresponding to that procedure,
|
|
.TP
|
|
\(bu
|
|
a pointer to the input and output arguments
|
|
.TP
|
|
\(bu
|
|
the size of these routines
|
|
.PD
|
|
.RE
|
|
A server can use the dispatch table to check authorization
|
|
and then to execute the service routine;
|
|
a client library may use it to deal with the details of storage
|
|
management and XDR data conversion.
|
|
.LP
|
|
The other three synopses shown above are used when
|
|
one does not want to generate all the output files,
|
|
but only a particular one.
|
|
See the
|
|
.SM EXAMPLES
|
|
section below for examples of
|
|
.B rpcgen
|
|
usage.
|
|
When
|
|
\f3rpcgen\f1
|
|
is executed with the
|
|
\f3\-s\f1
|
|
option,
|
|
it creates servers for that particular class of transports.
|
|
When
|
|
executed with the
|
|
\f3\-n\f1
|
|
option,
|
|
it creates a server for the transport specified by
|
|
\f2netid\f1.
|
|
If
|
|
\f2infile\f1
|
|
is not specified,
|
|
\f3rpcgen\f1
|
|
accepts the standard input.
|
|
.LP
|
|
The C preprocessor,
|
|
\f3cc \-E\f1
|
|
is run on the input file before it is actually interpreted by
|
|
\f3rpcgen\f1.
|
|
For each type of output file,
|
|
\f3rpcgen\f1
|
|
defines a special preprocessor symbol for use by the
|
|
\f3rpcgen\f1
|
|
programmer:
|
|
.LP
|
|
.PD 0
|
|
.RS
|
|
.TP 12
|
|
\f3RPC_HDR\f1
|
|
defined when compiling into headers
|
|
.TP
|
|
\f3RPC_XDR\f1
|
|
defined when compiling into XDR routines
|
|
.TP
|
|
\f3RPC_SVC\f1
|
|
defined when compiling into server-side stubs
|
|
.TP
|
|
\f3RPC_CLNT\f1
|
|
defined when compiling into client-side stubs
|
|
.TP
|
|
\f3RPC_TBL\f1
|
|
defined when compiling into RPC dispatch tables
|
|
.RE
|
|
.PD
|
|
.LP
|
|
Any line beginning with
|
|
``\f3%\f1''
|
|
is passed directly into the output file,
|
|
uninterpreted by
|
|
\f3rpcgen\f1.
|
|
To specify the path name of the C preprocessor use \f3\-Y\f1 flag.
|
|
.LP
|
|
For every data type referred to in
|
|
\f2infile\f1,
|
|
\f3rpcgen\f1
|
|
assumes that there exists a
|
|
routine with the string
|
|
\f3xdr_\f1
|
|
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.
|
|
.br
|
|
.ne 10
|
|
.SH OPTIONS
|
|
.TP 15
|
|
\f3\-a\f1
|
|
Generate all files, including sample files.
|
|
.TP
|
|
\f3\-b\f1
|
|
Backward compatibility mode.
|
|
Generate transport specific RPC code for older versions
|
|
of the operating system.
|
|
.IP
|
|
Note: in FreeBSD, this compatibility flag is turned on by
|
|
default since FreeBSD supports only the older ONC RPC library.
|
|
.TP
|
|
\f3\-c\f1
|
|
Compile into XDR routines.
|
|
.TP
|
|
\f3\-C\f1
|
|
Generate header and stub files which can be used with
|
|
.SM ANSI C
|
|
compilers. Headers generated with this flag can also be
|
|
used with C++ programs.
|
|
.TP
|
|
\f3\-D\f2name\f3[=\f2value\f3]\f1
|
|
Define a symbol
|
|
\f2name\f1.
|
|
Equivalent to the
|
|
\f3#define\f1
|
|
directive in the source.
|
|
If no
|
|
\f2value\f1
|
|
is given,
|
|
\f2value\f1
|
|
is defined as \f31\f1.
|
|
This option may be specified more than once.
|
|
.TP
|
|
\f3\-h\f1
|
|
Compile into
|
|
\f3C\f1
|
|
data-definitions (a header).
|
|
\f3\-T\f1
|
|
option can be used in conjunction to produce a
|
|
header which supports RPC dispatch tables.
|
|
.TP
|
|
\f3\-i \f2size\f1
|
|
Size at which to start generating inline code.
|
|
This option is useful for optimization. The default size is 5.
|
|
.IP
|
|
Note: in order to provide backwards compatibility with the older
|
|
.B rpcgen
|
|
on the FreeBSD platform, the default is actually 0 (which means
|
|
that inline code generation is disabled by default). You must specify
|
|
a non-zero value explicitly to override this default.
|
|
.TP
|
|
\f3\-I\f1
|
|
Compile support for
|
|
.BR inetd (8)
|
|
in the server side stubs.
|
|
Such servers can be self-started or can be started by \f3inetd\f1.
|
|
When the server is self-started, it backgrounds itself by default.
|
|
A special define symbol \f3RPC_SVC_FG\f1 can be used to run the
|
|
server process in foreground, or the user may simply compile without
|
|
the \f3\-I\f1 option.
|
|
.br
|
|
.ne 5
|
|
.IP
|
|
If there are no pending client requests, the
|
|
\f3inetd\f1 servers exit after 120 seconds (default).
|
|
The default can be changed with the
|
|
.B \-K
|
|
option.
|
|
All the error messages for \f3inetd\f1 servers
|
|
are always logged with
|
|
.BR syslog (3).
|
|
.\" .IP
|
|
.\" Note:
|
|
.\" this option is supported for backward compatibility only.
|
|
.\" By default,
|
|
.\" .B rpcgen
|
|
.\" generates servers that can be invoked through portmonitors.
|
|
.TP
|
|
.BI \-K " seconds"
|
|
By default, services created using \f3rpcgen\fP and invoked through
|
|
port monitors wait \f3120\fP seconds
|
|
after servicing a request before exiting.
|
|
That interval can be changed using the \f3\-K\fP flag.
|
|
To create a server that exits immediately upon servicing a request,
|
|
use
|
|
.BR "\-K\ 0".
|
|
To create a server that never exits, the appropriate argument is
|
|
\f3\-K \-1\fP.
|
|
.IP
|
|
When monitoring for a server,
|
|
some portmonitors
|
|
.I 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, \f3rpcgen\fP should be used with \f3\-K 0\fP.
|
|
.TP
|
|
\f3\-l\f1
|
|
Compile into client-side stubs.
|
|
.TP
|
|
.B \-L
|
|
When the servers are started in foreground, use
|
|
.BR syslog (3)
|
|
to log the server errors instead of printing them on the standard
|
|
error.
|
|
.TP
|
|
\f3\-m\f1
|
|
Compile into server-side stubs,
|
|
but do not generate a \(lqmain\(rq routine.
|
|
This option is useful for doing callback-routines
|
|
and for users who need to write their own
|
|
\(lqmain\(rq routine to do initialization.
|
|
.TP
|
|
\f3\-M\f1
|
|
Generate multithread-safe stubs for passing 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. However, the
|
|
.BR rpc_svc_calls (3N)
|
|
functions are not yet MT-safe, which means that rpcgen generated server-side
|
|
code will not be MT-safe.
|
|
.TP
|
|
.B \-N
|
|
This option allows procedures to have multiple 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 different from the old style of
|
|
.B rpcgen
|
|
generated code.
|
|
To maintain backward compatibility,
|
|
this option is not the default.
|
|
.TP
|
|
\f3\-n \f2netid\f1
|
|
Compile into server-side stubs for the transport
|
|
specified by
|
|
\f2netid\f1.
|
|
There should be an entry for
|
|
\f2netid\f1
|
|
in the
|
|
netconfig database.
|
|
This option may be specified more than once,
|
|
so as to compile a server that serves multiple transports.
|
|
.TP
|
|
\f3\-o \f2outfile\f1
|
|
Specify the name of the output file.
|
|
If none is specified,
|
|
standard output is used
|
|
(\f3\-c\f1,
|
|
\f3\-h\f1,
|
|
\f3\-l\f1,
|
|
\f3\-m\f1,
|
|
\f3\-n\f1,
|
|
\f3\-s\f1,
|
|
\f3\-Sc\f1,
|
|
\f3\-Sm\f1,
|
|
\f3\-Ss\f1,
|
|
and
|
|
\f3\-t\f1
|
|
modes only).
|
|
.TP
|
|
\f3\-s \f2nettype\f1
|
|
Compile into server-side stubs for all the
|
|
transports belonging to the class
|
|
\f2nettype\f1.
|
|
The supported classes are
|
|
\f3netpath\f1,
|
|
\f3visible\f1,
|
|
\f3circuit_n\f1,
|
|
\f3circuit_v\f1,
|
|
\f3datagram_n\f1,
|
|
\f3datagram_v\f1,
|
|
\f3tcp\f1,
|
|
and
|
|
\f3udp\f1
|
|
(see
|
|
.BR rpc (3N)
|
|
for the meanings associated with these classes).
|
|
This option may be specified more than once.
|
|
Note:
|
|
the transports are chosen at run time and not at compile time.
|
|
.TP
|
|
\f3\-Sc\f1
|
|
Generate sample client code that uses remote procedure calls.
|
|
.br
|
|
.ne 5
|
|
.TP
|
|
\f3\-Sm\f1
|
|
Generate a sample Makefile which can be used for compiling the
|
|
application.
|
|
.TP
|
|
\f3\-Ss\f1
|
|
Generate sample server code that uses remote procedure calls.
|
|
.TP
|
|
\f3\-t\f1
|
|
Compile into RPC dispatch table.
|
|
.TP
|
|
\f3\-T\f1
|
|
Generate the code to support RPC dispatch tables.
|
|
.IP
|
|
The options
|
|
\f3\-c\f1,
|
|
\f3\-h\f1,
|
|
\f3\-l\f1,
|
|
\f3\-m\f1,
|
|
\f3\-s\f1,
|
|
\f3\-Sc\f1,
|
|
\f3\-Sm\f1,
|
|
\f3\-Ss\f1,
|
|
and
|
|
\f3\-t\f1
|
|
are used exclusively to generate a particular type of file,
|
|
while the options
|
|
\f3\-D\f1
|
|
and
|
|
\f3\-T\f1
|
|
are global and can be used with the other options.
|
|
.TP
|
|
\f3\-Y\f2 pathname\f1
|
|
Give the name of the directory where
|
|
.B rpcgen
|
|
will start looking for the C-preprocessor.
|
|
.br
|
|
.ne 5
|
|
.SH EXAMPLES
|
|
The following example:
|
|
.LP
|
|
.RS
|
|
.B example% rpcgen \-T prot.x
|
|
.RE
|
|
.LP
|
|
generates all the five files:
|
|
.BR prot.h ,
|
|
.BR prot_clnt.c ,
|
|
.BR prot_svc.c ,
|
|
.B prot_xdr.c
|
|
and
|
|
.BR prot_tbl.i .
|
|
.LP
|
|
The following example sends the C data-definitions (header)
|
|
to the standard output.
|
|
.LP
|
|
.RS
|
|
.B example% rpcgen \-h prot.x
|
|
.RE
|
|
.LP
|
|
To send the test version of the
|
|
.BR -DTEST ,
|
|
server side stubs for
|
|
all the transport belonging to the class
|
|
.B datagram_n
|
|
to standard output, use:
|
|
.LP
|
|
.RS
|
|
.B example% rpcgen \-s datagram_n \-DTEST prot.x
|
|
.RE
|
|
.LP
|
|
To create the server side stubs for the transport indicated
|
|
by
|
|
\f2netid\f1
|
|
\f3tcp\f1,
|
|
use:
|
|
.LP
|
|
.RS
|
|
.B example% rpcgen \-n tcp \-o prot_svc.c prot.x
|
|
.RE
|
|
.SH "SEE ALSO"
|
|
.BR cc (1),
|
|
.BR inetd (8),
|
|
.BR syslog (3),
|
|
.BR rpc (3),
|
|
.\" .BR rpc_svc_calls (3)
|
|
.LP
|
|
The
|
|
.B rpcgen
|
|
chapter in the
|
|
.TZ NETP
|
|
manual.
|