1rpcgen(1) User Commands rpcgen(1)
2
3
4
6 rpcgen - an RPC protocol compiler
7
9 rpcgen infile
10
11
12 rpcgen [-a] [-A] [-b] [-C] [-D name [= value]] [-i size]
13 [-I [-K seconds]] [-L] [-M] [-N] [- T] [-v]
14 [-Y pathname] infile
15
16
17 rpcgen [-c | -h | -l | -m | -t | -Sc | -Ss | -Sm]
18 [-o outfile] [infile]
19
20
21 rpcgen [-s nettype] [-o outfile] [infile]
22
23
24 rpcgen [-n netid] [-o outfile] [infile]
25
26
28 The rpcgen utility is a tool that generates C code to implement an RPC
29 protocol. The input to rpcgen is a language similar to C known as RPC
30 Language (Remote Procedure Call Language).
31
32
33 The rpcgen utility is normally used as in the first synopsis where it
34 takes an input file and generates three output files. If the infile is
35 named proto.x, then rpcgen generates a header in proto.h, XDR routines
36 in proto_xdr.c, server-side stubs in proto_svc.c, and client-side stubs
37 in proto_clnt.c. With the -T option, it also generates the RPC dispatch
38 table in proto_tbl.i.
39
40
41 rpcgen can also generate sample client and server files that can be
42 customized to suit a particular application. The -Sc, -Ss, and -Sm
43 options generate sample client, server and makefile, respectively. The
44 -a option generates all files, including sample files. If the infile is
45 proto.x, then the client side sample file is written to proto_client.c,
46 the server side sample file to proto_server.c and the sample makefile
47 to makefile.proto.
48
49
50 The server created can be started both by the port monitors (for exam‐
51 ple, inetd or listen) or by itself. When it is started by a port moni‐
52 tor, it creates servers only for the transport for which the file
53 descriptor 0 was passed. The name of the transport must be specified by
54 setting up the environment variable PM_TRANSPORT. When the server gen‐
55 erated by rpcgen is executed, it creates server handles for all the
56 transports specified in the NETPATH environment variable, or if it is
57 unset, it creates server handles for all the visible transports from
58 the /etc/netconfig file. Note: the transports are chosen at run time
59 and not at compile time. When the server is self-started, it back‐
60 grounds itself by default. A special define symbol RPC_SVC_FG can be
61 used to run the server process in foreground.
62
63
64 The second synopsis provides special features which allow for the cre‐
65 ation of more sophisticated RPC servers. These features include support
66 for user-provided #defines and RPC dispatch tables. The entries in the
67 RPC dispatch table contain:
68
69 o pointers to the service routine corresponding to that proce‐
70 dure
71
72 o a pointer to the input and output arguments
73
74 o the size of these routines
75
76
77 A server can use the dispatch table to check authorization and then to
78 execute the service routine. A client library can use the dispatch ta‐
79 ble to deal with the details of storage management and XDR data conver‐
80 sion.
81
82
83 The other three synopses shown above are used when one does not want to
84 generate all the output files, but only a particular one. See the EXAM‐
85 PLES section below for examples of rpcgen usage. When rpcgen is exe‐
86 cuted with the -s option, it creates servers for that particular class
87 of transports. When executed with the -n option, it creates a server
88 for the transport specified by netid. If infile is not specified, rpc‐
89 gen accepts the standard input.
90
91
92 All the options mentioned in the second synopsis can be used with the
93 other three synopses, but the changes are made only to the specified
94 output file.
95
96
97 The C preprocessor cc -E is run on the input file before it is actually
98 interpreted by rpcgen. For each type of output file, rpcgen defines a
99 special preprocessor symbol for use by the rpcgen programmer:
100
101 RPC_HDR defined when compiling into headers
102
103
104 RPC_XDR defined when compiling into XDR routines
105
106
107 RPC_SVC defined when compiling into server-side stubs
108
109
110 RPC_CLNT defined when compiling into client-side stubs
111
112
113 RPC_TBL defined when compiling into RPC dispatch tables
114
115
116
117 Any line beginning with ``%'' is passed directly into the output file,
118 uninterpreted by rpcgen, except that the leading ``%" is stripped off.
119 To specify the path name of the C preprocessor, use the -Y flag.
120
121
122 For every data type referred to in infile, rpcgen assumes that there
123 exists a routine with the string xdr_ prepended to the name of the data
124 type. If this routine does not exist in the RPC/XDR library, it must be
125 provided. Providing an undefined data type allows customization of XDR
126 routines.
127
128 Server Error Reporting
129 By default, errors detected by proto_svc.c is reported to standard
130 error and/or the system log.
131
132
133 This behavior can be overridden by compiling the file with a definition
134 of RPC_MSGOUT, for example, -DRPC_MSGOUT=mymsgfunc. The function speci‐
135 fied is called to report errors. It must conform to the following
136 printf-like signature:
137
138 extern void RPC_MSGOUT(const char *fmt, ...);
139
140
141
143 The following options are supported:
144
145 -a Generates all files, including sample files.
146
147
148 -A Enables the Automatic MT mode in the server main pro‐
149 gram. In this mode, the RPC library automatically
150 creates threads to service client requests. This
151 option generates multithread-safe stubs by implicitly
152 turning on the -M option. Server multithreading modes
153 and parameters can be set using the rpc_control(3NSL)
154 call. rpcgen generated code does not change the
155 default values for the Automatic MT mode.
156
157
158 -b Backward compatibility mode. Generates transport-spe‐
159 cific RPC code for older versions of the operating
160 system.
161
162
163 -c Compiles into XDR routines.
164
165
166 -C Generates header and stub files which can be used
167 with ANSI C compilers. Headers generated with this
168 flag can also be used with C++ programs.
169
170
171 -Dname[=value] Defines a symbol name. Equivalent to the #define
172 directive in the source. If no value is given, value
173 is defined as 1. This option can be specified more
174 than once.
175
176
177 -h Compiles into C data-definitions (a header). The -T
178 option can be used in conjunction to produce a header
179 which supports RPC dispatch tables.
180
181
182 -i size Size at which to start generating inline code. This
183 option is useful for optimization. The default size
184 is 5.
185
186
187 -I Compiles support for inetd(1M) in the server side
188 stubs. Such servers can be self-started or can be
189 started by inetd. When the server is self-started, it
190 backgrounds itself by default. A special define sym‐
191 bol RPC_SVC_FG can be used to run the server process
192 in foreground, or the user can simply compile without
193 the -I option.
194
195 If there are no pending client requests, the inetd
196 servers exit after 120 seconds (default). The default
197 can be changed with the -K option. All of the error
198 messages for inetd servers are always logged with
199 syslog(3C).
200
201 Note: This option is supported for backward compati‐
202 bility only. It should always be used in conjunction
203 with the -b option which generates backward compati‐
204 bility code. By default (that is, when -b is not
205 specified), rpcgen generates servers that can be
206 invoked through portmonitors.
207
208
209 -K seconds By default, services created using rpcgen and invoked
210 through port monitors wait 120 seconds after servic‐
211 ing a request before exiting. That interval can be
212 changed using the -K flag. To create a server that
213 exits immediately upon servicing a request, use -K 0.
214 To create a server that never exits, the appropriate
215 argument is -K −1.
216
217 When monitoring for a server, some portmonitors, like
218 listen(1M), always spawn a new process in response to
219 a service request. If it is known that a server are
220 used with such a monitor, the server should exit
221 immediately on completion. For such servers, rpcgen
222 should be used with -K 0.
223
224
225 -l Compiles into client-side stubs.
226
227
228 -L When the servers are started in foreground, uses sys‐
229 log(3C) to log the server errors instead of printing
230 them on the standard error.
231
232
233 -m Compiles into server-side stubs, but do not generate
234 a "main" routine. This option is useful for doing
235 callback-routines and for users who need to write
236 their own "main" routine to do initialization.
237
238
239 -M Generates multithread-safe stubs for passing argu‐
240 ments and results between rpcgen-generated code and
241 user written code. This option is useful for users
242 who want to use threads in their code.
243
244
245 -N This option allows procedures to have multiple argu‐
246 ments. It also uses the style of parameter passing
247 that closely resembles C. So, when passing an argu‐
248 ment to a remote procedure, you do not have to pass a
249 pointer to the argument, but can pass the argument
250 itself. This behavior is different from the old style
251 of rpcgen-generated code. To maintain backward com‐
252 patibility, this option is not the default.
253
254
255 -n netid Compiles into server-side stubs for the transport
256 specified by netid. There should be an entry for
257 netid in the netconfig database. This option can be
258 specified more than once, so as to compile a server
259 that serves multiple transports.
260
261
262 -o outfile Specifies the name of the output file. If none is
263 specified, standard output is used (-c, -h, -l, -m,
264 -n, -s, -Sc, -Sm, -Ss, and -t modes only).
265
266
267 -s nettype Compiles into server-side stubs for all the trans‐
268 ports belonging to the class nettype. The supported
269 classes are netpath, visible, circuit_n, circuit_v,
270 datagram_n, datagram_v, tcp, and udp (see rpc(3NSL)
271 for the meanings associated with these classes). This
272 option can be specified more than once. Note: The
273 transports are chosen at run time and not at compile
274 time.
275
276
277 -Sc Generates sample client code that uses remote proce‐
278 dure calls.
279
280
281 -Sm Generates a sample Makefile which can be used for
282 compiling the application.
283
284
285 -Ss Generates sample server code that uses remote proce‐
286 dure calls.
287
288
289 -t Compiles into RPC dispatch table.
290
291
292 -T Generates the code to support RPC dispatch tables.
293
294 The options -c, -h, -l, -m, -s, -Sc, -Sm, -Ss, and -t
295 are used exclusively to generate a particular type of
296 file, while the options -D and -T are global and can
297 be used with the other options.
298
299
300 -v Displays the version number.
301
302
303 -Y pathname Gives the name of the directory where rpcgen starts
304 looking for the C preprocessor.
305
306
308 The following operand is supported:
309
310 infile input file
311
312
314 Example 1 Generating the output files and dispatch table
315
316
317 The following entry
318
319
320 example% rpcgen -T prot.x
321
322
323
324
325 generates all the five files: prot.h, prot_clnt.c, prot_svc.c,
326 prot_xdr.c, and prot_tbl.i.
327
328
329 Example 2 Sending headers to standard output
330
331
332 The following example sends the C data-definitions (header) to the
333 standard output:
334
335
336 example% rpcgen -h prot.x
337
338
339
340 Example 3 Sending a test version
341
342
343 To send the test version of the -DTEST, server side stubs for all the
344 transport belonging to the class datagram_n to standard output, use:
345
346
347 example% rpcgen -s datagram_n -DTEST prot.x
348
349
350
351 Example 4 Creating server side stubs
352
353
354 To create the server side stubs for the transport indicated by netid
355 tcp, use:
356
357
358 example% rpcgen -n tcp -o prot_svc.c prot.x
359
360
361
363 0 Successful operation.
364
365
366 >0 An error occurred.
367
368
370 See attributes(5) for descriptions of the following attributes:
371
372
373
374
375 ┌─────────────────────────────┬─────────────────────────────┐
376 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
377 ├─────────────────────────────┼─────────────────────────────┤
378 │Availability │SUNWbtool │
379 └─────────────────────────────┴─────────────────────────────┘
380
382 inetd(1M), listen(1M), rpc(3NSL), rpc_control(3NSL),
383 rpc_svc_calls(3NSL), syslog(3C), netconfig(4), attributes(5)
384
385
386 The rpcgen chapter in the ONC+ Developer's Guide manual.
387
388
389
390SunOS 5.11 24 Aug 2009 rpcgen(1)