usr.bin/rpcgen/rpcgen.1

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