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