NetBSD/usr.bin/rpcgen/rpcgen.1

.\"	from: @(#)rpcgen.1	2.2 88/08/02 4.0 RPCSRC
.\"	$Id: rpcgen.1,v 1.4 1993/08/01 07:29:24 mycroft Exp $
.\"
.Dd January 18, 1988
.Dt RPCGEN 1
.Os
.Sh NAME
.Nm rpcgen
.Nd RPC protocol compiler
.Sh SYNOPSIS
.Nm rpcgen
.Ar infile
.Nm rpcgen
.Fl c Li |
.Fl h Li |
.Fl l Li |
.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 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
.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 ,
.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 .
.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 -compact
.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
.El
.Pp
In addition,
.Nm rpcgen
does a little preprocessing of its own.  Any line beginning with
.Sq %
is passed directly into the output file, uninterpreted by
.Nm rpcgen .
.Pp
You can customize some of your
.Tn 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
.Tn xdr_
prepended to the name of the undefined type.
.Sh OPTIONS
.Bl -tag -width indent
.It Fl c
Compile into
.Tn XDR
routines.
.It Fl h
Compile into 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 
.Fn main
routine.  This option is useful for doing callback-routines and for
people who need to write their own 
.Fn 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 (
.Fl c , 
.Fl h , 
.Fl l 
and
.Fl s
modes only).
.It Fl s Ar transport
Compile into server-side stubs, using the 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
.Sh SEE ALSO
.Xr cpp 1
.Rs
.%T "rpcgen Programming Guide"
.Re
.Sh BUGS
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.