usr.bin/rpcgen/rpcgen.1

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