Print this page
4329 rpcgen(1): Four output files are generated by default
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man1/rpcgen.1
+++ new/usr/src/man/man1/rpcgen.1
1 1 '\" te
2 2 .\" Copyright (C) 2009, Sun Microsystems, Inc. All Rights Reserved
3 3 .\" Copyright 1989 AT&T
4 4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
5 5 .\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the
6 6 .\" fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
7 -.TH RPCGEN 1 "Aug 24, 2009"
7 +.TH RPCGEN 1 "Dec 16, 2013"
8 8 .SH NAME
9 9 rpcgen \- an RPC protocol compiler
10 10 .SH SYNOPSIS
11 11 .LP
12 12 .nf
13 13 \fBrpcgen\fR \fIinfile\fR
14 14 .fi
15 15
16 16 .LP
17 17 .nf
18 18 \fBrpcgen\fR [\fB-a\fR] [\fB-A\fR] [\fB-b\fR] [\fB-C\fR] [\fB-D\fR \fIname\fR [= \fIvalue\fR]] [\fB-i\fR \fIsize\fR]
19 19 [\fB-I\fR [\fB-K\fR \fIseconds\fR]] [\fB-L\fR] [\fB-M\fR] [\fB-N\fR] [\fB- T\fR] [\fB-v\fR]
20 20 [\fB-Y\fR \fIpathname\fR] \fIinfile\fR
21 21 .fi
22 22
23 23 .LP
24 24 .nf
25 25 \fBrpcgen\fR [\fB-c\fR | \fB-h\fR | \fB-l\fR | \fB-m\fR | \fB-t\fR | \fB-Sc\fR | \fB-Ss\fR | \fB-Sm\fR]
26 26 [\fB-o\fR \fIoutfile\fR] [\fIinfile\fR]
27 27 .fi
28 28
29 29 .LP
30 30 .nf
31 31 \fBrpcgen\fR [\fB-s\fR \fInettype\fR] [\fB-o\fR \fIoutfile\fR] [\fIinfile\fR]
32 32 .fi
33 33
34 34 .LP
35 35 .nf
36 36 \fBrpcgen\fR [\fB-n\fR \fInetid\fR] [\fB-o\fR \fIoutfile\fR] [\fIinfile\fR]
37 37 .fi
|
↓ open down ↓ |
20 lines elided |
↑ open up ↑ |
38 38
39 39 .SH DESCRIPTION
40 40 .sp
41 41 .LP
42 42 The \fBrpcgen\fR utility is a tool that generates C code to implement an
43 43 \fBRPC\fR protocol. The input to \fBrpcgen\fR is a language similar to C known
44 44 as \fBRPC\fR Language (Remote Procedure Call Language).
45 45 .sp
46 46 .LP
47 47 The \fBrpcgen\fR utility is normally used as in the first synopsis where it
48 -takes an input file and generates three output files. If the \fIinfile\fR is
48 +takes an input file and generates four output files. If the \fIinfile\fR is
49 49 named \fBproto.x\fR, then \fBrpcgen\fR generates a header in \fBproto.h\fR,
50 50 \fBXDR\fR routines in \fBproto_xdr.c\fR, server-side stubs in
51 51 \fBproto_svc.c\fR, and client-side stubs in \fBproto_clnt.c\fR. With the
52 52 \fB-T\fR option, it also generates the \fBRPC\fR dispatch table in
53 53 \fBproto_tbl.i\fR.
54 54 .sp
55 55 .LP
56 56 \fBrpcgen\fR can also generate sample client and server files that can be
57 57 customized to suit a particular application. The \fB-Sc\fR, \fB-Ss\fR, and
58 58 \fB-Sm\fR options generate sample client, server and makefile, respectively.
59 59 The \fB-a\fR option generates all files, including sample files. If the infile
60 60 is \fBproto.x\fR, then the client side sample file is written to
61 61 \fBproto_client.c\fR, the server side sample file to \fBproto_server.c\fR and
62 62 the sample makefile to \fBmakefile.proto\fR.
63 63 .sp
64 64 .LP
65 65 The server created can be started both by the port monitors (for example,
66 66 \fBinetd\fR or \fBlisten\fR) or by itself. When it is started by a port
67 67 monitor, it creates servers only for the transport for which the file
68 68 descriptor \fB0\fR was passed. The name of the transport must be specified by
69 69 setting up the environment variable \fBPM_TRANSPORT\fR. When the server
70 70 generated by \fBrpcgen\fR is executed, it creates server handles for all the
71 71 transports specified in the \fBNETPATH\fR environment variable, or if it is
72 72 unset, it creates server handles for all the visible transports from the
73 73 \fB/etc/netconfig\fR file. Note: the transports are chosen at run time and not
74 74 at compile time. When the server is self-started, it backgrounds itself by
75 75 default. A special define symbol \fBRPC_SVC_FG\fR can be used to run the server
76 76 process in foreground.
77 77 .sp
78 78 .LP
79 79 The second synopsis provides special features which allow for the creation of
80 80 more sophisticated \fBRPC\fR servers. These features include support for
81 81 user-provided \fB#defines\fR and \fBRPC\fR dispatch tables. The entries in the
82 82 \fBRPC\fR dispatch table contain:
83 83 .RS +4
84 84 .TP
85 85 .ie t \(bu
86 86 .el o
87 87 pointers to the service routine corresponding to that procedure
88 88 .RE
89 89 .RS +4
90 90 .TP
91 91 .ie t \(bu
92 92 .el o
93 93 a pointer to the input and output arguments
94 94 .RE
95 95 .RS +4
96 96 .TP
97 97 .ie t \(bu
98 98 .el o
99 99 the size of these routines
100 100 .RE
101 101 .sp
102 102 .LP
103 103 A server can use the dispatch table to check authorization and then to execute
104 104 the service routine. A client library can use the dispatch table to deal with
105 105 the details of storage management and \fBXDR\fR data conversion.
106 106 .sp
107 107 .LP
108 108 The other three synopses shown above are used when one does not want to
109 109 generate all the output files, but only a particular one. See the EXAMPLES
110 110 section below for examples of \fBrpcgen\fR usage. When \fBrpcgen\fR is executed
111 111 with the \fB-s\fR option, it creates servers for that particular class of
112 112 transports. When executed with the \fB-n\fR option, it creates a server for the
113 113 transport specified by \fInetid\fR. If \fIinfile\fR is not specified,
114 114 \fBrpcgen\fR accepts the standard input.
115 115 .sp
116 116 .LP
117 117 All the options mentioned in the second synopsis can be used with the other
118 118 three synopses, but the changes are made only to the specified output file.
119 119 .sp
120 120 .LP
121 121 The C preprocessor \fBcc\fR \fB-E\fR is run on the input file before it is
122 122 actually interpreted by \fBrpcgen\fR. For each type of output file,
123 123 \fBrpcgen\fR defines a special preprocessor symbol for use by the \fBrpcgen\fR
124 124 programmer:
125 125 .sp
126 126 .ne 2
127 127 .na
128 128 \fB\fBRPC_HDR\fR\fR
129 129 .ad
130 130 .RS 12n
131 131 defined when compiling into headers
132 132 .RE
133 133
134 134 .sp
135 135 .ne 2
136 136 .na
137 137 \fB\fBRPC_XDR\fR\fR
138 138 .ad
139 139 .RS 12n
140 140 defined when compiling into \fBXDR\fR routines
141 141 .RE
142 142
143 143 .sp
144 144 .ne 2
145 145 .na
146 146 \fB\fBRPC_SVC\fR\fR
147 147 .ad
148 148 .RS 12n
149 149 defined when compiling into server-side stubs
150 150 .RE
151 151
152 152 .sp
153 153 .ne 2
154 154 .na
155 155 \fB\fBRPC_CLNT\fR\fR
156 156 .ad
157 157 .RS 12n
158 158 defined when compiling into client-side stubs
159 159 .RE
160 160
161 161 .sp
162 162 .ne 2
163 163 .na
164 164 \fB\fBRPC_TBL\fR\fR
165 165 .ad
166 166 .RS 12n
167 167 defined when compiling into \fBRPC\fR dispatch tables
168 168 .RE
169 169
170 170 .sp
171 171 .LP
172 172 Any line beginning with ``\fB%\fR'' is passed directly into the output file,
173 173 uninterpreted by \fBrpcgen\fR, except that the leading ``\fB%\fR" is stripped
174 174 off. To specify the path name of the C preprocessor, use the \fB-Y\fR flag.
175 175 .sp
176 176 .LP
177 177 For every data type referred to in \fIinfile\fR, \fBrpcgen\fR assumes that
178 178 there exists a routine with the string \fBxdr_\fR prepended to the name of the
179 179 data type. If this routine does not exist in the \fBRPC\fR/\fBXDR\fR library,
180 180 it must be provided. Providing an undefined data type allows customization of
181 181 \fBXDR\fR routines.
182 182 .SS "Server Error Reporting"
183 183 .sp
184 184 .LP
185 185 By default, errors detected by \fBproto_svc.c\fR is reported to standard error
186 186 and/or the system log.
187 187 .sp
188 188 .LP
189 189 This behavior can be overridden by compiling the file with a definition of
190 190 \fBRPC_MSGOUT\fR, for example, \fB-DRPC_MSGOUT=mymsgfunc\fR. The function
191 191 specified is called to report errors. It must conform to the following
192 192 \fBprintf\fR-like signature:
193 193 .sp
194 194 .in +2
195 195 .nf
196 196 extern void RPC_MSGOUT(const char *fmt, ...);
197 197 .fi
198 198 .in -2
199 199 .sp
200 200
201 201 .SH OPTIONS
202 202 .sp
203 203 .LP
204 204 The following options are supported:
205 205 .sp
206 206 .ne 2
207 207 .na
208 208 \fB\fB-a\fR\fR
209 209 .ad
210 210 .RS 18n
211 211 Generates all files, including sample files.
212 212 .RE
213 213
214 214 .sp
215 215 .ne 2
216 216 .na
217 217 \fB\fB-A\fR\fR
218 218 .ad
219 219 .RS 18n
220 220 Enables the Automatic \fBMT\fR mode in the server main program. In this mode,
221 221 the \fBRPC\fR library automatically creates threads to service client requests.
222 222 This option generates multithread-safe stubs by implicitly turning on the
223 223 \fB-M\fR option. Server multithreading modes and parameters can be set using
224 224 the \fBrpc_control\fR(3NSL) call. \fBrpcgen\fR generated code does not change
225 225 the default values for the Automatic \fBMT\fR mode.
226 226 .RE
227 227
228 228 .sp
229 229 .ne 2
230 230 .na
231 231 \fB\fB-b\fR\fR
232 232 .ad
233 233 .RS 18n
234 234 Backward compatibility mode. Generates transport-specific \fBRPC\fR code for
235 235 older versions of the operating system.
236 236 .RE
237 237
238 238 .sp
239 239 .ne 2
240 240 .na
241 241 \fB\fB-c\fR\fR
242 242 .ad
243 243 .RS 18n
244 244 Compiles into \fBXDR\fR routines.
245 245 .RE
246 246
247 247 .sp
248 248 .ne 2
249 249 .na
250 250 \fB\fB-C\fR\fR
251 251 .ad
252 252 .RS 18n
253 253 Generates header and stub files which can be used with ANSI C compilers.
254 254 Headers generated with this flag can also be used with C++ programs.
255 255 .RE
256 256
257 257 .sp
258 258 .ne 2
259 259 .na
260 260 \fB\fB-D\fR\fIname\fR\fB[=\fR\fIvalue\fR\fB]\fR\fR
261 261 .ad
262 262 .RS 18n
263 263 Defines a symbol \fIname\fR. Equivalent to the \fB#define\fR directive in the
264 264 source. If no \fIvalue\fR is given, \fIvalue\fR is defined as \fB1\fR. This
265 265 option can be specified more than once.
266 266 .RE
267 267
268 268 .sp
269 269 .ne 2
270 270 .na
271 271 \fB\fB-h\fR\fR
272 272 .ad
273 273 .RS 18n
274 274 Compiles into \fBC\fR data-definitions (a header). The \fB-T\fR option can be
275 275 used in conjunction to produce a header which supports \fBRPC\fR dispatch
276 276 tables.
277 277 .RE
278 278
279 279 .sp
280 280 .ne 2
281 281 .na
282 282 \fB\fB-i\fR \fIsize\fR\fR
283 283 .ad
284 284 .RS 18n
285 285 Size at which to start generating inline code. This option is useful for
286 286 optimization. The default \fIsize\fR is 5.
287 287 .RE
288 288
289 289 .sp
290 290 .ne 2
291 291 .na
292 292 \fB\fB-I\fR\fR
293 293 .ad
294 294 .RS 18n
295 295 Compiles support for \fBinetd\fR(1M) in the server side stubs. Such servers can
296 296 be self-started or can be started by \fBinetd\fR. When the server is
297 297 self-started, it backgrounds itself by default. A special define symbol
298 298 \fBRPC_SVC_FG\fR can be used to run the server process in foreground, or the
299 299 user can simply compile without the \fB-I\fR option.
300 300 .sp
301 301 If there are no pending client requests, the \fBinetd\fR servers exit after 120
302 302 seconds (default). The default can be changed with the \fB-K\fR option. All of
303 303 the error messages for \fBinetd\fR servers are always logged with
304 304 \fBsyslog\fR(3C).
305 305 .sp
306 306 \fBNote:\fR This option is supported for backward compatibility only. It should
307 307 always be used in conjunction with the \fB-b\fR option which generates backward
308 308 compatibility code. By default (that is, when \fB-b\fR is not specified),
309 309 \fBrpcgen\fR generates servers that can be invoked through portmonitors.
310 310 .RE
311 311
312 312 .sp
313 313 .ne 2
314 314 .na
315 315 \fB\fB-K\fR \fIseconds\fR\fR
316 316 .ad
317 317 .RS 18n
318 318 By default, services created using \fBrpcgen\fR and invoked through port
319 319 monitors wait 120 seconds after servicing a request before exiting. That
320 320 interval can be changed using the \fB-K\fR flag. To create a server that exits
321 321 immediately upon servicing a request, use \fB-K\fR \fB0\fR. To create a server
322 322 that never exits, the appropriate argument is \fB-K\fR \fB\(mi1\fR\&.
323 323 .sp
324 324 When monitoring for a server, some portmonitors, like \fBlisten\fR(1M),
325 325 \fBalways\fR spawn a new process in response to a service request. If it is
326 326 known that a server are used with such a monitor, the server should exit
327 327 immediately on completion. For such servers, \fBrpcgen\fR should be used with
328 328 \fB-K\fR \fB0\fR.
329 329 .RE
330 330
331 331 .sp
332 332 .ne 2
333 333 .na
334 334 \fB\fB-l\fR\fR
335 335 .ad
336 336 .RS 18n
337 337 Compiles into client-side stubs.
338 338 .RE
339 339
340 340 .sp
341 341 .ne 2
342 342 .na
343 343 \fB\fB-L\fR\fR
344 344 .ad
345 345 .RS 18n
346 346 When the servers are started in foreground, uses \fBsyslog\fR(3C) to log the
347 347 server errors instead of printing them on the standard error.
348 348 .RE
349 349
350 350 .sp
351 351 .ne 2
352 352 .na
353 353 \fB\fB-m\fR\fR
354 354 .ad
355 355 .RS 18n
356 356 Compiles into server-side stubs, but do not generate a "main" routine. This
357 357 option is useful for doing callback-routines and for users who need to write
358 358 their own "main" routine to do initialization.
359 359 .RE
360 360
361 361 .sp
362 362 .ne 2
363 363 .na
364 364 \fB\fB-M\fR\fR
365 365 .ad
366 366 .RS 18n
367 367 Generates multithread-safe stubs for passing arguments and results between
368 368 \fBrpcgen\fR-generated code and user written code. This option is useful for
369 369 users who want to use threads in their code.
370 370 .RE
371 371
372 372 .sp
373 373 .ne 2
374 374 .na
375 375 \fB\fB-N\fR\fR
376 376 .ad
377 377 .RS 18n
378 378 This option allows procedures to have multiple arguments. It also uses the
379 379 style of parameter passing that closely resembles C. So, when passing an
380 380 argument to a remote procedure, you do not have to pass a pointer to the
381 381 argument, but can pass the argument itself. This behavior is different from the
382 382 old style of \fBrpcgen\fR-generated code. To maintain backward compatibility,
383 383 this option is not the default.
384 384 .RE
385 385
386 386 .sp
387 387 .ne 2
388 388 .na
389 389 \fB\fB-n\fR \fInetid\fR\fR
390 390 .ad
391 391 .RS 18n
392 392 Compiles into server-side stubs for the transport specified by \fInetid\fR.
393 393 There should be an entry for \fInetid\fR in the \fBnetconfig\fR database. This
394 394 option can be specified more than once, so as to compile a server that serves
395 395 multiple transports.
396 396 .RE
397 397
398 398 .sp
399 399 .ne 2
400 400 .na
401 401 \fB\fB-o\fR \fIoutfile\fR\fR
402 402 .ad
403 403 .RS 18n
404 404 Specifies the name of the output file. If none is specified, standard output is
405 405 used (\fB-c\fR, \fB-h\fR, \fB-l\fR, \fB-m\fR, \fB-n\fR, \fB-s\fR, \fB-Sc\fR,
406 406 \fB-Sm\fR, \fB-Ss\fR, and \fB-t\fR modes only).
407 407 .RE
408 408
409 409 .sp
410 410 .ne 2
411 411 .na
412 412 \fB\fB-s\fR \fInettype\fR\fR
413 413 .ad
414 414 .RS 18n
415 415 Compiles into server-side stubs for all the transports belonging to the class
416 416 \fInettype\fR. The supported classes are \fBnetpath\fR, \fBvisible\fR,
417 417 \fBcircuit_n\fR, \fBcircuit_v\fR, \fBdatagram_n\fR, \fBdatagram_v\fR,
418 418 \fBtcp\fR, and \fBudp\fR (see \fBrpc\fR(3NSL) for the meanings associated with
419 419 these classes). This option can be specified more than once. \fBNote:\fR The
420 420 transports are chosen at run time and not at compile time.
421 421 .RE
422 422
423 423 .sp
424 424 .ne 2
425 425 .na
426 426 \fB\fB-Sc\fR\fR
427 427 .ad
428 428 .RS 18n
429 429 Generates sample client code that uses remote procedure calls.
430 430 .RE
431 431
432 432 .sp
433 433 .ne 2
434 434 .na
435 435 \fB\fB-Sm\fR\fR
436 436 .ad
437 437 .RS 18n
438 438 Generates a sample Makefile which can be used for compiling the application.
439 439 .RE
440 440
441 441 .sp
442 442 .ne 2
443 443 .na
444 444 \fB\fB-Ss\fR\fR
445 445 .ad
446 446 .RS 18n
447 447 Generates sample server code that uses remote procedure calls.
448 448 .RE
449 449
450 450 .sp
451 451 .ne 2
452 452 .na
453 453 \fB\fB-t\fR\fR
454 454 .ad
455 455 .RS 18n
456 456 Compiles into \fBRPC\fR dispatch table.
457 457 .RE
458 458
459 459 .sp
460 460 .ne 2
461 461 .na
462 462 \fB\fB-T\fR\fR
463 463 .ad
464 464 .RS 18n
465 465 Generates the code to support \fBRPC\fR dispatch tables.
466 466 .sp
467 467 The options \fB-c\fR, \fB-h\fR, \fB-l\fR, \fB-m\fR, \fB-s\fR, \fB-Sc\fR,
468 468 \fB-Sm\fR, \fB-Ss\fR, and \fB-t\fR are used exclusively to generate a
469 469 particular type of file, while the options \fB-D\fR and \fB-T\fR are global and
470 470 can be used with the other options.
471 471 .RE
472 472
473 473 .sp
474 474 .ne 2
475 475 .na
476 476 \fB\fB-v\fR\fR
477 477 .ad
478 478 .RS 18n
479 479 Displays the version number.
480 480 .RE
481 481
482 482 .sp
483 483 .ne 2
484 484 .na
485 485 \fB\fB-Y\fR \fIpathname\fR\fR
486 486 .ad
487 487 .RS 18n
488 488 Gives the name of the directory where \fBrpcgen\fR starts looking for the C
489 489 preprocessor.
490 490 .RE
491 491
492 492 .SH OPERANDS
493 493 .sp
494 494 .LP
495 495 The following operand is supported:
496 496 .sp
497 497 .ne 2
498 498 .na
499 499 \fB\fIinfile\fR\fR
500 500 .ad
501 501 .RS 10n
502 502 input file
503 503 .RE
504 504
505 505 .SH EXAMPLES
506 506 .LP
507 507 \fBExample 1 \fRGenerating the output files and dispatch table
508 508 .sp
509 509 .LP
510 510 The following entry
511 511
512 512 .sp
513 513 .in +2
514 514 .nf
515 515 example% \fBrpcgen -T prot.x\fR
516 516 .fi
517 517 .in -2
518 518 .sp
519 519
520 520 .sp
521 521 .LP
522 522 generates all the five files: \fBprot.h\fR, \fBprot_clnt.c\fR,
523 523 \fBprot_svc.c\fR, \fBprot_xdr.c\fR, and \fBprot_tbl.i\fR.
524 524
525 525 .LP
526 526 \fBExample 2 \fRSending headers to standard output
527 527 .sp
528 528 .LP
529 529 The following example sends the C data-definitions (header) to the standard
530 530 output:
531 531
532 532 .sp
533 533 .in +2
534 534 .nf
535 535 example% \fBrpcgen -h prot.x\fR
536 536 .fi
537 537 .in -2
538 538 .sp
539 539
540 540 .LP
541 541 \fBExample 3 \fRSending a test version
542 542 .sp
543 543 .LP
544 544 To send the test version of the \fB-DTEST\fR, server side stubs for all the
545 545 transport belonging to the class \fBdatagram_n\fR to standard output, use:
546 546
547 547 .sp
548 548 .in +2
549 549 .nf
550 550 example% \fBrpcgen -s datagram_n -DTEST prot.x\fR
551 551 .fi
552 552 .in -2
553 553 .sp
554 554
555 555 .LP
556 556 \fBExample 4 \fRCreating server side stubs
557 557 .sp
558 558 .LP
559 559 To create the server side stubs for the transport indicated by \fInetid\fR
560 560 \fBtcp\fR, use:
561 561
562 562 .sp
563 563 .in +2
564 564 .nf
565 565 example% \fBrpcgen -n tcp -o prot_svc.c prot.x\fR
566 566 .fi
567 567 .in -2
568 568 .sp
569 569
570 570 .SH EXIT STATUS
571 571 .sp
572 572 .ne 2
573 573 .na
574 574 \fB\fB0\fR\fR
575 575 .ad
576 576 .RS 6n
577 577 Successful operation.
578 578 .RE
579 579
580 580 .sp
581 581 .ne 2
582 582 .na
583 583 \fB\fB>0\fR\fR
584 584 .ad
585 585 .RS 6n
586 586 An error occurred.
587 587 .RE
588 588
589 589 .SH SEE ALSO
590 590 .sp
591 591 .LP
592 592 \fBinetd\fR(1M), \fBlisten\fR(1M), \fBrpc\fR(3NSL), \fBrpc_control\fR(3NSL),
593 593 \fBrpc_svc_calls\fR(3NSL), \fBsyslog\fR(3C), \fBnetconfig\fR(4),
594 594 \fBattributes\fR(5)
595 595 .sp
596 596 .LP
597 597 The \fBrpcgen\fR chapter in the \fIONC+ Developer\&'s Guide\fR manual.
|
↓ open down ↓ |
539 lines elided |
↑ open up ↑ |
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX