533 lines
11 KiB
Groff
533 lines
11 KiB
Groff
.\" @(#)rpcgen.1 1.35 93/06/02 SMI
|
|
.\" $FreeBSD$
|
|
.\" Copyright 1985-1993 Sun Microsystems, Inc.
|
|
.\"
|
|
.Dd September 2, 2005
|
|
.Dt RPCGEN 1
|
|
.Os
|
|
.Sh NAME
|
|
.Nm rpcgen
|
|
.Nd an RPC protocol compiler
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Ar infile
|
|
.Nm
|
|
.Op Fl a
|
|
.Op Fl b
|
|
.Op Fl C
|
|
.Oo
|
|
.Fl D Ns Ar name Ns Op Ar =value
|
|
.Oc
|
|
.Op Fl i Ar size
|
|
.Op Fl I Fl P Op Fl K Ar seconds
|
|
.Op Fl L
|
|
.Op Fl M
|
|
.Op Fl N
|
|
.Op Fl T
|
|
.Op Fl Y Ar pathname
|
|
.Ar infile
|
|
.Nm
|
|
.Oo
|
|
.Fl c |
|
|
.Fl h |
|
|
.Fl l |
|
|
.Fl m |
|
|
.Fl t |
|
|
.Fl \&Sc |
|
|
.Fl \&Ss |
|
|
.Fl \&Sm
|
|
.Oc
|
|
.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 AVAILABILITY
|
|
.\" .LP
|
|
.\" SUNWcsu
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
utility 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).
|
|
.Pp
|
|
The
|
|
.Nm
|
|
utility is normally used as in the first synopsis where
|
|
it takes an input file and generates three output files.
|
|
If the
|
|
.Ar infile
|
|
is named
|
|
.Pa proto.x ,
|
|
then
|
|
.Nm
|
|
generates a header in
|
|
.Pa proto.h ,
|
|
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 also generates the
|
|
.Tn RPC
|
|
dispatch table in
|
|
.Pa proto_tbl.i .
|
|
.Pp
|
|
The
|
|
.Nm
|
|
utility can also generate sample client and server files
|
|
that can be customized to suit a particular application.
|
|
The
|
|
.Fl \&Sc ,
|
|
.Fl \&Ss
|
|
and
|
|
.Fl \&Sm
|
|
options generate sample client, server and makefile, respectively.
|
|
The
|
|
.Fl a
|
|
option generates all files, including sample files.
|
|
If the
|
|
.Ar infile
|
|
is
|
|
.Pa proto.x ,
|
|
then the client side sample file is written to
|
|
.Pa proto_client.c ,
|
|
the server side sample file to
|
|
.Pa proto_server.c
|
|
and the sample makefile to
|
|
.Pa makefile.proto .
|
|
.Pp
|
|
If option
|
|
.Fl I
|
|
is set,
|
|
the server created can be started both by the port monitors
|
|
(for example,
|
|
.Xr inetd 8 )
|
|
or by itself.
|
|
When it is started by a port monitor,
|
|
it creates servers only for the transport for which
|
|
the file descriptor
|
|
.Em 0
|
|
was passed.
|
|
The name of the transport may be specified
|
|
by setting up the environment variable
|
|
.Ev NLSPROVIDER .
|
|
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.
|
|
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
|
|
.Em RPC_SVC_FG
|
|
can be used to run the server process in foreground.
|
|
.Pp
|
|
The second synopsis provides special features which allow
|
|
for the creation of more sophisticated
|
|
.Tn RPC
|
|
servers.
|
|
These features include support for user provided
|
|
.Em #defines
|
|
and
|
|
.Tn RPC
|
|
dispatch tables.
|
|
The entries in the
|
|
.Tn RPC
|
|
dispatch table contain:
|
|
.Bl -bullet -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
|
|
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.
|
|
.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.
|
|
See the
|
|
.Sx EXAMPLES
|
|
section below for examples of
|
|
.Nm
|
|
usage.
|
|
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
|
|
.Ar netid .
|
|
If
|
|
.Ar infile
|
|
is not specified,
|
|
.Nm
|
|
accepts the standard input.
|
|
.Pp
|
|
The C preprocessor,
|
|
.Em cc -E
|
|
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 indent
|
|
.It RPC_HDR
|
|
defined when compiling into headers
|
|
.It RPC_XDR
|
|
defined when compiling into XDR routines
|
|
.It RPC_SVC
|
|
defined when compiling into server-side stubs
|
|
.It RPC_CLNT
|
|
defined when compiling into client-side stubs
|
|
.It RPC_TBL
|
|
defined when compiling into RPC dispatch tables
|
|
.El
|
|
.Pp
|
|
Any line beginning with
|
|
.Dq %
|
|
is passed directly into the output file,
|
|
uninterpreted by
|
|
.Nm .
|
|
To specify the path name of the C preprocessor use
|
|
.Fl Y
|
|
flag.
|
|
.Pp
|
|
For every data type referred to in
|
|
.Ar infile ,
|
|
.Nm
|
|
assumes that there exists a
|
|
routine with the string
|
|
.Em 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
|
|
.Xr xdr 3
|
|
routines.
|
|
.Sh OPTIONS
|
|
The following options are available:
|
|
.Bl -tag -width indent
|
|
.It Fl a
|
|
Generate all files, including sample files.
|
|
.It Fl b
|
|
Backward compatibility mode.
|
|
Generate transport specific
|
|
.Tn RPC
|
|
code for older versions
|
|
of the operating system.
|
|
.It Fl c
|
|
Compile into
|
|
.Tn XDR
|
|
routines.
|
|
.It Fl C
|
|
Generate ANSI C code.
|
|
This is always done, the flag is only provided for backwards compatibility.
|
|
.It Fl D Ns Ar name
|
|
.It Fl D Ns Ar name=value
|
|
.\".It Fl D Ns Ar name Ns Op Ar =value
|
|
Define a symbol
|
|
.Ar name .
|
|
Equivalent to the
|
|
.Em #define
|
|
directive in the source.
|
|
If no
|
|
.Ar value
|
|
is given,
|
|
.Ar value
|
|
is defined as
|
|
.Em 1 .
|
|
This option may be specified more than once.
|
|
.It Fl h
|
|
Compile into C data-definitions (a header).
|
|
.Fl T
|
|
option can be used in conjunction to produce a
|
|
header which supports
|
|
.Tn RPC
|
|
dispatch tables.
|
|
.It Fl i Ar size
|
|
Size at which to start generating inline code.
|
|
This option is useful for optimization.
|
|
The default size is 5.
|
|
.Pp
|
|
Note: in order to provide backwards compatibility with the older
|
|
.Nm
|
|
on the
|
|
.Fx
|
|
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.
|
|
.It Fl I
|
|
Compile support for
|
|
.Xr inetd 8
|
|
in the server side stubs.
|
|
Such servers can be self-started or can be started by
|
|
.Xr inetd 8 .
|
|
When the server is self-started, it backgrounds itself by default.
|
|
A special define symbol
|
|
.Em RPC_SVC_FG
|
|
can be used to run the
|
|
server process in foreground, or the user may simply compile without
|
|
the
|
|
.Fl I
|
|
option.
|
|
.Pp
|
|
If there are no pending client requests, the
|
|
.Xr inetd 8
|
|
servers exit after 120 seconds (default).
|
|
The default can be changed with the
|
|
.Fl K
|
|
option.
|
|
All the error messages for
|
|
.Xr inetd 8
|
|
servers
|
|
are always logged with
|
|
.Xr syslog 3 .
|
|
.Pp
|
|
Note:
|
|
Contrary to some systems, in
|
|
.Fx
|
|
this option is needed to generate
|
|
servers that can be invoked through portmonitors and
|
|
.Xr inetd 8 .
|
|
.Pp
|
|
.It Fl K Ar seconds
|
|
By default, services created using
|
|
.Nm
|
|
and invoked through
|
|
port monitors 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,
|
|
use
|
|
.Fl K Ar 0 .
|
|
To create a server that never exits, the appropriate argument is
|
|
.Fl K Ar -1 .
|
|
.Pp
|
|
When monitoring for a server,
|
|
some portmonitors
|
|
.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
|
|
.Fl K Ar 0 .
|
|
.It Fl l
|
|
Compile into client-side stubs.
|
|
.It Fl L
|
|
When the servers are started in foreground, use
|
|
.Xr syslog 3
|
|
to log the server errors instead of printing them on the standard
|
|
error.
|
|
.It Fl m
|
|
Compile into server-side stubs,
|
|
but do not generate a
|
|
.Qq main
|
|
routine.
|
|
This option is useful for doing callback-routines
|
|
and for users who need to write their own
|
|
.Qq main
|
|
routine to do initialization.
|
|
.It Fl M
|
|
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
|
|
.Xr rpc_svc_calls 3
|
|
functions are not yet MT-safe, which means that rpcgen generated server-side
|
|
code will not be MT-safe.
|
|
.It Fl N
|
|
Allow 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
|
|
.Nm
|
|
generated code.
|
|
To maintain backward compatibility,
|
|
this option is not the default.
|
|
.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
|
|
.Fl ( c ,
|
|
.Fl h ,
|
|
.Fl l ,
|
|
.Fl m ,
|
|
.Fl n ,
|
|
.Fl s ,
|
|
.Fl \&Sc ,
|
|
.Fl \&Sm ,
|
|
.Fl \&Ss ,
|
|
and
|
|
.Fl t
|
|
modes only).
|
|
.It Fl P
|
|
Compile support for
|
|
port monitors
|
|
in the server side stubs.
|
|
.Pp
|
|
Note:
|
|
Contrary to some systems, in
|
|
.Fx
|
|
this option is needed to generate
|
|
servers that can be monitored.
|
|
.Pp
|
|
If the
|
|
.Fl I
|
|
option has been specified,
|
|
.Fl P
|
|
is turned off automatically.
|
|
.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).
|
|
This option may be specified more than once.
|
|
Note:
|
|
the transports are chosen at run time and not at compile time.
|
|
.It Fl \&Sc
|
|
Generate sample client code that uses remote procedure calls.
|
|
.It Fl \&Sm
|
|
Generate a sample
|
|
.Pa Makefile
|
|
which can be used for compiling the application.
|
|
.It Fl \&Ss
|
|
Generate sample server code that uses remote procedure calls.
|
|
.It Fl t
|
|
Compile into
|
|
.Tn RPC
|
|
dispatch table.
|
|
.It Fl T
|
|
Generate the code to support
|
|
.Tn RPC
|
|
dispatch tables.
|
|
.Pp
|
|
The options
|
|
.Fl c ,
|
|
.Fl h ,
|
|
.Fl l ,
|
|
.Fl m ,
|
|
.Fl s ,
|
|
.Fl \&Sc ,
|
|
.Fl \&Sm ,
|
|
.Fl \&Ss ,
|
|
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.
|
|
.It Fl Y Ar pathname
|
|
Give the name of the directory where
|
|
.Nm
|
|
will start looking for the C-preprocessor.
|
|
.El
|
|
.Sh EXAMPLES
|
|
The following example:
|
|
.Dl example% rpcgen -T prot.x
|
|
.Pp
|
|
generates all 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)
|
|
to the standard output.
|
|
.Dl example% rpcgen -h prot.x
|
|
.Pp
|
|
To send the test version of the
|
|
.Fl D Ns Ar TEST ,
|
|
server side stubs for
|
|
all the transport belonging to the class
|
|
.Ar datagram_n
|
|
to standard output, use:
|
|
.Dl example% rpcgen -s datagram_n -DTEST prot.x
|
|
.Pp
|
|
To create the server side stubs for the transport indicated
|
|
by
|
|
.Ar netid
|
|
tcp,
|
|
use:
|
|
.Dl example% rpcgen -n tcp -o prot_svc.c prot.x
|
|
.Sh SEE ALSO
|
|
.Xr cc 1 ,
|
|
.Xr rpc 3 ,
|
|
.Xr rpc_svc_calls 3 ,
|
|
.Xr syslog 3 ,
|
|
.Xr xdr 3 ,
|
|
.Xr inetd 8
|
|
.Rs
|
|
.%T The rpcgen chapter in the NETP manual
|
|
.Re
|