1 .\" @(#)rpcgen.1 1.35 93/06/02 SMI
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
333 By default, services created using
336 port monitors wait 120 seconds
337 after servicing a request before exiting.
338 That interval can be changed using the
341 To create a server that exits immediately upon servicing a request,
344 To create a server that never exits, the appropriate argument is
347 When monitoring for a server,
350 spawn a new process in response to a service request.
351 If it is known that a server will be used with such a monitor, the
352 server should exit immediately on completion.
358 Compile into client-side stubs.
360 When the servers are started in foreground, use
362 to log the server errors instead of printing them on the standard
365 Compile into server-side stubs,
366 but do not generate a
369 This option is useful for doing callback-routines
370 and for users who need to write their own
372 routine to do initialization.
374 Generate multithread-safe stubs for passing arguments and results between
375 rpcgen generated code and user written code.
376 This option is useful
377 for users who want to use threads in their code.
380 functions are not yet MT-safe, which means that rpcgen generated server-side
381 code will not be MT-safe.
383 Allow procedures to have multiple arguments.
384 It also uses the style of parameter passing that closely resembles C.
385 So, when passing an argument to a remote procedure, you do not have to
386 pass a pointer to the argument, but can pass the argument itself.
387 This behavior is different from the old style of
390 To maintain backward compatibility,
391 this option is not the default.
393 Compile into server-side stubs for the transport
396 There should be an entry for
400 This option may be specified more than once,
401 so as to compile a server that serves multiple transports.
403 Specify the name of the output file.
404 If none is specified,
405 standard output is used
421 in the server side stubs.
424 Contrary to some systems, in
426 this option is needed to generate
427 servers that can be monitored.
431 option has been specified,
433 is turned off automatically.
435 Compile into server-side stubs for all the
436 transports belonging to the class
438 The supported classes are
450 for the meanings associated with these classes).
451 This option may be specified more than once.
453 the transports are chosen at run time and not at compile time.
455 Generate sample client code that uses remote procedure calls.
459 which can be used for compiling the application.
461 Generate sample server code that uses remote procedure calls.
467 Generate the code to support
482 are used exclusively to generate a particular type of file,
487 are global and can be used with the other options.
489 Give the name of the directory where
491 will start looking for the C-preprocessor.
496 environment variable is set, its value is used as the command line of the
497 C preprocessor to be run on the input file.
499 The following example:
500 .Dl example% rpcgen -T prot.x
502 generates all the five files:
510 The following example sends the C data-definitions (header)
511 to the standard output.
512 .Dl example% rpcgen -h prot.x
514 To send the test version of the
516 server side stubs for
517 all the transport belonging to the class
519 to standard output, use:
520 .Dl example% rpcgen -s datagram_n -DTEST prot.x
522 To create the server side stubs for the transport indicated
527 .Dl example% rpcgen -n tcp -o prot_svc.c prot.x
531 .Xr rpc_svc_calls 3 ,
536 .%T The rpcgen chapter in the NETP manual