1 .\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
   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 .Dd "Aug 2, 2014"
   8 .Dt RPCGEN 1
   9 .Os
  10 .Sh NAME
  11 .Nm rpcgen
  12 .Nd an RPC protocol compiler
  13 .Sh SYNOPSIS
  14 .Nm
  15 .Ar infile
  16 .
  17 .Nm
  18 .Op Fl a
  19 .Op Fl A
  20 .Op Fl b
  21 .Op Fl C
  22 .Op Fl D Ar name Ns Op = Ns Ar value
  23 .Op Fl i Ar size
  24 .Op Fl I Op Fl K Ar seconds
  25 .Op Fl L
  26 .Op Fl M
  27 .Op Fl N
  28 .Op Fl T
  29 .Op Fl v
  30 .Op Fl Y Ar pathname
  31 .Ar infile
  32 .
  33 .Nm
  34 .Op Fl c | Fl h | Fl l | Fl m | Fl t | Fl "Sc" | Fl "Ss" | Fl "Sm"
  35 .Op Fl o Ar outfile
  36 .Op Ar infile
  37 .
  38 .Nm
  39 .Op Fl s Ar nettype
  40 .Op Fl o Ar outfile
  41 .Op Ar infile
  42 .
  43 .Nm
  44 .Op Fl n Ar netid
  45 .Op Fl o Ar outfile
  46 .Op infile
  47 .
  48 .Sh DESCRIPTION
  49 The
  50 .Nm
  51 utility is a tool that generates C code to implement an
  52 RPC protocol. The input to
  53 .Nm
  54 is a language similar to C known
  55 as
  56 .Em RPC Language
  57 (Remote Procedure Call Language).
  58 .Lp
  59 The
  60 .Nm
  61 utility is normally used as in the first synopsis where it
  62 takes an input file and generates four output files. If the
  63 .Ar infile
  64 is
  65 named
  66 .Pa proto.x ,
  67 then
  68 .Nm
  69 generates a header in
  70 .Pa proto.h ,
  71 XDR routines in
  72 .Pa proto_xdr.c ,
  73 server-side stubs in
  74 .Pa proto_svc.c ,
  75 and client-side stubs in
  76 .Pa proto_clnt.c .
  77 With the
  78 .Fl T
  79 option, it also generates the RPC dispatch table in
  80 .Pa proto_tbl.i .
  81 .Lp
  82 .Nm
  83 can also generate sample client and server files that can be
  84 customized to suit a particular application. The
  85 .Fl "Sc" ,
  86 .Fl "Ss" ,
  87 and
  88 .Fl "Sm"
  89 options generate sample client, server and makefile, respectively.
  90 The
  91 .Fl a
  92 option generates all files, including sample files. If the infile
  93 is
  94 .Pa proto.x ,
  95 then the client side sample file is written to
  96 .Pa proto_client.c ,
  97 the server side sample file to
  98 .Pa proto_server.c
  99 and the sample makefile to
 100 .Pa makefile.proto .
 101 .Lp
 102 The server created can be started both by the port monitors (for example,
 103 .Xr inetd 1M
 104 or
 105 .Xr listen 1M )
 106 or by itself. When it is started by a port
 107 monitor, it creates servers only for the transport for which the file
 108 descriptor 0 was passed. The name of the transport must be specified by
 109 setting up the environment variable
 110 .Ev PM_TRANSPORT .
 111 When the server
 112 generated by
 113 .Nm
 114 is executed, it creates server handles for all the
 115 transports specified in the
 116 .Ev NETPATH
 117 environment variable, or if it is
 118 unset, it creates server handles for all the visible transports from the
 119 .Pa /etc/netconfig
 120 file. Note: the transports are chosen at run time and not
 121 at compile time. When the server is self-started, it backgrounds itself by
 122 default. A special define symbol
 123 .Dv RPC_SVC_FG
 124 can be used to run the server process in foreground.
 125 .Lp
 126 The second synopsis provides special features which allow for the creation of
 127 more sophisticated RPC servers. These features include support for
 128 user-provided
 129 .Li #defines
 130 and RPC dispatch tables. The entries in the
 131 RPC dispatch table contain:
 132 .Bl -bullet -offset indent
 133 .It
 134 pointers to the service routine corresponding to that procedure
 135 .It
 136 a pointer to the input and output arguments
 137 .It
 138 the size of these routines
 139 .El
 140 .Lp
 141 A server can use the dispatch table to check authorization and then to execute
 142 the service routine. A client library can use the dispatch table to deal with
 143 the details of storage management and XDR data conversion.
 144 .Lp
 145 The other three synopses shown above are used when one does not want to
 146 generate all the output files, but only a particular one. See the
 147 .Sx EXAMPLES
 148 section below for examples of
 149 .Nm
 150 usage. When
 151 .Nm
 152 is executed with the
 153 .Fl s
 154 option, it creates servers for that particular class of
 155 transports. When executed with the
 156 .Fl n
 157 option, it creates a server for the
 158 transport specified by
 159 .Ar netid .
 160 If
 161 .Ar infile
 162 is not specified,
 163 .Nm
 164 accepts the standard input.
 165 .Lp
 166 All the options mentioned in the second synopsis can be used with the other
 167 three synopses, but the changes are made only to the specified output file.
 168 .Lp
 169 The C preprocessor
 170 .Ic cc Fl E
 171 is run on the input file before it is
 172 actually interpreted by
 173 .Nm .
 174 For each type of output file,
 175 .Nm
 176 defines a special preprocessor symbol for use by the
 177 .Nm
 178 programmer:
 179 .Bl -tag -width Dv -offset indent
 180 .It Dv RPC_HDR
 181 defined when compiling into headers
 182 .It Dv RPC_XDR
 183 defined when compiling into XDR routines
 184 .It Dv RPC_SVC
 185 defined when compiling into server-side stubs
 186 .It Dv RPC_CLNT
 187 defined when compiling into client-side stubs
 188 .It Dv RPC_TBL
 189 defined when compiling into RPC dispatch tables
 190 .El
 191 .Lp
 192 Any line beginning with
 193 .Dq %
 194 is passed directly into the output file,
 195 uninterpreted by
 196 .Nm ,
 197 except that the leading
 198 .Dq %
 199 is stripped
 200 off. To specify the path name of the C preprocessor, use the
 201 .Fl Y
 202 flag.
 203 .Lp
 204 For every data type referred to in
 205 .Ar infile ,
 206 .Nm
 207 assumes that
 208 there exists a routine with the string
 209 .Sy xdr_
 210 prepended to the name of the
 211 data type. If this routine does not exist in the RPC/XDR library,
 212 it must be provided. Providing an undefined data type allows customization of
 213 XDR routines.
 214 .Ss "Server Error Reporting"
 215 By default, errors detected by
 216 .Pa proto_svc.c
 217 is reported to standard error and/or the system log.
 218 .Lp
 219 This behavior can be overridden by compiling the file with a definition of
 220 .Dv RPC_MSGOUT ,
 221 for example,
 222 .Fl D Dv RPC_MSGOUT  Ns = Ns Ar mymsgfunc .
 223 The function
 224 specified is called to report errors. It must conform to the following
 225 .Xr printf 3C
 226 style signature:
 227 .Lp
 228 .Dl extern void RPC_MSGOUT(const char *fmt, ...);
 229 .Sh OPTIONS
 230 The following options are supported:
 231 .Bl -tag -width Fl
 232 .
 233 .It Fl a
 234 Generates all files, including sample files.
 235 .
 236 .It Fl A
 237 Enables the Automatic
 238 MT mode in the server main program. In this mode,
 239 the RPC library automatically creates threads to service client requests.
 240 This option generates multithread-safe stubs by implicitly turning on the
 241 .Fl M
 242 option. Server multithreading modes and parameters can be set using
 243 the
 244 .Xr rpc_control 3NSL
 245 call.
 246 .Nm
 247 generated code does not change
 248 the default values for the Automatic MT mode.
 249 .
 250 .It Fl b
 251 Backward compatibility mode. Generates transport-specific RPC code for
 252 older versions of the operating system.
 253 .
 254 .It Fl c
 255 Compiles into XDR routines.
 256 .
 257 .It Fl C
 258 Generates header and stub files which can be used with ANSI C compilers.
 259 Headers generated with this flag can also be used with C++ programs.  This
 260 behavior is now default, and therefore this option
 261 is redundant.  It remains here for compatibility.
 262 .It Fl D Ar name Ns Op = Ns Ar value
 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 .
 267 .It Fl h
 268 Compiles into C data-definitions (a header). The
 269 .Fl T
 270 option can be
 271 used in conjunction to produce a header which supports RPC dispatch
 272 tables.
 273 .
 274 .It Fl i Ar size
 275 Size at which to start generating inline code. This option is useful for
 276 optimization. The default
 277 .Ar size
 278 is 5.
 279 .
 280 .It Fl I
 281 Compiles support for
 282 .Xr inetd 1M
 283 in the server side stubs. Such servers can
 284 be self-started or can be started by
 285 .Xr inetd 3C .
 286 When the server is
 287 self-started, it backgrounds itself by default. A special define symbol
 288 .Dv RPC_SVC_FG
 289 can be used to run the server process in foreground, or the
 290 user can simply compile without the
 291 .Fl I
 292 option.
 293 .Lp
 294 If there are no pending client requests, the
 295 .Xr inetd 1M
 296 servers exit after 120
 297 seconds (default). The default can be changed with the
 298 .Fl -K
 299 option. All of
 300 the error messages for
 301 .Xr inetd 1M
 302 servers are always logged with
 303 .Xr syslog 3C .
 304 .Lp
 305 .Em Note:
 306 This option is supported for backward compatibility only. It should
 307 always be used in conjunction with the
 308 .Fl b
 309 option which generates backward
 310 compatibility code. By default (that is, when
 311 .Fl b
 312 is not specified),
 313 .Nm
 314 generates servers that can be invoked through portmonitors.
 315 .
 316 .It Fl K Ar seconds
 317 By default, services created using
 318 .Nm
 319 and invoked through port
 320 monitors wait 120 seconds after servicing a request before exiting. That
 321 interval can be changed using the
 322 .Fl K
 323 flag. To create a server that exits
 324 immediately upon servicing a request, use
 325 .Fl K Li 0 .
 326 To create a server
 327 that never exits, the appropriate argument is
 328 .Fl K Li \(mi1 .
 329 .Lp
 330 When monitoring for a server, some portmonitors, like
 331 .Xr listen 1M ,
 332 .Em always
 333 spawn a new process in response to a service request. If it is
 334 known that a server are used with such a monitor, the server should exit
 335 immediately on completion. For such servers,
 336 .Nm
 337 should be used with
 338 .Fl K Li 0 .
 339 .
 340 .It Fl l
 341 Compiles into client-side stubs.
 342 .
 343 .It Fl L
 344 When the servers are started in foreground, uses
 345 .Xr syslog 3C
 346 to log the server errors instead of printing them on the standard error.
 347 .
 348 .It Fl m
 349 Compiles into server-side stubs, but do not generate a "main" routine. This
 350 option is useful for doing callback-routines and for users who need to write
 351 their own "main" routine to do initialization.
 352 .
 353 .It Fl M
 354 Generates multithread-safe stubs for passing arguments and results between
 355 code generated by
 356 .Nm rpcgen
 357 and user written code. This option is useful for
 358 users who want to use threads in their code.
 359 .
 360 .It Fl N
 361 This option allows procedures to have multiple arguments. It also uses the
 362 style of parameter passing that closely resembles C. So, when passing an
 363 argument to a remote procedure, you do not have to pass a pointer to the
 364 argument, but can pass the argument itself. This behavior is different from the
 365 old style of code generated by
 366 .Nm .
 367 To maintain backward compatibility, this option is not the default.
 368 .
 369 .It Fl n Ar netid
 370 Compiles into server-side stubs for the transport specified by
 371 .Ar netid .
 372 There should be an entry for
 373 .Ar netid
 374 in the
 375 .Xr netconfig 4
 376 database. This
 377 option can be specified more than once, so as to compile a server that serves
 378 multiple transports.
 379 .
 380 .It Fl o Ar outfile
 381 Specifies the name of the output file. If none is specified, standard output is
 382 used
 383 .Po
 384 .Fl c , h , l , m , n , s , "Sc" , "Sm" , "Ss" ,
 385 and
 386 .Fl t
 387 modes only
 388 .Pc .
 389 .
 390 .It Fl s Ar netttype
 391 Compiles into server-side stubs for all the transports belonging to the class
 392 .Ar nettype .
 393 The supported classes are
 394 .Sy netpath ,
 395 .Sy visible ,
 396 .Sy circuit_n ,
 397 .Sy circuit_v ,
 398 .Sy datagram_n ,
 399 .Sy datagram_v ,
 400 .Sy tcp ,
 401 and
 402 .Sy udp
 403 (see
 404 .Xr rpc 3NSL
 405 for the meanings associated with
 406 these classes). This option can be specified more than once.
 407 .Em Note:
 408 The transports are chosen at run time and not at compile time.
 409 .
 410 .It Fl "Sc"
 411 Generates sample client code that uses remote procedure calls.
 412 .
 413 .It Fl "Sm"
 414 Generates a sample Makefile which can be used for compiling the application.
 415 .
 416 .It Fl "Ss"
 417 Generates sample server code that uses remote procedure calls.
 418 .
 419 .It Fl t
 420 Compiles into RPC dispatch table.
 421 .
 422 .It Fl T
 423 Generates the code to support RPC dispatch tables.
 424 .Lp
 425 The options
 426 .Fl c , h , l , m , s R, "Sc" , "Sm" , "Ss" ,
 427 and
 428 .Fl t
 429 are used exclusively to generate a
 430 particular type of file, while the options
 431 .Fl D
 432 and
 433 .Fl T
 434 are global and can be used with the other options.
 435 .
 436 .It Fl v
 437 Displays the version number.
 438 .
 439 .It Fl Y Ar pathname
 440 Gives the name of the directory where
 441 .Nm
 442 starts looking for the C preprocessor.
 443 .El
 444 .Sh OPERANDS
 445 The following operand is supported:
 446 .Bl -tag -width Ar
 447 .
 448 .It Ar infile
 449 input file
 450 .El
 451 .Sh EXIT STATUS
 452 .Ex -std
 453 .Sh EXAMPLES
 454 .Ss Example 1 Generating the output files and dispatch table
 455 The following entry
 456 .Lp
 457 .Dl example% rpcgen -T prot.x
 458 .Lp
 459 generates all the five files:
 460 .Pa prot.h , prot_clnt.c R, prot_svc.c , prot_xdr.c ,
 461 and
 462 .Pa prot_tbl.i .
 463 .
 464 .Ss Example 2 Sending headers to standard output
 465 The following example sends the C data-definitions (header) to the standard
 466 output:
 467 .Lp
 468 .Dl example% rpcgen -h prot.x
 469 .
 470 .Ss Example 3 Sending a test version
 471 To send the test version of the
 472 .Fl DTEST ,
 473 server side stubs for all the
 474 transport belonging to the class
 475 .Sy datagram_n
 476 to standard output, use:
 477 .Lp
 478 .Dl example% rpcgen -s datagram_n -DTEST prot.x
 479 .
 480 .Ss Example 4 Creating server side stubs
 481 To create the server side stubs for the transport indicated by
 482 .Ar netid
 483 .Sy tcp ,
 484 use:
 485 .Lp
 486 .Dl example% rpcgen -n tcp -o prot_svc.c prot.x
 487 .Sh SEE ALSO
 488 .Xr inetd 1M ,
 489 .Xr listen 1M ,
 490 .Xr rpc 3NSL ,
 491 .Xr rpc_control 3NSL ,
 492 .Xr rpc_svc_calls 3NSL ,
 493 .Xr syslog 3C ,
 494 .Xr netconfig 4 ,
 495 .Xr attributes 5
 496 .Rs
 497 .%B ONC+ Developer\&'s Guide
 498 .Re