Initial revision
[nfs-utils.git] / tools / rpcgen / rpcgen.new.1
1 .\" @(#)rpcgen.new.1    1.1 90/11/09 TIRPC 1.0; from 40.10 of 10/10/89
2 .\" Copyright (c) 1988,1990 Sun Microsystems, Inc. - All Rights Reserved.
3 .nr X
4 .if \nX=0 .ds x} rpcgen 1 "" "\&"
5 .if \nX=1 .ds x} rpcgen 1 ""
6 .if \nX=2 .ds x} rpcgen 1 "" "\&"
7 .if \nX=3 .ds x} rpcgen "" "" "\&"
8 .TH \*(x}
9 .SH NAME
10 \f4rpcgen\f1 \- an RPC protocol compiler
11 .SH SYNOPSIS
12 .ft 4
13 .nf
14 rpcgen \f2infile\f4
15 .fi
16 .ft 1
17 .br
18 .ft 4
19 .nf
20 rpcgen [\-D\f2name\f4[=\f2value\f4]] [\-T] [\-K \f2secs\fP] \f2infile\f4
21 .fi
22 .ft 1
23 .br
24 .ft 4
25 .nf
26 rpcgen \-c|\-h|\-l|\-m|\-t [\-o \f2outfile\f4 ] \f2infile\f4
27 .fi
28 .ft 1
29 .br
30 .ft 4
31 .nf
32 rpcgen \-s \f2nettype\f4 [\-o \f2outfile\f4] \f2infile\f4
33 .fi
34 .ft 1
35 .br
36 .ft 4
37 .nf
38 rpcgen \-n \f2netid\f4 [\-o \f2outfile\f4] \f2infile\f4
39 .ft 1
40 .SH DESCRIPTION
41 .P
42 \f4rpcgen\f1
43 is a tool that generates C code to implement an RPC protocol.
44 The input to
45 \f4rpcgen\f1
46 is a language similar to C known as
47 RPC Language (Remote Procedure Call Language).
48 .P
49 \f4rpcgen\f1
50 is normally used as in the first synopsis where 
51 it takes an input file and generates up to four output files.
52 If the
53 \f2infile\f1
54 is named
55 \f4proto.x\f1,
56 then
57 \f4rpcgen\f1
58 will generate a header file in
59 \f4proto.h\f1,
60 XDR routines in
61 \f4proto_xdr.c\f1,
62 server-side stubs in
63 \f4proto_svc.c\f1,
64 and client-side stubs in
65 \f4proto_clnt.c\f1.
66 With the
67 \f4\-T\f1
68 option,
69 it will also generate the RPC dispatch table in
70 \f4proto_tbl.i\f1.
71 With the
72 \f4\-Sc\f1
73 option,
74 it will also generate  sample code which would illustrate how to use the
75 remote procedures on the client side. This code would be created in 
76 \f4proto_client.c\f1.
77 With the
78 \f4\-Ss\f1
79 option,
80 it will also generate a sample server code which would illustrate how to write
81 the remote procedures. This code would be created in 
82 \f4proto_server.c\f1.
83 .P
84 The server created can be started both by the port monitors
85 (for example, \f4inetd\f1 or \f4listen\f1)
86 or by itself.
87 When it is started by a port monitor,
88 it creates servers only for the transport for which 
89 the file descriptor \f40\fP was passed.
90 The name of the transport must be specified
91 by setting up the environmental variable
92 \f4PM_TRANSPORT\f1.
93 When the server generated by
94 \f4rpcgen\f1
95 is executed,
96 it creates server handles for all the transports
97 specified in
98 \f4NETPATH\f1
99 environment variable,
100 or if it is unset,
101 it creates server handles for all the visible transports from
102 \f4/etc/netconfig\f1
103 file.
104 Note:
105 the transports are chosen at run time and not at compile time.
106 When the server is self-started,
107 it backgrounds itself by default.
108 A special define symbol
109 \f4RPC_SVC_FG\f1
110 can be used to run the server process in foreground.
111 .P
112 The second synopsis provides special features which allow
113 for the creation of more sophisticated RPC servers.
114 These features include support for user provided
115 \f4#defines\f1
116 and RPC dispatch tables.
117 The entries in the RPC dispatch table contain:
118 .RS
119 .PD 0
120 .TP 3
121 \(bu
122 pointers to the service routine corresponding to that procedure,
123 .TP
124 \(bu
125 a pointer to the input and output arguments
126 .TP
127 \(bu
128 the size of these routines
129 .PD
130 .RE
131 A server can use the dispatch table to check authorization 
132 and then to execute the service routine; 
133 a client library may use it to deal with the details of storage
134 management and XDR data conversion.
135 .P
136 The other three synopses shown above are used when 
137 one does not want to generate all the output files,
138 but only a particular one.
139 Some examples of their usage is described in the
140 EXAMPLE
141 section below.
142 When 
143 \f4rpcgen\f1
144 is executed with the
145 \f4\-s\f1
146 option,
147 it creates servers for that particular class of transports.
148 When
149 executed with the
150 \f4\-n\f1
151 option,
152 it creates a server for the transport specified by
153 \f2netid\f1.
154 If
155 \f2infile\f1
156 is not specified,
157 \f4rpcgen\f1
158 accepts the standard input.
159 .P
160 The C preprocessor,
161 \f4cc \-E\f1
162 [see \f4cc\fP(1)],
163 is run on the input file before it is actually interpreted by
164 \f4rpcgen\f1.
165 For each type of output file,
166 \f4rpcgen\f1
167 defines a special preprocessor symbol for use by the
168 \f4rpcgen\f1
169 programmer:
170 .P
171 .PD 0
172 .TP 12
173 \f4RPC_HDR\f1
174 defined when compiling into header files
175 .TP
176 \f4RPC_XDR\f1
177 defined when compiling into XDR routines
178 .TP
179 \f4RPC_SVC\f1
180 defined when compiling into server-side stubs
181 .TP
182 \f4RPC_CLNT\f1
183 defined when compiling into client-side stubs
184 .TP
185 \f4RPC_TBL\f1
186 defined when compiling into RPC dispatch tables
187 .PD
188 .P
189 Any line beginning with
190 `\f4%\f1'
191 is passed directly into the output file,
192 uninterpreted by
193 \f4rpcgen\f1.
194 .P
195 For every data type referred to in
196 \f2infile\f1,
197 \f4rpcgen\f1
198 assumes that there exists a
199 routine with the string
200 \f4xdr_\f1
201 prepended to the name of the data type.
202 If this routine does not exist in the RPC/XDR
203 library, it must be provided.
204 Providing an undefined data type
205 allows customization of XDR routines.
206 .br
207 .ne 10
208 .P
209 The following options are available:
210 .TP
211 \f4\-a\f1
212 Generate all the files including sample code for client and server side.
213 .TP
214 \f4\-b\f1
215 This generates code for the SunOS4.1 style of rpc. It is only
216 for backward compatibilty. By default rpcgen generates code for
217 Transport Independent RPC that is in Svr4 systems.
218 .TP
219 \f4\-c\f1
220 Compile into XDR routines.
221 .TP
222 \f4\-C\f1
223 Generate code in ANSI C. This option also generates code that could be
224 compiled with the C++ compiler.
225 .TP
226 \f4\-D\f2name\f4[=\f2value\f4]\f1
227 Define a symbol
228 \f2name\f1.
229 Equivalent to the
230 \f4#define\f1
231 directive in the source.
232 If no
233 \f2value\f1
234 is given,
235 \f2value\f1
236 is defined as \f41\f1.
237 This option may be specified more than once.
238 .TP
239 \f4\-h\f1
240 Compile into
241 \f4C\f1
242 data-definitions (a header file).
243 \f4\-T\f1
244 option can be used in conjunction to produce a 
245 header file which supports RPC dispatch tables.
246 .TP
247 \f4-K\f2 secs\f1
248 By default, services created using \f4rpcgen\fP wait \f4120\fP seconds
249 after servicing a request before exiting.
250 That interval can be changed using the \f4-K\fP flag.
251 To create a server that exits immediately upon servicing a request,
252 \f4-K\ 0\fP can be used.
253 To create a server that never exits, the appropriate argument is
254 \f4-K\ -1\fP.
255 .IP
256 When monitoring for a server,
257 some portmonitors, like
258 \f4listen\fP(1M),
259 .I always
260 spawn a new process in response to a service request.
261 If it is known that a server will be used with such a monitor, the
262 server should exit immediately on completion.
263 For such servers, \f4rpcgen\fP should be used with \f4-K\ -1\fP.
264 .TP
265 \f4\-l\f1
266 Compile into client-side stubs.
267 .TP
268 \f4\-m\f1
269 Compile into server-side stubs,
270 but do not generate a \(lqmain\(rq routine.
271 This option is useful for doing callback-routines 
272 and for users who need to write their own 
273 \(lqmain\(rq routine to do initialization.
274 .TP
275 \f4\-n \f2netid\f1
276 Compile into server-side stubs for the transport
277 specified by
278 \f2netid\f1.
279 There should be an entry for
280 \f2netid\f1
281 in the
282 netconfig database.
283 This option may be specified more than once,
284 so as to compile a server that serves multiple transports.
285 .TP
286 \f4\-N\f1
287 Use the newstyle of rpcgen. This allows procedures to have multiple arguments. 
288 It also uses the style of parameter passing that closely resembles C. So, when 
289 passing an argument to a remote procedure you do not have to pass a pointer to
290 the argument but the argument itself. This behaviour is different from the oldstyle
291 of rpcgen generated code. The newstyle is not the default case because of 
292 backward compatibility.
293 .TP
294 \f4\-o \f2outfile\f1
295 Specify the name of the output file.
296 If none is specified,
297 standard output is used
298 (\f4\-c\f1,
299 \f4\-h\f1,
300 \f4\-l\f1,
301 \f4\-m\f1,
302 \f4\-n\f1,
303 \f4\-s\f1,
304 \f4\-s\Sc,
305 \f4\-s\Ss
306 and
307 \f4\-t\f1
308 modes only).
309 .TP
310 \f4\-s \f2nettype\f1
311 Compile into server-side stubs for all the 
312 transports belonging to the class
313 \f2nettype\f1.
314 The supported classes are
315 \f4netpath\f1,
316 \f4visible\f1,
317 \f4circuit_n\f1,
318 \f4circuit_v\f1,
319 \f4datagram_n\f1,
320 \f4datagram_v\f1,
321 \f4tcp\f1,
322 and
323 \f4udp\f1
324 [see \f4rpc\fP(3N)
325 for the meanings associated with these classes].
326 This option may be specified more than once.
327 Note:
328 the transports are chosen at run time and not at compile time.
329 .TP
330 \f4\-Sc\f1
331 Generate sample code to show the use of remote procedure and how to bind
332 to the server before calling the client side stubs generated by rpcgen.
333 .TP
334 \f4\-Ss\f1
335 Generate skeleton code for the remote procedures on the server side. You would need
336 to fill in the actual code for the remote procedures.
337 .TP
338 \f4\-t\f1
339 Compile into RPC dispatch table.
340 .TP
341 \f4\-T\f1
342 Generate the code to support RPC dispatch tables.
343 .P
344 The options 
345 \f4\-c\f1,
346 \f4\-h\f1,
347 \f4\-l\f1,
348 \f4\-m\f1,
349 \f4\-s\f1
350 and
351 \f4\-t\f1
352 are used exclusively to generate a particular type of file,
353 while the options
354 \f4\-D\f1
355 and
356 \f4\-T\f1
357 are global and can be used with the other options.
358 .br
359 .ne 5
360 .SH NOTES
361 The RPC Language does not support nesting of structures.
362 As a work-around,
363 structures can be declared at the top-level,
364 and their name used inside other structures in 
365 order to achieve the same effect.
366 .P
367 Name clashes can occur when using program definitions,
368 since the apparent scoping does not really apply.
369 Most of these can be avoided by giving 
370 unique names for programs,
371 versions,
372 procedures and types.
373 .P
374 The server code generated with
375 \f4\-n\f1
376 option refers to the transport indicated by
377 \f2netid\f1
378 and hence is very site specific.
379 .SH EXAMPLE
380 The following example:
381 .IP
382 .ft 4
383 $ rpcgen \-T prot.x
384 .ft 1
385 .P
386 generates the five files:
387 \f4prot.h\f1,
388 \f4prot_clnt.c\f1,
389 \f4prot_svc.c\f1,
390 \f4prot_xdr.c\f1
391 and
392 \f4prot_tbl.i\f1.
393 .P
394 The following example sends the C data-definitions (header file)
395 to the standard output.
396 .IP
397 .ft 4
398 $ rpcgen \-h prot.x
399 .ft 1
400 .P
401 To send the test version of the
402 \f4-DTEST\f1,
403 server side stubs for 
404 all the transport belonging to the class
405 \f4datagram_n\f1
406 to standard output, use:
407 .IP
408 .ft 4
409 $ rpcgen \-s datagram_n \-DTEST prot.x
410 .ft 1
411 .P
412 To create the server side stubs for the transport indicated
413 by
414 \f2netid\f1
415 \f4tcp\f1,
416 use:
417 .IP
418 .ft 4
419 $ rpcgen \-n tcp \-o prot_svc.c prot.x
420 .ft 1
421 .SH "SEE ALSO"
422 \f4cc\fP(1).