518 lines
11 KiB
Groff
518 lines
11 KiB
Groff
.\" $NetBSD: rpcgen.1,v 1.19 2004/05/12 18:49:30 wiz Exp $
|
|
.\" from: @(#)rpcgen.new.1 1.1 90/11/09 TIRPC 1.0; from 40.10 of 10/10/89
|
|
.\" Copyright (c) 1988,1990 Sun Microsystems, Inc. - All Rights Reserved.
|
|
.Dd May 12, 2004
|
|
.Dt RPCGEN 1
|
|
.Sh NAME
|
|
.Nm rpcgen
|
|
.Nd Remote Procedure Call (RPC) protocol compiler
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Ar infile
|
|
.Nm
|
|
.Op Fl A
|
|
.Op Fl a
|
|
.Op Fl b
|
|
.Op Fl C
|
|
.Op Fl D Ar name Op =value
|
|
.Op Fl I
|
|
.Op Fl i Ar size
|
|
.Op Fl K Ar secs
|
|
.Op Fl L
|
|
.Op Fl M
|
|
.Op Fl N
|
|
.Op Fl T
|
|
.Op Fl v
|
|
.Op Fl Y Ar pathname
|
|
.Ar infile
|
|
.Nm
|
|
.Fl c Li |
|
|
.Fl h Li |
|
|
.Fl l Li |
|
|
.Fl m Li |
|
|
.Fl t Li |
|
|
.Fl S\&c Li |
|
|
.Fl S\&s
|
|
.\" .Fl S\&m
|
|
.Op Fl o Ar outfile
|
|
.Op Ar infile
|
|
.Nm
|
|
.Op Fl s Ar nettype
|
|
.Op Fl o Ar outfile
|
|
.Op Ar infile
|
|
.Nm
|
|
.Op Fl n Ar netid
|
|
.Op Fl o Ar outfile
|
|
.Op Ar infile
|
|
.Sh DESCRIPTION
|
|
.Nm
|
|
is a tool that generates C code to implement an
|
|
.Tn RPC
|
|
protocol.
|
|
The input to
|
|
.Nm
|
|
is a language similar to C known as
|
|
.Tn RPC
|
|
Language (Remote Procedure Call Language).
|
|
.Nm
|
|
is normally used as in the first synopsis where
|
|
it takes an input file and generates up to four output files.
|
|
If the
|
|
.Ar infile
|
|
is named
|
|
.Pa proto.x ,
|
|
then
|
|
.Nm
|
|
will generate a header file in
|
|
.Pa proto.h ,
|
|
.Tn XDR
|
|
routines in
|
|
.Pa proto_xdr.c ,
|
|
server-side stubs in
|
|
.Pa proto_svc.c ,
|
|
and client-side stubs in
|
|
.Pa proto_clnt.c .
|
|
With the
|
|
.Fl T
|
|
option,
|
|
it will also generate the
|
|
.Tn RPC
|
|
dispatch table in
|
|
.Pa proto_tbl.i .
|
|
With the
|
|
.Fl S\&c
|
|
option,
|
|
it will also generate sample code which would illustrate how to use the
|
|
remote procedures on the client side.
|
|
This code would be created in
|
|
.Pa proto_client.c .
|
|
With the
|
|
.Fl S\&s
|
|
option,
|
|
it will also generate a sample server code which would illustrate how to write
|
|
the remote procedures.
|
|
This code would be created in
|
|
.Pa proto_server.c .
|
|
.Pp
|
|
The server created can be started both by the port monitors
|
|
(for example,
|
|
.Em inetd
|
|
or
|
|
.Em 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 name of the transport must be specified
|
|
by setting up the environmental variable
|
|
.Ev PM_TRANSPORT .
|
|
When the server generated by
|
|
.Nm
|
|
is executed,
|
|
it creates server handles for all the transports
|
|
specified in
|
|
.Ev NETPATH
|
|
environment variable,
|
|
or if it is unset,
|
|
it creates server handles for all the visible transports from
|
|
.Pa /etc/netconfig
|
|
file.
|
|
.Pp
|
|
.Em 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
|
|
.Dv RPC_SVC_FG
|
|
can be used to run the server process in foreground.
|
|
.P
|
|
The second synopsis provides special features which allow
|
|
for the creation of more sophisticated
|
|
.Tn RPC
|
|
servers.
|
|
These features include support for user provided
|
|
.Li #defines
|
|
and
|
|
.Tn RPC
|
|
dispatch tables.
|
|
The entries in the
|
|
.Tn RPC
|
|
dispatch table contain:
|
|
.Pp
|
|
.Bl -inset -offset indent -compact
|
|
.It +
|
|
pointers to the service routine corresponding to that procedure,
|
|
.It +
|
|
a pointer to the input and output arguments,
|
|
.It +
|
|
the size of these routines
|
|
.El
|
|
.Pp
|
|
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
|
|
.Tn XDR
|
|
data conversion.
|
|
.Pp
|
|
The other three synopses shown above are used when
|
|
one does not want to generate all the output files,
|
|
but only a particular one.
|
|
Some examples of their usage is described in the
|
|
.Sx EXAMPLES
|
|
section below.
|
|
When
|
|
.Nm
|
|
is executed with the
|
|
.Fl s
|
|
option,
|
|
it creates servers for that particular class of transports.
|
|
When
|
|
executed with the
|
|
.Fl n
|
|
option,
|
|
it creates a server for the transport specified by
|
|
.Em netid .
|
|
If
|
|
.Ar infile
|
|
is not specified,
|
|
.Nm
|
|
accepts the standard input.
|
|
.Pp
|
|
The C preprocessor,
|
|
.Xr cpp 1
|
|
is run on the input file before it is actually interpreted by
|
|
.Nm
|
|
For each type of output file,
|
|
.Nm
|
|
defines a special preprocessor symbol for use by the
|
|
.Nm
|
|
programmer:
|
|
.Bl -tag -width RPC_CLNT
|
|
.It Dv RPC_HDR
|
|
defined when compiling into header files
|
|
.It Dv RPC_XDR
|
|
defined when compiling into
|
|
.Tn XDR
|
|
routines
|
|
.It Dv RPC_SVC
|
|
defined when compiling into server-side stubs
|
|
.It Dv RPC_CLNT
|
|
defined when compiling into client-side stubs
|
|
.It Dv RPC_TBL
|
|
defined when compiling into
|
|
.Tn RPC
|
|
dispatch tables
|
|
.El
|
|
.Pp
|
|
Any line beginning with
|
|
.Sq %
|
|
is passed directly into the output file,
|
|
uninterpreted by
|
|
.Nm .
|
|
.Pp
|
|
For every data type referred to in
|
|
.Ar infile
|
|
.Nm
|
|
assumes that there exists a
|
|
routine with the string
|
|
.Dq xdr_
|
|
prepended to the name of the data type.
|
|
If this routine does not exist in the
|
|
.Tn RPC/XDR
|
|
library, it must be provided.
|
|
Providing an undefined data type
|
|
allows customization of
|
|
.Tn XDR
|
|
routines.
|
|
.Sh OPTIONS
|
|
.Bl -tag -width indent
|
|
.It Fl a
|
|
Generate all the files including sample code for client and server side.
|
|
.It Fl A
|
|
Generate an
|
|
.Fn svc_caller
|
|
function.
|
|
.It Fl b
|
|
Compile stubs in "backwards compatible" mode, disabling support for
|
|
transport-independent RPC.
|
|
The
|
|
.Fl b
|
|
should always be specified when generating files for
|
|
.Nx ,
|
|
since there is no transport-independent RPC support in
|
|
.Nx .
|
|
.It Fl c
|
|
Compile into
|
|
.Tn XDR
|
|
routines.
|
|
.It Fl C
|
|
Generate code in
|
|
.Tn ANSI
|
|
C.
|
|
This option also generates code that could be compiled with the
|
|
C++ compiler.
|
|
.It Fl D Ar name Ns Op Ar =value
|
|
Define a symbol
|
|
.Dv name .
|
|
Equivalent to the
|
|
.Dv #define
|
|
directive in the source.
|
|
If no
|
|
.Dv value
|
|
is given,
|
|
.Dv value
|
|
is defined as 1.
|
|
This option may be specified more than once.
|
|
.It Fl h
|
|
Compile into C data-definitions (a header file).
|
|
The
|
|
.Fl T
|
|
option can be used in conjunction to produce a
|
|
header file which supports
|
|
.Tn RPC
|
|
dispatch tables.
|
|
.It Fl i Ar size
|
|
Size to decide when to start generating inline code.
|
|
The default size is 3.
|
|
.It Fl I
|
|
Support
|
|
.Xr inetd 8
|
|
in the server side stubs.
|
|
Servers generated using this flag can either be standalone or
|
|
started from
|
|
.Xr inetd 8 .
|
|
If a server is started as standalone, then it places itself
|
|
in the background, unless
|
|
.Dv RCP_SVC_FG
|
|
is defined, or the server is compiled without
|
|
.Fl I .
|
|
.It Fl K Ar secs
|
|
By default, services created using
|
|
.Nm
|
|
wait 120 seconds
|
|
after servicing a request before exiting.
|
|
That interval can be changed using the
|
|
.Fl K
|
|
flag.
|
|
To create a server that exits immediately upon servicing a request,
|
|
.Dq Fl K No 0
|
|
can be used.
|
|
To create a server that never exits, the appropriate argument is
|
|
.Dq Fl K No -1 .
|
|
.Pp
|
|
When monitoring for a server,
|
|
some port monitors, like the
|
|
.At V.4
|
|
utility
|
|
.Ic listen ,
|
|
.Em 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,
|
|
.Nm
|
|
should be used with
|
|
.Dq Fl K No -1 .
|
|
.It Fl l
|
|
Compile into client-side stubs.
|
|
.Xr inetd 8 .
|
|
.It Fl I
|
|
Compile stubs meant for use in programs started by
|
|
.Xr inetd 8 .
|
|
.It Fl L
|
|
Server errors will be sent to syslog instead of stderr.
|
|
.It Fl m
|
|
Compile into server-side stubs,
|
|
but do not generate a
|
|
.Fn main
|
|
routine.
|
|
This option is useful for doing callback-routines
|
|
and for users who need to write their own
|
|
.Fn main
|
|
routine to do initialization.
|
|
.It Fl M
|
|
Generate thread-safe stubs.
|
|
This alters the calling pattern of client and
|
|
server stubs so that storage for results is allocated by the caller.
|
|
Note
|
|
that all components for a particular service (stubs, client and service
|
|
wrappers, etc.) must be built either with or without the
|
|
.Fl M
|
|
flag.
|
|
.It Fl N
|
|
Use the newstyle of
|
|
.Nm .
|
|
This 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 the argument itself.
|
|
This behaviour is different from the oldstyle
|
|
of
|
|
.Nm
|
|
generated code.
|
|
The newstyle is not the default case because of backward compatibility.
|
|
.It Fl n Ar netid
|
|
Compile into server-side stubs for the transport
|
|
specified by
|
|
.Ar netid .
|
|
There should be an entry for
|
|
.Ar netid
|
|
in the
|
|
netconfig database.
|
|
This option may be specified more than once,
|
|
so as to compile a server that serves multiple transports.
|
|
.It Fl o Ar outfile
|
|
Specify the name of the output file.
|
|
If none is specified,
|
|
standard output is used
|
|
.Po
|
|
.Fl c Fl h Fl l
|
|
.Fl m Fl n Fl s
|
|
modes only
|
|
.Pc
|
|
.It Fl n Ar netid
|
|
Specify the transport for the server-side stubs.
|
|
.Ar netid
|
|
should be defined in
|
|
.Xr netconfig 5 .
|
|
This option can be repeated in order to support more than one transport.
|
|
.It Fl s Ar nettype
|
|
Compile into server-side stubs for all the
|
|
transports belonging to the class
|
|
.Ar nettype .
|
|
The supported classes are
|
|
.Em netpath ,
|
|
.Em visible ,
|
|
.Em circuit_n ,
|
|
.Em circuit_v ,
|
|
.Em datagram_n ,
|
|
.Em datagram_v ,
|
|
.Em tcp ,
|
|
and
|
|
.Em udp
|
|
[see
|
|
.Xr rpc 3
|
|
for the meanings associated with these classes.
|
|
.Em Note :
|
|
.Bx
|
|
currently supports only the
|
|
.Em tcp
|
|
and
|
|
.Em udp
|
|
classes].
|
|
This option may be specified more than once.
|
|
.Em Note :
|
|
the transports are chosen at run time and not at compile time.
|
|
.It Fl S\&c
|
|
Generate sample code to show the use of remote procedure and how to bind
|
|
to the server before calling the client side stubs generated by
|
|
.Nm .
|
|
.It Fl S\&s
|
|
Generate skeleton code for the remote procedures on the server side.
|
|
You would need
|
|
to fill in the actual code for the remote procedures.
|
|
.\" .It Fl S\&m
|
|
.\" Generate a sample Makefile that can be used to compile the application.
|
|
.It Fl t
|
|
Compile into
|
|
.Tn RPC
|
|
dispatch table.
|
|
.It Fl T
|
|
Generate the code to support
|
|
.Tn RPC
|
|
dispatch tables.
|
|
.It Fl v
|
|
Display the version number.
|
|
.It Fl Y Ar pathname
|
|
Specify the directory where
|
|
.Nm
|
|
looks for the C pre-processor.
|
|
.El
|
|
.Pp
|
|
The options
|
|
.Fl c ,
|
|
.Fl h ,
|
|
.Fl l ,
|
|
.Fl m ,
|
|
.Fl s ,
|
|
and
|
|
.Fl t
|
|
are used exclusively to generate a particular type of file,
|
|
while the options
|
|
.Fl D
|
|
and
|
|
.Fl T
|
|
are global and can be used with the other options.
|
|
.Sh NOTES
|
|
The
|
|
.Tn RPC
|
|
Language does not support nesting of structures.
|
|
As a work-around,
|
|
structures can be declared at the top-level,
|
|
and their name used inside other structures in
|
|
order to achieve the same effect.
|
|
.Pp
|
|
Name clashes can occur when using program definitions,
|
|
since the apparent scoping does not really apply.
|
|
Most of these can be avoided by giving
|
|
unique names for programs,
|
|
versions,
|
|
procedures and types.
|
|
.Pp
|
|
The server code generated with
|
|
.Fl n
|
|
option refers to the transport indicated by
|
|
.Em netid
|
|
and hence is very site specific.
|
|
.Sh EXAMPLES
|
|
The command
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
$ rpcgen -T prot.x
|
|
.Ed
|
|
.Pp
|
|
generates the five files:
|
|
.Pa prot.h ,
|
|
.Pa prot_clnt.c ,
|
|
.Pa prot_svc.c ,
|
|
.Pa prot_xdr.c
|
|
and
|
|
.Pa prot_tbl.i .
|
|
.Pp
|
|
The following example sends the C data-definitions (header file)
|
|
to standard output.
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
$ rpcgen -h prot.x
|
|
.Ed
|
|
.Pp
|
|
To send the test version of the
|
|
.Dv -DTEST ,
|
|
server side stubs for
|
|
all the transport belonging to the class
|
|
.Em datagram_n
|
|
to standard output, use:
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
$ rpcgen -s datagram_n -DTEST prot.x
|
|
.Ed
|
|
.Pp
|
|
To create the server side stubs for the transport indicated by
|
|
.Em netid
|
|
.Em tcp ,
|
|
use:
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
$ rpcgen -n tcp -o prot_svc.c prot.x
|
|
.Ed
|
|
.Sh SEE ALSO
|
|
.Xr cpp 1 ,
|
|
.Xr inetd 8
|
|
.Sh HISTORY
|
|
The
|
|
.Fl M
|
|
option was first implemented in RedHat Linux, and was reimplemented by
|
|
Charles M. Hannum in
|
|
.Nx 1.6 .
|