usr.bin/rpcgen/rpcgen.1

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