Penguin
Recent Changes
Annotated edit history of rpcgen(1) version 1, including all changes. View license author blame.
Rev Author # Line
1 perry 1 rpcgen
2 !!!rpcgen
3 NAME
4 SYNOPSIS
5 DESCRIPTION
6 NOTES
7 EXAMPLE
8 SEE ALSO
9 ----
10 !!NAME
11
12
13 ''rpcgen'' - an RPC protocol compiler
14 !!SYNOPSIS
15
16
17 ''rpcgen'' ''infile
18 ''
19 ''rpcgen [[-D''''name''''[[=''''value'''']] [[-T] [[-K'' ''secs'''']'' ''infile
20 ''
21 ''rpcgen -c|-h|-l|-m|-t [[-o'' ''outfile'' '']'' ''infile
22 ''
23 ''rpcgen [[-I] -s'' ''nettype'' ''[[-o'' ''outfile'''']'' ''infile
24 ''
25 ''rpcgen -n'' ''netid'' ''[[-o'' ''outfile'''']'' ''infile
26 ''
27 !!DESCRIPTION
28
29
30 ''rpcgen'' is a tool that generates C code to implement
31 an RPC protocol. The input to ''rpcgen'' is a language
32 similar to C known as RPC Language (Remote Procedure Call
33 Language).
34
35
36 ''rpcgen'' is normally used as in the first synopsis
37 where it takes an input file and generates up to four output
38 files. If the ''infile'' is named ''proto.x'', then
39 ''rpcgen'' will generate a header file in ''proto.h'',
40 XDR routines in ''proto_xdr.c'', server-side stubs in
41 ''proto_svc.c'', and client-side stubs in
42 ''proto_clnt.c''. With the ''-T'' option, it will also
43 generate the RPC dispatch table in ''proto_tbl.i''. With
44 the ''-Sc'' option, it will also generate sample code
45 which would illustrate how to use the remote procedures on
46 the client side. This code would be created in
47 ''proto_client.c''. With the ''-Ss'' option, it will
48 also generate a sample server code which would illustrate
49 how to write the remote procedures. This code would be
50 created in ''proto_server.c''.
51
52
53 The server created can be started both by the port monitors
54 (for example, ''inetd'' or ''listen'') or by itself.
55 When it is started by a port monitor, it creates servers
56 only for the transport for which the file descriptor
57 ''0'' was passed. The name of the transport must be
58 specified by setting up the environmental variable
59 ''PM_TRANSPORT''. When the server generated by
60 ''rpcgen'' is executed, it creates server handles for all
61 the transports specified in ''NETPATH'' environment
62 variable, or if it is unset, it creates server handles for
63 all the visible transports from ''/etc/netconfig'' file.
64 Note: the transports are chosen at run time and not at
65 compile time. When the server is self-started, it
66 backgrounds itself by default. A special define symbol
67 ''RPC_SVC_FG'' can be used to run the server process in
68 foreground.
69
70
71 The second synopsis provides special features which allow
72 for the creation of more sophisticated RPC servers. These
73 features include support for user provided ''#defines''
74 and RPC dispatch tables. The entries in the RPC dispatch
75 table contain:
76
77
78 pointers to the service routine corresponding to that
79 procedure,
80
81
82 a pointer to the input and output arguments
83
84
85 the size of these routines
86
87
88 A server can use the dispatch table to check authorization
89 and then to execute the service routine; a client library
90 may use it to deal with the details of storage management
91 and XDR data conversion.
92
93
94 The other three synopses shown above are used when one does
95 not want to generate all the output files, but only a
96 particular one. Some examples of their usage is described in
97 the EXAMPLE section below. When ''rpcgen'' is executed
98 with the ''-s'' option, it creates servers for that
99 particular class of transports. When executed with the
100 ''-n'' option, it creates a server for the transport
101 specified by ''netid''. If ''infile'' is not
102 specified, ''rpcgen'' accepts the standard
103 input.
104
105
106 The C preprocessor, ''cc -E'' [[see cc(1)], is run
107 on the input file before it is actually interpreted by
108 ''rpcgen''. For each type of output file, ''rpcgen''
109 defines a special preprocessor symbol for use by the
110 ''rpcgen'' programmer:
111
112
113 ''RPC_HDR''
114
115
116 defined when compiling into header files
117
118
119 ''RPC_XDR''
120
121
122 defined when compiling into XDR routines
123
124
125 ''RPC_SVC''
126
127
128 defined when compiling into server-side stubs
129
130
131 ''RPC_CLNT''
132
133
134 defined when compiling into client-side stubs
135
136
137 ''RPC_TBL''
138
139
140 defined when compiling into RPC dispatch tables
141
142
143 Any line beginning with `''%''' is passed directly into
144 the output file, uninterpreted by
145 ''rpcgen''.
146
147
148 For every data type referred to in ''infile'',
149 ''rpcgen'' assumes that there exists a routine with the
150 string ''xdr_'' prepended to the name of the data type.
151 If this routine does not exist in the RPC/XDR library, it
152 must be provided. Providing an undefined data type allows
153 customization of XDR routines.
154
155
156 The following options are available:
157
158
159 ''-a''
160
161
162 Generate all the files including sample code for client and
163 server side.
164
165
166 ''-b''
167
168
169 This generates code for the SunOS4.1 style of rpc. It is for
170 backward compatibilty. This is the default.
171
172
173 ''-5''
174
175
176 This generates code for the SysVr4 style of rpc. It is used
177 by the Transport Independent RPC that is in Svr4 systems. By
178 default rpcgen generates code for SunOS4.1 stype of
179 rpc.
180
181
182 ''-c''
183
184
185 Compile into XDR routines.
186
187
188 ''-C''
189
190
191 Generate code in ANSI C. This option also generates code
192 that could be compiled with the C++ compiler. This is the
193 default.
194
195
196 ''-k''
197
198
199 Generate code in K
200
201
202 ''-D''''name''''[[=''''value'''']''
203
204
205 Define a symbol ''name''. Equivalent to the
206 ''#define'' directive in the source. If no ''value''
207 is given, ''value'' is defined as ''1''. This option
208 may be specified more than once.
209
210
211 ''-h''
212
213
214 Compile into ''C'' data-definitions (a header file).
215 ''-T'' option can be used in conjunction to produce a
216 header file which supports RPC dispatch tables.
217
218
219 ''-I''
220
221
222 Generate a service that can be started from inetd. The
223 default is to generate a static service that handles
224 transports selected with ''-s''. Using ''-I'' allows
225 starting a service by either method.
226
227
228 ''-K'' ''secs''
229
230
231 By default, services created using ''rpcgen'' wait
232 ''120'' seconds after servicing a request before exiting.
233 That interval can be changed using the ''-K'' flag. To
234 create a server that exits immediately upon servicing a
235 request, ''-K 0'' can be used. To create a server that
236 never exits, the appropriate argument is ''-K
237 -1''.
238
239
240 When monitoring for a server, some portmonitors, like
241 ''listen''(1M), ''always'' spawn a new process in
242 response to a service request. If it is known that a server
243 will be used with such a monitor, the server should exit
244 immediately on completion. For such servers, ''rpcgen''
245 should be used with ''-K -1''.
246
247
248 ''-l''
249
250
251 Compile into client-side stubs.
252
253
254 ''-m''
255
256
257 Compile into server-side stubs, but do not generate a
258 ``main'' routine. This option is useful for doing
259 callback-routines and for users who need to write their own
260 ``main'' routine to do initialization.
261
262
263 ''-n'' ''netid''
264
265
266 Compile into server-side stubs for the transport specified
267 by ''netid''. There should be an entry for ''netid''
268 in the netconfig database. This option may be specified more
269 than once, so as to compile a server that serves multiple
270 transports.
271
272
273 ''-N''
274
275
276 Use the newstyle of rpcgen. This allows procedures to have
277 multiple arguments. It also uses the style of parameter
278 passing that closely resembles C. So, when passing an
279 argument to a remote procedure you do not have to pass a
280 pointer to the argument but the argument itself. This
281 behaviour is different from the oldstyle of rpcgen generated
282 code. The newstyle is not the default case because of
283 backward compatibility.
284
285
286 ''-o'' ''outfile''
287
288
289 Specify the name of the output file. If none is specified,
290 standard output is used (''-c'', ''-h'', ''-l'',
291 ''-m'', ''-n'', ''-s'', ''-s -sand -t'' modes
292 only).
293
294
295 ''-s'' ''nettype''
296
297
298 Compile into server-side stubs for all the transports
299 belonging to the class ''nettype''. The supported classes
300 are ''netpath'', ''visible'', ''circuit_n'',
301 ''circuit_v'', ''datagram_n'', ''datagram_v'',
302 ''tcp'', and ''udp'' [[see ''rpc''(3N) for the
303 meanings associated with these classes]. This option may be
304 specified more than once. Note: the transports are chosen at
305 run time and not at compile time.
306
307
308 ''-Sc''
309
310
311 Generate sample code to show the use of remote procedure and
312 how to bind to the server before calling the client side
313 stubs generated by rpcgen.
314
315
316 ''-Ss''
317
318
319 Generate skeleton code for the remote procedures on the
320 server side. You would need to fill in the actual code for
321 the remote procedures.
322
323
324 ''-t''
325
326
327 Compile into RPC dispatch table.
328
329
330 ''-T''
331
332
333 Generate the code to support RPC dispatch
334 tables.
335
336
337 The options ''-c'', ''-h'', ''-l'', ''-m'',
338 ''-s'' and ''-t'' are used exclusively to generate a
339 particular type of file, while the options ''-D'' and
340 ''-T'' are global and can be used with the other
341 options.
342 !!NOTES
343
344
345 The RPC Language does not support nesting of structures. As
346 a work-around, structures can be declared at the top-level,
347 and their name used inside other structures in order to
348 achieve the same effect.
349
350
351 Name clashes can occur when using program definitions, since
352 the apparent scoping does not really apply. Most of these
353 can be avoided by giving unique names for programs,
354 versions, procedures and types.
355
356
357 The server code generated with ''-n'' option refers to
358 the transport indicated by ''netid'' and hence is very
359 site specific.
360 !!EXAMPLE
361
362
363 The following example:
364
365
366 ''$ rpcgen -T prot.x''
367
368
369 generates the five files: ''prot.h'', ''prot_clnt.c'',
370 ''prot_svc.c'', ''prot_xdr.c'' and
371 ''prot_tbl.i''.
372
373
374 The following example sends the C data-definitions (header
375 file) to the standard output.
376
377
378 ''$ rpcgen -h prot.x''
379
380
381 To send the test version of the ''-DTEST'', server side
382 stubs for all the transport belonging to the class
383 ''datagram_n'' to standard output, use:
384
385
386 ''$ rpcgen -s datagram_n -DTEST prot.x''
387
388
389 To create the server side stubs for the transport indicated
390 by ''netid'' ''tcp'', use:
391
392
393 ''$ rpcgen -n tcp -o prot_svc.c prot.x''
394 !!SEE ALSO
395
396
397 cc(1).
398 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.