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.
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 "" "" "\&"
10 \f4rpcgen\f1 \- an RPC protocol compiler
20 rpcgen [\-D\f2name\f4[=\f2value\f4]] [\-T] [\-K \f2secs\fP] \f2infile\f4
26 rpcgen \-c|\-h|\-l|\-m|\-t [\-o \f2outfile\f4 ] \f2infile\f4
32 rpcgen [\-I] \-s \f2nettype\f4 [\-o \f2outfile\f4] \f2infile\f4
38 rpcgen \-n \f2netid\f4 [\-o \f2outfile\f4] \f2infile\f4
43 is a tool that generates C code to implement an RPC protocol.
46 is a language similar to C known as
47 RPC Language (Remote Procedure Call Language).
50 is normally used as in the first synopsis where
51 it takes an input file and generates up to four output files.
58 will generate a header file in
64 and client-side stubs in
69 it will also generate the RPC dispatch table in
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
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
84 The server created can be started both by the port monitors
85 (for example, \f4inetd\f1 or \f4listen\f1)
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
93 When the server generated by
96 it creates server handles for all the transports
101 it creates server handles for all the visible transports from
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
110 can be used to run the server process in foreground.
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
116 and RPC dispatch tables.
117 The entries in the RPC dispatch table contain:
122 pointers to the service routine corresponding to that procedure,
125 a pointer to the input and output arguments
128 the size of these routines
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.
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
147 it creates servers for that particular class of transports.
152 it creates a server for the transport specified by
158 accepts the standard input.
163 is run on the input file before it is actually interpreted by
165 For each type of output file,
167 defines a special preprocessor symbol for use by the
174 defined when compiling into header files
177 defined when compiling into XDR routines
180 defined when compiling into server-side stubs
183 defined when compiling into client-side stubs
186 defined when compiling into RPC dispatch tables
189 Any line beginning with
191 is passed directly into the output file,
195 For every data type referred to in
198 assumes that there exists a
199 routine with the string
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.
209 The following options are available:
212 Generate all the files including sample code for client and server side.
215 This generates code for the SunOS4.1 style of rpc. It is
216 for backward compatibilty. This is the default.
219 This generates code for the SysVr4 style of rpc. It is used by the
220 Transport Independent RPC that is in Svr4 systems.
221 By default rpcgen generates code for SunOS4.1 stype of rpc.
224 Compile into XDR routines.
227 Generate code in ANSI C. This option also generates code that could be
228 compiled with the C++ compiler. This is the default.
231 Generate code in K&R C. The default is ANSI C.
233 \f4\-D\f2name\f4[=\f2value\f4]\f1
238 directive in the source.
243 is defined as \f41\f1.
244 This option may be specified more than once.
249 data-definitions (a header file).
251 option can be used in conjunction to produce a
252 header file which supports RPC dispatch tables.
255 Generate a service that can be started from inetd. The default is
256 to generate a static service that handles transports selected with \f4\-s\f1.
257 Using \f4\-I\f1 allows starting a service by either method.
260 By default, services created using \f4rpcgen\fP wait \f4120\fP seconds
261 after servicing a request before exiting.
262 That interval can be changed using the \f4-K\fP flag.
263 To create a server that exits immediately upon servicing a request,
264 \f4-K\ 0\fP can be used.
265 To create a server that never exits, the appropriate argument is
268 When monitoring for a server,
269 some portmonitors, like
272 spawn a new process in response to a service request.
273 If it is known that a server will be used with such a monitor, the
274 server should exit immediately on completion.
275 For such servers, \f4rpcgen\fP should be used with \f4-K\ -1\fP.
278 Compile into client-side stubs.
281 Compile into server-side stubs,
282 but do not generate a \(lqmain\(rq routine.
283 This option is useful for doing callback-routines
284 and for users who need to write their own
285 \(lqmain\(rq routine to do initialization.
288 Compile into server-side stubs for the transport
291 There should be an entry for
295 This option may be specified more than once,
296 so as to compile a server that serves multiple transports.
299 Use the newstyle of rpcgen. This allows procedures to have multiple arguments.
300 It also uses the style of parameter passing that closely resembles C. So, when
301 passing an argument to a remote procedure you do not have to pass a pointer to
302 the argument but the argument itself. This behaviour is different from the oldstyle
303 of rpcgen generated code. The newstyle is not the default case because of
304 backward compatibility.
307 Specify the name of the output file.
308 If none is specified,
309 standard output is used
323 Compile into server-side stubs for all the
324 transports belonging to the class
326 The supported classes are
337 for the meanings associated with these classes].
338 This option may be specified more than once.
340 the transports are chosen at run time and not at compile time.
343 Generate sample code to show the use of remote procedure and how to bind
344 to the server before calling the client side stubs generated by rpcgen.
347 Generate skeleton code for the remote procedures on the server side. You would need
348 to fill in the actual code for the remote procedures.
351 Compile into RPC dispatch table.
354 Generate the code to support RPC dispatch tables.
364 are used exclusively to generate a particular type of file,
369 are global and can be used with the other options.
373 The RPC Language does not support nesting of structures.
375 structures can be declared at the top-level,
376 and their name used inside other structures in
377 order to achieve the same effect.
379 Name clashes can occur when using program definitions,
380 since the apparent scoping does not really apply.
381 Most of these can be avoided by giving
382 unique names for programs,
384 procedures and types.
386 The server code generated with
388 option refers to the transport indicated by
390 and hence is very site specific.
392 The following example:
398 generates the five files:
406 The following example sends the C data-definitions (header file)
407 to the standard output.
413 To send the test version of the
415 server side stubs for
416 all the transport belonging to the class
418 to standard output, use:
421 $ rpcgen \-s datagram_n \-DTEST prot.x
424 To create the server side stubs for the transport indicated
431 $ rpcgen \-n tcp \-o prot_svc.c prot.x