[unix-history] / 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.
Commit	Line	Data
9a4767d3 C	1	.\" from: @(#)rpcgen.1 2.2 88/08/02 4.0 RPCSRC
	2	.\" $Id: rpcgen.1,v 1.4 1993/08/01 07:29:24 mycroft Exp $
	3	.\"
	4	.Dd January 18, 1988
	5	.Dt RPCGEN 1
	6	.Os
	7	.Sh NAME
	8	.Nm rpcgen
	9	.Nd RPC protocol compiler
	10	.Sh SYNOPSIS
	11	.Nm rpcgen
	12	.Ar infile
	13	.Nm rpcgen
	14	.Fl c Li \|
	15	.Fl h Li \|
	16	.Fl l Li \|
	17	.Fl m
	18	.Op Fl o Ar outfile
	19	.Op Ar infile
	20	.Nm rpcgen
	21	.Fl s Ar transport
	22	.Op Fl o Ar outfile
	23	.Op Ar infile
	24	.Sh DESCRIPTION
	25	.Nm rpcgen
	26	is a tool that generates C code to implement an
	27	.Tn RPC
	28	protocol. The input to
	29	.Nm rpcgen
	30	is a language similar to C known as
	31	.Tn RPC
	32	Language (Remote Procedure Call Language). Information about the
	33	syntax of
	34	.Tn RPC
	35	Language is available in the
	36	.Rs
	37	.%T "rpcgen Programming Guide"
	38	.Re
	39	.Pp
	40	.Nm rpcgen
	41	is normally used as in the first synopsis where it takes an input file
	42	and generates four output files. If the
	43	.Ar infile
	44	is named
	45	.Pa proto.x ,
	46	then
	47	.Nm rpcgen
	48	will generate a header file in
	49	.Pa proto.h ,
	50	.Tn XDR
	51	routines in
	52	.Pa proto_xdr.c ,
	53	server-side stubs in
	54	.Pa proto_svc.c ,
	55	and client-side stubs in
	56	.Pa proto_clnt.c .
	57	.Pp
	58	The other synopses shown above are used when one does not want to
	59	generate all the output files, but only a particular one.
	60	.\" Their usage is described in the
	61	.\" .Sx USAGE
	62	.\" section below.
	63	.Pp
	64	The C-preprocessor,
65	.Xr cpp 1 ,
66	is run on all input files before they are actually
67	interpreted by
68	.Nm rpcgen ,
69	so all the
70	.Xr cpp
71	directives are legal within an
72	.Nm rpcgen
73	input file. For each type of output file,
74	.Nm rpcgen
75	defines a special
76	.Xr cpp
77	symbol for use by the
78	.Nm rpcgen
79	programmer:
80	.Pp
81	.Bl -tag -width RPC_CLNT -compact
82	.It Dv RPC_HDR
83	defined when compiling into header files
84	.It Dv RPC_XDR
85	defined when compiling into
86	.Tn XDR
87	routines
88	.It Dv RPC_SVC
89	defined when compiling into server-side stubs
90	.It Dv RPC_CLNT
91	defined when compiling into client-side stubs
92	.El
93	.Pp
94	In addition,
95	.Nm rpcgen
96	does a little preprocessing of its own. Any line beginning with
97	.Sq %
98	is passed directly into the output file, uninterpreted by
99	.Nm rpcgen .
100	.Pp
101	You can customize some of your
102	.Tn XDR
103	routines by leaving those data types undefined. For every data type
104	that is undefined,
105	.Nm rpcgen
106	will assume that there exists a routine with the name
107	.Tn xdr_
108	prepended to the name of the undefined type.
109	.Sh OPTIONS
110	.Bl -tag -width indent
111	.It Fl c
112	Compile into
113	.Tn XDR
114	routines.
115	.It Fl h
116	Compile into C data-definitions (a header file).
117	.It Fl l
118	Compile into client-side stubs.
119	.It Fl m
120	Compile into server-side stubs, but do not generate a
121	.Fn main
122	routine. This option is useful for doing callback-routines and for
123	people who need to write their own
124	.Fn main
125	routine to do initialization.
126	.It Fl o Ar outfile
127	Specify the name of the output file. If none is specified, standard
128	output is used (
129	.Fl c ,
130	.Fl h ,
131	.Fl l
132	and
133	.Fl s
134	modes only).
135	.It Fl s Ar transport
136	Compile into server-side stubs, using the the given transport. The
137	supported transports are
138	.Tn udp
139	and
140	.Tn tcp .
141	This option may be invoked more than once so as to compile a server
142	that serves multiple transports.
143	.El
144	.Sh SEE ALSO
145	.Xr cpp 1
146	.Rs
147	.%T "rpcgen Programming Guide"
148	.Re
149	.Sh BUGS
150	Nesting is not supported. As a work-around, structures can be
151	declared at top-level, and their name used inside other structures in
152	order to achieve the same effect.
153	.Pp
154	Name clashes can occur when using program definitions, since the
155	apparent scoping does not really apply. Most of these can be avoided
156	by giving unique names for programs, versions, procedures and types.