usr.bin/rpcgen/rpcgen.1

   1 .\" @(#)rpcgen.1 1.35 93/06/02 SMI
   2 .\" $FreeBSD$
   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 rpcgen
  12 .Ar infile
  13 .Nm rpcgen
  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 rpcgen
  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 rpcgen
  42 .Op Fl s Ar nettype
  43 .Op Fl o Ar outfile
  44 .Op Ar infile
  45 .Nm rpcgen
  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 .Nm Rpcgen
  54 is a tool that generates C code to implement an
  55 .Tn RPC
  56 protocol.
  57 The input to
  58 .Nm
  59 is a language similar to C known as
  60 .Tn RPC
  61 Language (Remote Procedure Call Language).
  62 .Pp
  63 .Nm Rpcgen
  64 is normally used as in the first synopsis where
  65 it takes an input file and generates three output files.
  66 If the
  67 .Ar infile
  68 is named
  69 .Pa proto.x ,
  70 then
  71 .Nm
  72 generates a header in
  73 .Pa proto.h ,
  74 XDR routines in
  75 .Pa proto_xdr.c ,
  76 server-side stubs in
  77 .Pa proto_svc.c ,
  78 and client-side stubs in
  79 .Pa proto_clnt.c .
  80 With the
  81 .Fl T
  82 option,
  83 it also generates the
  84 .Tn RPC
  85 dispatch table in
  86 .Pa proto_tbl.i .
  87 .Pp
  88 .Nm Rpcgen
  89 can also generate sample client and server files
  90 that can be customized to suit a particular application. The
  91 .Fl \&Sc ,
  92 .Fl \&Ss
  93 and
  94 .Fl \&Sm
  95 options generate sample client, server and makefile, respectively.
  96 The
  97 .Fl a
  98 option generates all files, including sample files. If the
  99 .Ar infile
 100 is
 101 .Pa proto.x ,
 102 then the client side sample file is written to
 103 .Pa proto_client.c ,
 104 the server side sample file to
 105 .Pa proto_server.c
 106 and the sample makefile to
 107 .Pa makefile.proto .
 108 .Pp
 109 The server created can be started both by the port monitors
 110 (for example,
 111 .Xr inetd 8 )
 112 or by itself.
 113 When it is started by a port monitor,
 114 it creates servers only for the transport for which
 115 the file descriptor
 116 .Em 0
 117 was passed.
 118 The name of the transport must be specified
 119 by setting up the environment variable
 120 .Ev PM_TRANSPORT .
 121 When the server generated by
 122 .Nm
 123 is executed,
 124 it creates server handles for all the transports
 125 specified in
 126 .Ev NETPATH
 127 environment variable,
 128 or if it is unset,
 129 it creates server handles for all the visible transports from
 130 .Pa /etc/netconfig
 131 file.
 132 Note:
 133 the transports are chosen at run time and not at compile time.
 134 When the server is self-started,
 135 it backgrounds itself by default.
 136 A special define symbol
 137 .Em RPC_SVC_FG
 138 can be used to run the server process in foreground.
 139 .Pp
 140 The second synopsis provides special features which allow
 141 for the creation of more sophisticated
 142 .Tn RPC
 143 servers.
 144 These features include support for user provided
 145 .Em #defines
 146 and
 147 .Tn RPC
 148 dispatch tables.
 149 The entries in the
 150 .Tn RPC
 151 dispatch table contain:
 152 .Bl -bullet -offset indent -compact
 153 .It
 154 pointers to the service routine corresponding to that procedure,
 155 .It
 156 a pointer to the input and output arguments,
 157 .It
 158 the size of these routines.
 159 .El
 160 A server can use the dispatch table to check authorization
 161 and then to execute the service routine;
 162 a client library may use it to deal with the details of storage
 163 management and XDR data conversion.
 164 .Pp
 165 The other three synopses shown above are used when
 166 one does not want to generate all the output files,
 167 but only a particular one.
 168 See the
 169 .Sx EXAMPLES
 170 section below for examples of
 171 .Nm
 172 usage.
 173 When
 174 .Nm
 175 is executed with the
 176 .Fl s
 177 option,
 178 it creates servers for that particular class of transports.
 179 When
 180 executed with the
 181 .Fl n
 182 option,
 183 it creates a server for the transport specified by
 184 .Ar netid .
 185 If
 186 .Ar infile
 187 is not specified,
 188 .Nm
 189 accepts the standard input.
 190 .Pp
 191 The C preprocessor,
 192 .Em cc -E
 193 is run on the input file before it is actually interpreted by
 194 .Nm Ns .
 195 For each type of output file,
 196 .Nm
 197 defines a special preprocessor symbol for use by the
 198 .Nm
 199 programmer:
 200 .Bl -tag -width indent
 201 .It RPC_HDR
 202 defined when compiling into headers
 203 .It RPC_XDR
 204 defined when compiling into XDR routines
 205 .It RPC_SVC
 206 defined when compiling into server-side stubs
 207 .It RPC_CLNT
 208 defined when compiling into client-side stubs
 209 .It RPC_TBL
 210 defined when compiling into RPC dispatch tables
 211 .El
 212 .Pp
 213 Any line beginning with
 214 .Dq %
 215 is passed directly into the output file,
 216 uninterpreted by
 217 .Nm Ns .
 218 To specify the path name of the C preprocessor use
 219 .Fl Y
 220 flag.
 221 .Pp
 222 For every data type referred to in
 223 .Ar infile ,
 224 .Nm
 225 assumes that there exists a
 226 routine with the string
 227 .Em xdr_
 228 prepended to the name of the data type.
 229 If this routine does not exist in the
 230 .Tn RPC/XDR
 231 library, it must be provided.
 232 Providing an undefined data type
 233 allows customization of
 234 .Xr XDR
 235 routines.
 236 .Sh OPTIONS
 237 The following options are available:
 238 .Bl -tag -width indent
 239 .It Fl a
 240 Generate all files, including sample files.
 241 .It Fl b
 242 Backward compatibility mode.
 243 Generate transport specific
 244 .Tn RPC
 245 code for older versions
 246 of the operating system.
 247 .Pp
 248 Note: in
 249 .Bx Free ,
 250 this compatibility flag is turned on by
 251 default since
 252 .Bx Free
 253 supports only the older
 254 .Tn ONC RPC
 255 library.
 256 .It Fl c
 257 Compile into
 258 .Tn XDR
 259 routines.
 260 .It Fl C
 261 Generate header and stub files which can be used with
 262 .Tn ANSI
 263 C compilers.  Headers generated with this flag can also be
 264 used with C++ programs.
 265 .It Fl D Ns Ar name
 266 .It Fl D Ns Ar name=value
 267 .\".It Fl D Ns Ar name Ns Op Ar =value
 268 Define a symbol
 269 .Ar name .
 270 Equivalent to the
 271 .Em #define
 272 directive in the source.
 273 If no
 274 .Ar value
 275 is given,
 276 .Ar value
 277 is defined as
 278 .Em 1 .
 279 This option may be specified more than once.
 280 .It Fl h
 281 Compile into C data-definitions (a header).
 282 .Fl T
 283 option can be used in conjunction to produce a
 284 header which supports
 285 .Tn RPC
 286 dispatch tables.
 287 .It Fl i Ar size
 288 Size at which to start generating inline code.
 289 This option is useful for optimization. The default size is 5.
 290 .Pp
 291 Note: in order to provide backwards compatibility with the older
 292 .Nm
 293 on the
 294 .Bx Free
 295 platform, the default is actually 0 (which means
 296 that inline code generation is disabled by default). 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 .Nm inetd .
 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 .Nm inetd
 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 .Nm inetd
 321 servers
 322 are always logged with
 323 .Xr syslog 3 .
 324 .\" .IP
 325 .\" Note:
 326 .\" this option is supported for backward compatibility only.
 327 .\" By default,
 328 .\" .B rpcgen
 329 .\" generates servers that can be invoked through portmonitors.
 330 .Pp
 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. This option is useful
 375 for users who want to use threads in their code. However, the
 376 .Xr rpc_svc_calls 3
 377 functions are not yet MT-safe, which means that rpcgen generated server-side
 378 code will not be MT-safe.
 379 .It Fl N
 380 This option allows procedures to have multiple arguments.
 381 It also uses the style of parameter passing that closely resembles C.
 382 So, when passing an argument to a remote procedure, you do not have to
 383 pass a pointer to the argument, but can pass the argument itself.
 384 This behavior is different from the old style of
 385 .Nm
 386 generated code.
 387 To maintain backward compatibility,
 388 this option is not the default.
 389 .It Fl n Ar netid
 390 Compile into server-side stubs for the transport
 391 specified by
 392 .Ar netid .
 393 There should be an entry for
 394 .Ar netid
 395 in the
 396 netconfig database.
 397 This option may be specified more than once,
 398 so as to compile a server that serves multiple transports.
 399 .It Fl o Ar outfile
 400 Specify the name of the output file.
 401 If none is specified,
 402 standard output is used
 403 (
 404 .Fl c ,
 405 .Fl h ,
 406 .Fl l ,
 407 .Fl m ,
 408 .Fl n ,
 409 .Fl s ,
 410 .Fl \&Sc ,
 411 .Fl \&Sm ,
 412 .Fl \&Ss ,
 413 and
 414 .Fl t
 415 modes only).
 416 .It Fl s Ar nettype
 417 Compile into server-side stubs for all the
 418 transports belonging to the class
 419 .Ar nettype .
 420 The supported classes are
 421 .Em netpath ,
 422 .Em visible ,
 423 .Em circuit_n ,
 424 .Em circuit_v ,
 425 .Em datagram_n ,
 426 .Em datagram_v ,
 427 .Em tcp ,
 428 and
 429 .Em udp
 430 (see
 431 .Xr rpc 3
 432 for the meanings associated with these classes).
 433 This option may be specified more than once.
 434 Note:
 435 the transports are chosen at run time and not at compile time.
 436 .It Fl \&Sc
 437 Generate sample client code that uses remote procedure calls.
 438 .It Fl \&Sm
 439 Generate a sample
 440 .Pa Makefile
 441 which can be used for compiling the application.
 442 .It Fl \&Ss
 443 Generate sample server code that uses remote procedure calls.
 444 .It Fl t
 445 Compile into
 446 .Tn RPC
 447 dispatch table.
 448 .It Fl T
 449 Generate the code to support
 450 .Tn RPC
 451 dispatch tables.
 452 .Pp
 453 The options
 454 .Fl c ,
 455 .Fl h ,
 456 .Fl l ,
 457 .Fl m ,
 458 .Fl s ,
 459 .Fl \&Sc ,
 460 .Fl \&Sm ,
 461 .Fl \&Ss ,
 462 and
 463 .Fl t
 464 are used exclusively to generate a particular type of file,
 465 while the options
 466 .Fl D
 467 and
 468 .Fl T
 469 are global and can be used with the other options.
 470 .It Fl Y Ar pathname
 471 Give the name of the directory where
 472 .Nm
 473 will start looking for the C-preprocessor.
 474 .El
 475 .Sh EXAMPLES
 476 The following example:
 477 .Dl example% rpcgen -T prot.x
 478 .Pp
 479 generates all the five files:
 480 .Pa prot.h ,
 481 .Pa prot_clnt.c ,
 482 .Pa prot_svc.c ,
 483 .Pa prot_xdr.c
 484 and
 485 .Pa prot_tbl.i .
 486 .Pp
 487 The following example sends the C data-definitions (header)
 488 to the standard output.
 489 .Dl example% rpcgen -h prot.x
 490 .Pp
 491 To send the test version of the
 492 .Fl D Ns Ar TEST ,
 493 server side stubs for
 494 all the transport belonging to the class
 495 .Ar datagram_n
 496 to standard output, use:
 497 .Dl example% rpcgen -s datagram_n -DTEST prot.x
 498 .Pp
 499 To create the server side stubs for the transport indicated
 500 by
 501 .Ar netid
 502 tcp,
 503 use:
 504 .Dl example% rpcgen -n tcp -o prot_svc.c prot.x
 505 .Sh SEE ALSO
 506 .Xr cc 1 ,
 507 .Xr rpc 3 ,
 508 .Xr syslog 3 ,
 509 .Xr inetd 8
 510 .\" .BR rpc_svc_calls (3)
 511 .Rs
 512 .%T The Nm rpcgen No chapter in the NETP manual
 513 .Re