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