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 .It Fl K Ar seconds
 332 By default, services created using
 333 .Nm
 334 and invoked through
 335 port monitors wait 120 seconds
 336 after servicing a request before exiting.
 337 That interval can be changed using the
 338 .Fl K
 339 flag.
 340 To create a server that exits immediately upon servicing a request,
 341 use
 342 .Fl K Ar 0 .
 343 To create a server that never exits, the appropriate argument is
 344 .Fl K Ar -1 .
 345 .Pp
 346 When monitoring for a server,
 347 some portmonitors
 348 .Em always
 349 spawn a new process in response to a service request.
 350 If it is known that a server will be used with such a monitor, the
 351 server should exit immediately on completion.
 352 For such servers,
 353 .Nm
 354 should be used with
 355 .Fl K Ar 0 .
 356 .It Fl l
 357 Compile into client-side stubs.
 358 .It Fl L
 359 When the servers are started in foreground, use
 360 .Xr syslog 3
 361 to log the server errors instead of printing them on the standard
 362 error.
 363 .It Fl m
 364 Compile into server-side stubs,
 365 but do not generate a
 366 .Qq main
 367 routine.
 368 This option is useful for doing callback-routines
 369 and for users who need to write their own
 370 .Qq main
 371 routine to do initialization.
 372 .It Fl M
 373 Generate multithread-safe stubs for passing arguments and results between
 374 rpcgen generated code and user written code.
 375 This option is useful
 376 for users who want to use threads in their code.
 377 However, the
 378 .Xr rpc_svc_calls 3
 379 functions are not yet MT-safe, which means that rpcgen generated server-side
 380 code will not be MT-safe.
 381 .It Fl N
 382 Allow procedures to have multiple arguments.
 383 It also uses the style of parameter passing that closely resembles C.
 384 So, when passing an argument to a remote procedure, you do not have to
 385 pass a pointer to the argument, but can pass the argument itself.
 386 This behavior is different from the old style of
 387 .Nm
 388 generated code.
 389 To maintain backward compatibility,
 390 this option is not the default.
 391 .It Fl n Ar netid
 392 Compile into server-side stubs for the transport
 393 specified by
 394 .Ar netid .
 395 There should be an entry for
 396 .Ar netid
 397 in the
 398 netconfig database.
 399 This option may be specified more than once,
 400 so as to compile a server that serves multiple transports.
 401 .It Fl o Ar outfile
 402 Specify the name of the output file.
 403 If none is specified,
 404 standard output is used
 405 .Fl ( c ,
 406 .Fl h ,
 407 .Fl l ,
 408 .Fl m ,
 409 .Fl n ,
 410 .Fl s ,
 411 .Fl \&Sc ,
 412 .Fl \&Sm ,
 413 .Fl \&Ss ,
 414 and
 415 .Fl t
 416 modes only).
 417 .It Fl P
 418 Compile support for
 419 port monitors
 420 in the server side stubs.
 421 .Pp
 422 Note:
 423 Contrary to some systems, in
 424 .Fx
 425 this option is needed to generate
 426 servers that can be monitored.
 427 .Pp
 428 If the
 429 .Fl I
 430 option has been specified,
 431 .Fl P
 432 is turned off automatically.
 433 .It Fl s Ar nettype
 434 Compile into server-side stubs for all the
 435 transports belonging to the class
 436 .Ar nettype .
 437 The supported classes are
 438 .Em netpath ,
 439 .Em visible ,
 440 .Em circuit_n ,
 441 .Em circuit_v ,
 442 .Em datagram_n ,
 443 .Em datagram_v ,
 444 .Em tcp ,
 445 and
 446 .Em udp
 447 (see
 448 .Xr rpc 3
 449 for the meanings associated with these classes).
 450 This option may be specified more than once.
 451 Note:
 452 the transports are chosen at run time and not at compile time.
 453 .It Fl \&Sc
 454 Generate sample client code that uses remote procedure calls.
 455 .It Fl \&Sm
 456 Generate a sample
 457 .Pa Makefile
 458 which can be used for compiling the application.
 459 .It Fl \&Ss
 460 Generate sample server code that uses remote procedure calls.
 461 .It Fl t
 462 Compile into
 463 .Tn RPC
 464 dispatch table.
 465 .It Fl T
 466 Generate the code to support
 467 .Tn RPC
 468 dispatch tables.
 469 .Pp
 470 The options
 471 .Fl c ,
 472 .Fl h ,
 473 .Fl l ,
 474 .Fl m ,
 475 .Fl s ,
 476 .Fl \&Sc ,
 477 .Fl \&Sm ,
 478 .Fl \&Ss ,
 479 and
 480 .Fl t
 481 are used exclusively to generate a particular type of file,
 482 while the options
 483 .Fl D
 484 and
 485 .Fl T
 486 are global and can be used with the other options.
 487 .It Fl Y Ar pathname
 488 Give the name of the directory where
 489 .Nm
 490 will start looking for the C-preprocessor.
 491 .El
 492 .Sh ENVIRONMENT
 493 If the
 494 .Ev RPCGEN_CPP
 495 environment variable is set, its value is used as the command line of the
 496 C preprocessor to be run on the input file.
 497 .Sh EXAMPLES
 498 The following example:
 499 .Dl example% rpcgen -T prot.x
 500 .Pp
 501 generates all the five files:
 502 .Pa prot.h ,
 503 .Pa prot_clnt.c ,
 504 .Pa prot_svc.c ,
 505 .Pa prot_xdr.c
 506 and
 507 .Pa prot_tbl.i .
 508 .Pp
 509 The following example sends the C data-definitions (header)
 510 to the standard output.
 511 .Dl example% rpcgen -h prot.x
 512 .Pp
 513 To send the test version of the
 514 .Fl D Ns Ar TEST ,
 515 server side stubs for
 516 all the transport belonging to the class
 517 .Ar datagram_n
 518 to standard output, use:
 519 .Dl example% rpcgen -s datagram_n -DTEST prot.x
 520 .Pp
 521 To create the server side stubs for the transport indicated
 522 by
 523 .Ar netid
 524 tcp,
 525 use:
 526 .Dl example% rpcgen -n tcp -o prot_svc.c prot.x
 527 .Sh SEE ALSO
 528 .Xr cc 1 ,
 529 .Xr rpc 3 ,
 530 .Xr rpc_svc_calls 3 ,
 531 .Xr syslog 3 ,
 532 .Xr xdr 3 ,
 533 .Xr inetd 8
 534 .Rs
 535 .%T The rpcgen chapter in the NETP manual
 536 .Re