1 .\" @(#)rpcgen.1 1.35 93/06/02 SMI
3 .\" Copyright 1985-1993 Sun Microsystems, Inc.
9 .Nd an RPC protocol compiler
18 .Fl D Ns Ar name Ns Op Ar =value
21 .Op Fl I Op Fl K Ar seconds
54 is a tool that generates C code to implement an
59 is a language similar to C known as
61 Language (Remote Procedure Call Language).
64 is normally used as in the first synopsis where
65 it takes an input file and generates three output files.
78 and client-side stubs in
89 can also generate sample client and server files
90 that can be customized to suit a particular application. The
95 options generate sample client, server and makefile, respectively.
98 option generates all files, including sample files. If the
102 then the client side sample file is written to
104 the server side sample file to
106 and the sample makefile to
109 The server created can be started both by the port monitors
113 When it is started by a port monitor,
114 it creates servers only for the transport for which
118 The name of the transport must be specified
119 by setting up the environment variable
121 When the server generated by
124 it creates server handles for all the transports
127 environment variable,
129 it creates server handles for all the visible transports from
133 the transports are chosen at run time and not at compile time.
134 When the server is self-started,
135 it backgrounds itself by default.
136 A special define symbol
138 can be used to run the server process in foreground.
140 The second synopsis provides special features which allow
141 for the creation of more sophisticated
144 These features include support for user provided
151 dispatch table contain:
152 .Bl -bullet -offset indent -compact
154 pointers to the service routine corresponding to that procedure,
156 a pointer to the input and output arguments,
158 the size of these routines.
160 A server can use the dispatch table to check authorization
161 and then to execute the service routine;
162 a client library may use it to deal with the details of storage
163 management and XDR data conversion.
165 The other three synopses shown above are used when
166 one does not want to generate all the output files,
167 but only a particular one.
170 section below for examples of
178 it creates servers for that particular class of transports.
183 it creates a server for the transport specified by
189 accepts the standard input.
193 is run on the input file before it is actually interpreted by
195 For each type of output file,
197 defines a special preprocessor symbol for use by the
200 .Bl -tag -width indent
202 defined when compiling into headers
204 defined when compiling into XDR routines
206 defined when compiling into server-side stubs
208 defined when compiling into client-side stubs
210 defined when compiling into RPC dispatch tables
213 Any line beginning with
215 is passed directly into the output file,
218 To specify the path name of the C preprocessor use
222 For every data type referred to in
225 assumes that there exists a
226 routine with the string
228 prepended to the name of the data type.
229 If this routine does not exist in the
231 library, it must be provided.
232 Providing an undefined data type
233 allows customization of
237 The following options are available:
238 .Bl -tag -width indent
240 Generate all files, including sample files.
242 Backward compatibility mode.
243 Generate transport specific
245 code for older versions
246 of the operating system.
250 this compatibility flag is turned on by
253 supports only the older
261 Generate header and stub files which can be used with
263 C compilers. Headers generated with this flag can also be
264 used with C++ programs.
266 .It Fl D Ns Ar name=value
267 .\".It Fl D Ns Ar name Ns Op Ar =value
272 directive in the source.
279 This option may be specified more than once.
281 Compile into C data-definitions (a header).
283 option can be used in conjunction to produce a
284 header which supports
288 Size at which to start generating inline code.
289 This option is useful for optimization. The default size is 5.
291 Note: in order to provide backwards compatibility with the older
295 platform, the default is actually 0 (which means
296 that inline code generation is disabled by default). You must specify
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 .\" this option is supported for backward compatibility only.
329 .\" generates servers that can be invoked through portmonitors.
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. This option is useful
375 for users who want to use threads in their code. However, the
377 functions are not yet MT-safe, which means that rpcgen generated server-side
378 code will not be MT-safe.
380 This option allows procedures to have multiple arguments.
381 It also uses the style of parameter passing that closely resembles C.
382 So, when passing an argument to a remote procedure, you do not have to
383 pass a pointer to the argument, but can pass the argument itself.
384 This behavior is different from the old style of
387 To maintain backward compatibility,
388 this option is not the default.
390 Compile into server-side stubs for the transport
393 There should be an entry for
397 This option may be specified more than once,
398 so as to compile a server that serves multiple transports.
400 Specify the name of the output file.
401 If none is specified,
402 standard output is used
417 Compile into server-side stubs for all the
418 transports belonging to the class
420 The supported classes are
432 for the meanings associated with these classes).
433 This option may be specified more than once.
435 the transports are chosen at run time and not at compile time.
437 Generate sample client code that uses remote procedure calls.
441 which can be used for compiling the application.
443 Generate sample server code that uses remote procedure calls.
449 Generate the code to support
464 are used exclusively to generate a particular type of file,
469 are global and can be used with the other options.
471 Give the name of the directory where
473 will start looking for the C-preprocessor.
476 The following example:
477 .Dl example% rpcgen -T prot.x
479 generates all the five files:
487 The following example sends the C data-definitions (header)
488 to the standard output.
489 .Dl example% rpcgen -h prot.x
491 To send the test version of the
493 server side stubs for
494 all the transport belonging to the class
496 to standard output, use:
497 .Dl example% rpcgen -s datagram_n -DTEST prot.x
499 To create the server side stubs for the transport indicated
504 .Dl example% rpcgen -n tcp -o prot_svc.c prot.x
510 .\" .BR rpc_svc_calls (3)
512 .%T The Nm rpcgen No chapter in the NETP manual