usr.bin/rpcgen/rpcgen.1

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