| blob | 81bca9b1bbaa757fd6ab1b3b797f9906b451caa0 |
1 .\" $NetBSD: rpcgen.1,v 1.21 2008/01/19 14:22:05 hubertf Exp $
2 .\" from: @(#)rpcgen.new.1 1.1 90/11/09 TIRPC 1.0; from 40.10 of 10/10/89
3 .\" Copyright (c) 1988,1990 Sun Microsystems, Inc. - All Rights Reserved.
4 .Dd January 19, 2008
5 .Dt RPCGEN 1
6 .Os
7 .Sh NAME
8 .Nm rpcgen
9 .Nd Remote Procedure Call (RPC) protocol compiler
10 .Sh SYNOPSIS
11 .Nm
12 .Ar infile
13 .Nm
14 .Op Fl A
15 .Op Fl a
16 .Op Fl b
17 .Op Fl C
18 .Op Fl D Ar name Op =value
19 .Op Fl I
20 .Op Fl i Ar size
21 .Op Fl K Ar secs
22 .Op Fl L
23 .Op Fl M
24 .Op Fl N
25 .Op Fl T
26 .Op Fl v
27 .Op Fl Y Ar pathname
28 .Ar infile
29 .Nm
30 .Fl c Li |
31 .Fl h Li |
32 .Fl l Li |
33 .Fl m Li |
34 .Fl t Li |
35 .Fl S\&c Li |
36 .Fl S\&s
37 .\" .Fl S\&m
38 .Op Fl o Ar outfile
39 .Op Ar infile
40 .Nm
41 .Op Fl s Ar nettype
42 .Op Fl o Ar outfile
43 .Op Ar infile
44 .Nm
45 .Op Fl n Ar netid
46 .Op Fl o Ar outfile
47 .Op Ar infile
48 .Sh DESCRIPTION
49 .Nm
50 is a tool that generates C code to implement an
51 .Tn RPC
52 protocol.
53 The input to
54 .Nm
55 is a language similar to C known as
56 .Tn RPC
57 Language (Remote Procedure Call Language).
58 .Nm
59 is normally used as in the first synopsis where
60 it takes an input file and generates up to four output files.
61 If the
62 .Ar infile
63 is named
64 .Pa proto.x ,
65 then
66 .Nm
67 will generate a header file in
68 .Pa proto.h ,
69 .Tn XDR
70 routines in
71 .Pa proto_xdr.c ,
72 server-side stubs in
73 .Pa proto_svc.c ,
74 and client-side stubs in
75 .Pa proto_clnt.c .
76 With the
77 .Fl T
78 option,
79 it will also generate the
80 .Tn RPC
81 dispatch table in
82 .Pa proto_tbl.i .
83 With the
84 .Fl S\&c
85 option,
86 it will also generate sample code which would illustrate how to use the
87 remote procedures on the client side.
88 This code would be created in
89 .Pa proto_client.c .
90 With the
91 .Fl S\&s
92 option,
93 it will also generate a sample server code which would illustrate how to write
94 the remote procedures.
95 This code would be created in
96 .Pa proto_server.c .
97 .Pp
98 The server created can be started both by the port monitors
99 (for example,
100 .Em inetd
101 or
102 .Em listen )
103 or by itself.
104 When it is started by a port monitor,
105 it creates servers only for the transport for which
106 the file descriptor 0 was passed.
107 The name of the transport must be specified
108 by setting up the environmental variable
109 .Ev PM_TRANSPORT .
110 When the server generated by
111 .Nm
112 is executed,
113 it creates server handles for all the transports
114 specified in
115 .Ev NETPATH
116 environment variable,
117 or if it is unset,
118 it creates server handles for all the visible transports from
119 .Pa /etc/netconfig
120 file.
121 .Pp
122 .Em Note :
123 the transports are chosen at run time and not at compile time.
124 When the server is self-started,
125 it backgrounds itself by default.
126 A special define symbol
127 .Dv RPC_SVC_FG
128 can be used to run the server process in foreground.
129 .Pp
130 The second synopsis provides special features which allow
131 for the creation of more sophisticated
132 .Tn RPC
133 servers.
134 These features include support for user provided
135 .Li #defines
136 and
137 .Tn RPC
138 dispatch tables.
139 The entries in the
140 .Tn RPC
141 dispatch table contain:
142 .Pp
143 .Bl -inset -offset indent -compact
144 .It +
145 pointers to the service routine corresponding to that procedure,
146 .It +
147 a pointer to the input and output arguments,
148 .It +
149 the size of these routines
150 .El
151 .Pp
152 A server can use the dispatch table to check authorization
153 and then to execute the service routine;
154 a client library may use it to deal with the details of storage
155 management and
156 .Tn XDR
157 data conversion.
158 .Pp
159 The other three synopses shown above are used when
160 one does not want to generate all the output files,
161 but only a particular one.
162 Some examples of their usage is described in the
163 .Sx EXAMPLES
164 section below.
165 When
166 .Nm
167 is executed with the
168 .Fl s
169 option,
170 it creates servers for that particular class of transports.
171 When
172 executed with the
173 .Fl n
174 option,
175 it creates a server for the transport specified by
176 .Em netid .
177 If
178 .Ar infile
179 is not specified,
180 .Nm
181 accepts the standard input.
182 .Pp
183 The C preprocessor,
184 .Xr cpp 1
185 is run on the input file before it is actually interpreted by
186 .Nm
187 For each type of output file,
188 .Nm
189 defines a special preprocessor symbol for use by the
190 .Nm
191 programmer:
192 .Bl -tag -width RPC_CLNT
193 .It Dv RPC_HDR
194 defined when compiling into header files
195 .It Dv RPC_XDR
196 defined when compiling into
197 .Tn XDR
198 routines
199 .It Dv RPC_SVC
200 defined when compiling into server-side stubs
201 .It Dv RPC_CLNT
202 defined when compiling into client-side stubs
203 .It Dv RPC_TBL
204 defined when compiling into
205 .Tn RPC
206 dispatch tables
207 .El
208 .Pp
209 Any line beginning with
210 .Sq %
211 is passed directly into the output file,
212 uninterpreted by
213 .Nm .
214 .Pp
215 For every data type referred to in
216 .Ar infile
217 .Nm
218 assumes that there exists a
219 routine with the string
220 .Dq xdr_
221 prepended to the name of the data type.
222 If this routine does not exist in the
223 .Tn RPC/XDR
224 library, it must be provided.
225 Providing an undefined data type
226 allows customization of
227 .Tn XDR
228 routines.
229 .Sh OPTIONS
230 .Bl -tag -width indent
231 .It Fl a
232 Generate all the files including sample code for client and server side.
233 .It Fl A
234 Generate an
235 .Fn svc_caller
236 function.
237 .It Fl b
238 Compile stubs in "backwards compatible" mode, disabling support for
239 transport-independent RPC.
240 The
241 .Fl b
242 should always be specified when generating files for
243 .Nx ,
244 since there is no transport-independent RPC support in
245 .Nx .
246 .It Fl c
247 Compile into
248 .Tn XDR
249 routines.
250 .It Fl C
251 Generate code in
252 .Tn ANSI
253 C.
254 This option also generates code that could be compiled with the
255 C++ compiler.
256 .It Fl D Ar name Ns Op Ar =value
257 Define a symbol
258 .Dv name .
259 Equivalent to the
260 .Dv #define
261 directive in the source.
262 If no
263 .Dv value
264 is given,
265 .Dv value
266 is defined as 1.
267 This option may be specified more than once.
268 .It Fl h
269 Compile into C data-definitions (a header file).
270 The
271 .Fl T
272 option can be used in conjunction to produce a
273 header file which supports
274 .Tn RPC
275 dispatch tables.
276 .It Fl i Ar size
277 Size to decide when to start generating inline code.
278 The default size is 3.
279 .It Fl I
280 Support
281 .Xr inetd 8
282 in the server side stubs.
283 Servers generated using this flag can either be standalone or
284 started from
285 .Xr inetd 8 .
286 If a server is started as standalone, then it places itself
287 in the background, unless
288 .Dv RCP_SVC_FG
289 is defined, or the server is compiled without
290 .Fl I .
291 .It Fl K Ar secs
292 By default, services created using
293 .Nm
294 wait 120 seconds
295 after servicing a request before exiting.
296 That interval can be changed using the
297 .Fl K
298 flag.
299 To create a server that exits immediately upon servicing a request,
300 .Dq Fl K No 0
301 can be used.
302 To create a server that never exits, the appropriate argument is
303 .Dq Fl K No -1 .
304 .Pp
305 When monitoring for a server,
306 some port monitors, like the
307 .At V.4
308 utility
309 .Ic listen ,
310 .Em always
311 spawn a new process in response to a service request.
312 If it is known that a server will be used with such a monitor, the
313 server should exit immediately on completion.
314 For such servers,
315 .Nm
316 should be used with
317 .Dq Fl K No -1 .
318 .It Fl l
319 Compile into client-side stubs.
320 .Xr inetd 8 .
321 .It Fl I
322 Compile stubs meant for use in programs started by
323 .Xr inetd 8 .
324 .It Fl L
325 Server errors will be sent to syslog instead of stderr.
326 .It Fl m
327 Compile into server-side stubs,
328 but do not generate a
329 .Fn main
330 routine.
331 This option is useful for doing callback-routines
332 and for users who need to write their own
333 .Fn main
334 routine to do initialization.
335 .It Fl M
336 Generate thread-safe stubs.
337 This alters the calling pattern of client and
338 server stubs so that storage for results is allocated by the caller.
339 Note
340 that all components for a particular service (stubs, client and service
341 wrappers, etc.) must be built either with or without the
342 .Fl M
343 flag.
344 .It Fl N
345 Use the newstyle of
346 .Nm .
347 This allows procedures to have multiple arguments.
348 It also uses the style of parameter passing that closely resembles C.
349 So, when passing an argument to a remote procedure you do not have
350 to pass a pointer to the argument but the argument itself.
351 This behaviour is different from the oldstyle
352 of
353 .Nm
354 generated code.
355 The newstyle is not the default case because of backward compatibility.
356 .It Fl n Ar netid
357 Compile into server-side stubs for the transport
358 specified by
359 .Ar netid .
360 There should be an entry for
361 .Ar netid
362 in the
363 netconfig database.
364 This option may be specified more than once,
365 so as to compile a server that serves multiple transports.
366 .It Fl o Ar outfile
367 Specify the name of the output file.
368 If none is specified,
369 standard output is used
370 .Po
371 .Fl c Fl h Fl l
372 .Fl m Fl n Fl s
373 modes only
374 .Pc
375 .It Fl n Ar netid
376 Specify the transport for the server-side stubs.
377 .Ar netid
378 should be defined in
379 .Xr netconfig 5 .
380 This option can be repeated in order to support more than one transport.
381 .It Fl s Ar nettype
382 Compile into server-side stubs for all the
383 transports belonging to the class
384 .Ar nettype .
385 The supported classes are
386 .Em netpath ,
387 .Em visible ,
388 .Em circuit_n ,
389 .Em circuit_v ,
390 .Em datagram_n ,
391 .Em datagram_v ,
392 .Em tcp ,
393 and
394 .Em udp
395 [see
396 .Xr rpc 3
397 for the meanings associated with these classes.
398 .Em Note :
399 .Bx
400 currently supports only the
401 .Em tcp
402 and
403 .Em udp
404 classes].
405 This option may be specified more than once.
406 .Em Note :
407 the transports are chosen at run time and not at compile time.
408 .It Fl S\&c
409 Generate sample code to show the use of remote procedure and how to bind
410 to the server before calling the client side stubs generated by
411 .Nm .
412 .It Fl S\&s
413 Generate skeleton code for the remote procedures on the server side.
414 You would need
415 to fill in the actual code for the remote procedures.
416 .\" .It Fl S\&m
417 .\" Generate a sample Makefile that can be used to compile the application.
418 .It Fl t
419 Compile into
420 .Tn RPC
421 dispatch table.
422 .It Fl T
423 Generate the code to support
424 .Tn RPC
425 dispatch tables.
426 .It Fl v
427 Display the version number.
428 .It Fl Y Ar pathname
429 Specify the directory where
430 .Nm
431 looks for the C pre-processor.
432 .El
433 .Pp
434 The options
435 .Fl c ,
436 .Fl h ,
437 .Fl l ,
438 .Fl m ,
439 .Fl s ,
440 and
441 .Fl t
442 are used exclusively to generate a particular type of file,
443 while the options
444 .Fl D
445 and
446 .Fl T
447 are global and can be used with the other options.
448 .Sh ENVIRONMENT
449 If the
450 .Ev RPCGEN_CPP
451 environment variable is set, its value is used as the pathname of the
452 C preprocessor to be run on the input file.
453 .Sh NOTES
454 The
455 .Tn RPC
456 Language does not support nesting of structures.
457 As a work-around,
458 structures can be declared at the top-level,
459 and their name used inside other structures in
460 order to achieve the same effect.
461 .Pp
462 Name clashes can occur when using program definitions,
463 since the apparent scoping does not really apply.
464 Most of these can be avoided by giving
465 unique names for programs,
466 versions,
467 procedures and types.
468 .Pp
469 The server code generated with
470 .Fl n
471 option refers to the transport indicated by
472 .Em netid
473 and hence is very site specific.
474 .Sh EXAMPLES
475 The command
476 .Pp
477 .Bd -literal -offset indent
478 $ rpcgen -T prot.x
479 .Ed
480 .Pp
481 generates the five files:
482 .Pa prot.h ,
483 .Pa prot_clnt.c ,
484 .Pa prot_svc.c ,
485 .Pa prot_xdr.c
486 and
487 .Pa prot_tbl.i .
488 .Pp
489 The following example sends the C data-definitions (header file)
490 to standard output.
491 .Pp
492 .Bd -literal -offset indent
493 $ rpcgen -h prot.x
494 .Ed
495 .Pp
496 To send the test version of the
497 .Dv -DTEST ,
498 server side stubs for
499 all the transport belonging to the class
500 .Em datagram_n
501 to standard output, use:
502 .Pp
503 .Bd -literal -offset indent
504 $ rpcgen -s datagram_n -DTEST prot.x
505 .Ed
506 .Pp
507 To create the server side stubs for the transport indicated by
508 .Em netid
509 .Em tcp ,
510 use:
511 .Pp
512 .Bd -literal -offset indent
513 $ rpcgen -n tcp -o prot_svc.c prot.x
514 .Ed
515 .Sh SEE ALSO
516 .Xr cpp 1 ,
517 .Xr inetd 8
518 .Sh HISTORY
519 The
520 .Fl M
521 option was first implemented in RedHat Linux, and was reimplemented by
522 Charles M. Hannum in
523 .Nx 1.6 .