HardenedBSD/lib/librpc/man/man1/rpcgen.1

.\" Copyright 1991 The Regents of the University of California.
.\" All rights reserved.
.\"
.\" Derived from Sun Microsystems rpcgen.1        2.2 88/08/02 4.0 RPCSRC
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"	@(#)rpcgen.1	5.4 (Berkeley) 12/30/93
.\"
.Dd December 30, 1993
.Dt RPCGEN 1
.Sh NAME
.Nm rpcgen
.Nd an
.Tn RPC
protocol compiler
.Sh SYNOPSIS
.Nm rpcgen Ar infile
.Nm rpcgen
.Fl c | Fl h | Fl l |
.Fl m
.Op Fl o Ar outfile
.Op Ar infile
.Nm rpcgen Fl s Ar transport
.Op Fl o Ar outfile
.Op Ar infile
.Sh DESCRIPTION
.Nm rpcgen
is a tool that generates
.Tn \&C
code to implement an
.Tn RPC
protocol.  The input to
.Nm rpcgen
is a language similar to C
known as
.Tn RPC
Language (Remote Procedure Call Language).  Information
about the syntax of
.Tn RPC
Language is available in the
.Rs
.%T "Rpcgen Programming Guide"
.Re
.Pp
Available options:
.Bl -tag -width indent
.It Fl c
Compile into
.Dv XDR
routines.
.It Fl h
Compile into
.Tn \&C
data-definitions (a header file)
.It Fl l
Compile into client-side stubs.
.It Fl m
Compile into server-side stubs, but do not generate a
.Em main
routine.
This option is useful for doing callback-routines and for people who
need to write their own
.Em main
routine to do initialization.
.It Fl o Ar outfile
Specify the name of the output file.
If none is specified, standard output is used
.Pf ( Fl c ,
.Fl h ,
.Fl l
and
.Fl s
modes only).
.It Fl s Ar transport
Compile into server-side stubs, using the given transport.  The
supported transports
are
.Tn UDP
and
.Tn TCP .
This option may be invoked more than once
so as to compile a server that serves multiple transports.
.El
.Pp
.Nm rpcgen
is normally used as in the first synopsis where it takes an input file
and generates four output files. If the
.Ar infile
is named
.Pa proto.x ,
then
.Nm rpcgen
will generate a header file in
.Pa proto.h ,
.Dv XDR
routines in
.Pa proto_xdr.c ,
server-side stubs in
.Pa proto_svc.c ,
and client-side stubs in
.Pa proto_clnt.c .
.Pp
The other synopses shown above are used when one does not want to
generate all the output files, but only a particular one.  Their
usage is described in the
.Sx USAGE
section below.
.Pp
The C-preprocessor,
.Xr cpp 1 ,
is run on all input files before they are actually
interpreted by
.Nm rpcgen ,
so all the
.Xr cpp
directives are legal within an
.Nm rpcgen
input file.  For each type of output file,
.Nm rpcgen
defines a special
.Xr cpp
symbol for use by the
.Nm rpcgen
programmer:
.Pp
.Bl -tag -width "RPC_CLNT"
.It Dv RPC_HDR
defined when compiling into header files
.It Dv RPC_XDR
defined when compiling into
.Dv XDR
routines
.It Dv RPC_SVC
defined when compiling into server-side stubs
.It Dv RPC_CLNT
defined when compiling into client-side stubs
.El
.Pp
In addition,
.Nm rpcgen
does a little preprocessing of its own.
Any line beginning with
.Ql \&%
is passed directly into the output file, uninterpreted by
.Nm rpcgen .
.Pp
You can customize some of your
.Dv XDR
routines by leaving those data
types undefined.  For every data type that is undefined,
.Nm rpcgen
will assume that there exists a routine with the name
.Em xdr_
prepended to the name of the undefined type.
.Sh SEE ALSO
.Xr cpp 1
.Rs
.%T "Rpcgen Programming Guide"
.%I "Sun Microsystems"
.Re
.Sh BUGS
.Pp
Nesting is not supported.
As a work-around, structures can be declared at
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.