1 .\" @(#)rpcgen.1 1.35 93/06/02 SMI
2 .\" $FreeBSD: src/usr.bin/rpcgen/rpcgen.1,v 1.24 2005/09/02 18:37:34 stefanf Exp $
3 .\" Copyright 1985-1993 Sun Microsystems, Inc.
10 .Nd an RPC protocol compiler
19 .Fl D Ns Ar name Ns Op Ar =value
22 .Op Fl I Fl P Op Fl K Ar seconds
56 utility is a tool that generates C code to implement an
61 is a language similar to C known as
63 Language (Remote Procedure Call Language).
67 utility is normally used as in the first synopsis where
68 it takes an input file and generates three output files.
81 and client-side stubs in
93 utility can also generate sample client and server files
94 that can be customized to suit a particular application.
100 options generate sample client, server and makefile, respectively.
103 option generates all files, including sample files.
108 then the client side sample file is written to
110 the server side sample file to
112 and the sample makefile to
118 the server created can be started both by the port monitors
122 When it is started by a port monitor,
123 it creates servers only for the transport for which
127 The name of the transport may be specified
128 by setting up the environment variable
130 When the server generated by
133 it creates server handles for all the transports
136 environment variable,
138 it creates server handles for all the visible transports from
142 the transports are chosen at run time and not at compile time.
143 When the server is self-started,
144 it backgrounds itself by default.
145 A special define symbol
147 can be used to run the server process in foreground.
149 The second synopsis provides special features which allow
150 for the creation of more sophisticated
153 These features include support for user provided
160 dispatch table contain:
161 .Bl -bullet -offset indent -compact
163 pointers to the service routine corresponding to that procedure,
165 a pointer to the input and output arguments,
167 the size of these routines.
169 A server can use the dispatch table to check authorization
170 and then to execute the service routine;
171 a client library may use it to deal with the details of storage
172 management and XDR data conversion.
174 The other three synopses shown above are used when
175 one does not want to generate all the output files,
176 but only a particular one.
179 section below for examples of
187 it creates servers for that particular class of transports.
192 it creates a server for the transport specified by
198 accepts the standard input.
202 is run on the input file before it is actually interpreted by
204 For each type of output file,
206 defines a special preprocessor symbol for use by the
209 .Bl -tag -width indent
211 defined when compiling into headers
213 defined when compiling into XDR routines
215 defined when compiling into server-side stubs
217 defined when compiling into client-side stubs
219 defined when compiling into RPC dispatch tables
222 Any line beginning with
224 is passed directly into the output file,
227 To specify the path name of the C preprocessor use
231 For every data type referred to in
234 assumes that there exists a
235 routine with the string
237 prepended to the name of the data type.
238 If this routine does not exist in the
240 library, it must be provided.
241 Providing an undefined data type
242 allows customization of
246 The following options are available:
247 .Bl -tag -width indent
249 Generate all files, including sample files.
251 Backward compatibility mode.
252 Generate transport specific
254 code for older versions
255 of the operating system.
261 Generate ANSI C code.
262 This is always done, the flag is only provided for backwards compatibility.
264 .It Fl D Ns Ar name=value
265 .\".It Fl D Ns Ar name Ns Op Ar =value
270 directive in the source.
277 This option may be specified more than once.
279 Compile into C data-definitions (a header).
281 option can be used in conjunction to produce a
282 header which supports
286 Size at which to start generating inline code.
287 This option is useful for optimization.
288 The default size is 5.
290 Note: in order to provide backwards compatibility with the older
294 platform, the default is actually 0 (which means
295 that inline code generation is disabled by default).
297 a non-zero value explicitly to override this default.
301 in the server side stubs.
302 Such servers can be self-started or can be started by
304 When the server is self-started, it backgrounds itself by default.
305 A special define symbol
307 can be used to run the
308 server process in foreground, or the user may simply compile without
313 If there are no pending client requests, the
315 servers exit after 120 seconds (default).
316 The default can be changed with the
319 All the error messages for
322 are always logged with
326 Contrary to some systems, in
328 this option is needed to generate
329 servers that can be invoked through portmonitors and
332 By default, services created using
335 port monitors wait 120 seconds
336 after servicing a request before exiting.
337 That interval can be changed using the
340 To create a server that exits immediately upon servicing a request,
343 To create a server that never exits, the appropriate argument is
346 When monitoring for a server,
349 spawn a new process in response to a service request.
350 If it is known that a server will be used with such a monitor, the
351 server should exit immediately on completion.
357 Compile into client-side stubs.
359 When the servers are started in foreground, use
361 to log the server errors instead of printing them on the standard
364 Compile into server-side stubs,
365 but do not generate a
368 This option is useful for doing callback-routines
369 and for users who need to write their own
371 routine to do initialization.
373 Generate multithread-safe stubs for passing arguments and results between
374 rpcgen generated code and user written code.
375 This option is useful
376 for users who want to use threads in their code.
379 functions are not yet MT-safe, which means that rpcgen generated server-side
380 code will not be MT-safe.
382 Allow procedures to have multiple arguments.
383 It also uses the style of parameter passing that closely resembles C.
384 So, when passing an argument to a remote procedure, you do not have to
385 pass a pointer to the argument, but can pass the argument itself.
386 This behavior is different from the old style of
389 To maintain backward compatibility,
390 this option is not the default.
392 Compile into server-side stubs for the transport
395 There should be an entry for
399 This option may be specified more than once,
400 so as to compile a server that serves multiple transports.
402 Specify the name of the output file.
403 If none is specified,
404 standard output is used
420 in the server side stubs.
423 Contrary to some systems, in
425 this option is needed to generate
426 servers that can be monitored.
430 option has been specified,
432 is turned off automatically.
434 Compile into server-side stubs for all the
435 transports belonging to the class
437 The supported classes are
449 for the meanings associated with these classes).
450 This option may be specified more than once.
452 the transports are chosen at run time and not at compile time.
454 Generate sample client code that uses remote procedure calls.
458 which can be used for compiling the application.
460 Generate sample server code that uses remote procedure calls.
466 Generate the code to support
481 are used exclusively to generate a particular type of file,
486 are global and can be used with the other options.
488 Give the name of the directory where
490 will start looking for the C-preprocessor.
493 The following example:
494 .Dl example% rpcgen -T prot.x
496 generates all the five files:
504 The following example sends the C data-definitions (header)
505 to the standard output.
506 .Dl example% rpcgen -h prot.x
508 To send the test version of the
510 server side stubs for
511 all the transport belonging to the class
513 to standard output, use:
514 .Dl example% rpcgen -s datagram_n -DTEST prot.x
516 To create the server side stubs for the transport indicated
521 .Dl example% rpcgen -n tcp -o prot_svc.c prot.x
525 .Xr rpc_svc_calls 3 ,
530 .%T The rpcgen chapter in the NETP manual