tools/rpcgen/rpcgen.new.1

   1 .\" @(#)rpcgen.new.1    1.1 90/11/09 TIRPC 1.0; from 40.10 of 10/10/89
   2 .\" Copyright (c) 1988,1990 Sun Microsystems, Inc. - All Rights Reserved.
   3 .nr X
   4 .if \nX=0 .ds x} rpcgen 1 "" "\&"
   5 .if \nX=1 .ds x} rpcgen 1 ""
   6 .if \nX=2 .ds x} rpcgen 1 "" "\&"
   7 .if \nX=3 .ds x} rpcgen "" "" "\&"
   8 .TH \*(x}
   9 .SH NAME
  10 \f4rpcgen\f1 \- an RPC protocol compiler
  11 .SH SYNOPSIS
  12 .ft 4
  13 .nf
  14 rpcgen \f2infile\f4
  15 .fi
  16 .ft 1
  17 .br
  18 .ft 4
  19 .nf
  20 rpcgen [\-D\f2name\f4[=\f2value\f4]] [\-T] [\-K \f2secs\fP] \f2infile\f4
  21 .fi
  22 .ft 1
  23 .br
  24 .ft 4
  25 .nf
  26 rpcgen \-c|\-h|\-l|\-m|\-t [\-o \f2outfile\f4 ] \f2infile\f4
  27 .fi
  28 .ft 1
  29 .br
  30 .ft 4
  31 .nf
  32 rpcgen \-s \f2nettype\f4 [\-o \f2outfile\f4] \f2infile\f4
  33 .fi
  34 .ft 1
  35 .br
  36 .ft 4
  37 .nf
  38 rpcgen \-n \f2netid\f4 [\-o \f2outfile\f4] \f2infile\f4
  39 .ft 1
  40 .SH DESCRIPTION
  41 .P
  42 \f4rpcgen\f1
  43 is a tool that generates C code to implement an RPC protocol.
  44 The input to
  45 \f4rpcgen\f1
  46 is a language similar to C known as
  47 RPC Language (Remote Procedure Call Language).
  48 .P
  49 \f4rpcgen\f1
  50 is normally used as in the first synopsis where
  51 it takes an input file and generates up to four output files.
  52 If the
  53 \f2infile\f1
  54 is named
  55 \f4proto.x\f1,
  56 then
  57 \f4rpcgen\f1
  58 will generate a header file in
  59 \f4proto.h\f1,
  60 XDR routines in
  61 \f4proto_xdr.c\f1,
  62 server-side stubs in
  63 \f4proto_svc.c\f1,
  64 and client-side stubs in
  65 \f4proto_clnt.c\f1.
  66 With the
  67 \f4\-T\f1
  68 option,
  69 it will also generate the RPC dispatch table in
  70 \f4proto_tbl.i\f1.
  71 With the
  72 \f4\-Sc\f1
  73 option,
  74 it will also generate  sample code which would illustrate how to use the
  75 remote procedures on the client side. This code would be created in
  76 \f4proto_client.c\f1.
  77 With the
  78 \f4\-Ss\f1
  79 option,
  80 it will also generate a sample server code which would illustrate how to write
  81 the remote procedures. This code would be created in
  82 \f4proto_server.c\f1.
  83 .P
  84 The server created can be started both by the port monitors
  85 (for example, \f4inetd\f1 or \f4listen\f1)
  86 or by itself.
  87 When it is started by a port monitor,
  88 it creates servers only for the transport for which
  89 the file descriptor \f40\fP was passed.
  90 The name of the transport must be specified
  91 by setting up the environmental variable
  92 \f4PM_TRANSPORT\f1.
  93 When the server generated by
  94 \f4rpcgen\f1
  95 is executed,
  96 it creates server handles for all the transports
  97 specified in
  98 \f4NETPATH\f1
  99 environment variable,
 100 or if it is unset,
 101 it creates server handles for all the visible transports from
 102 \f4/etc/netconfig\f1
 103 file.
 104 Note:
 105 the transports are chosen at run time and not at compile time.
 106 When the server is self-started,
 107 it backgrounds itself by default.
 108 A special define symbol
 109 \f4RPC_SVC_FG\f1
 110 can be used to run the server process in foreground.
 111 .P
 112 The second synopsis provides special features which allow
 113 for the creation of more sophisticated RPC servers.
 114 These features include support for user provided
 115 \f4#defines\f1
 116 and RPC dispatch tables.
 117 The entries in the RPC dispatch table contain:
 118 .RS
 119 .PD 0
 120 .TP 3
 121 \(bu
 122 pointers to the service routine corresponding to that procedure,
 123 .TP
 124 \(bu
 125 a pointer to the input and output arguments
 126 .TP
 127 \(bu
 128 the size of these routines
 129 .PD
 130 .RE
 131 A server can use the dispatch table to check authorization
 132 and then to execute the service routine;
 133 a client library may use it to deal with the details of storage
 134 management and XDR data conversion.
 135 .P
 136 The other three synopses shown above are used when
 137 one does not want to generate all the output files,
 138 but only a particular one.
 139 Some examples of their usage is described in the
 140 EXAMPLE
 141 section below.
 142 When
 143 \f4rpcgen\f1
 144 is executed with the
 145 \f4\-s\f1
 146 option,
 147 it creates servers for that particular class of transports.
 148 When
 149 executed with the
 150 \f4\-n\f1
 151 option,
 152 it creates a server for the transport specified by
 153 \f2netid\f1.
 154 If
 155 \f2infile\f1
 156 is not specified,
 157 \f4rpcgen\f1
 158 accepts the standard input.
 159 .P
 160 The C preprocessor,
 161 \f4cc \-E\f1
 162 [see \f4cc\fP(1)],
 163 is run on the input file before it is actually interpreted by
 164 \f4rpcgen\f1.
 165 For each type of output file,
 166 \f4rpcgen\f1
 167 defines a special preprocessor symbol for use by the
 168 \f4rpcgen\f1
 169 programmer:
 170 .P
 171 .PD 0
 172 .TP 12
 173 \f4RPC_HDR\f1
 174 defined when compiling into header files
 175 .TP
 176 \f4RPC_XDR\f1
 177 defined when compiling into XDR routines
 178 .TP
 179 \f4RPC_SVC\f1
 180 defined when compiling into server-side stubs
 181 .TP
 182 \f4RPC_CLNT\f1
 183 defined when compiling into client-side stubs
 184 .TP
 185 \f4RPC_TBL\f1
 186 defined when compiling into RPC dispatch tables
 187 .PD
 188 .P
 189 Any line beginning with
 190 `\f4%\f1'
 191 is passed directly into the output file,
 192 uninterpreted by
 193 \f4rpcgen\f1.
 194 .P
 195 For every data type referred to in
 196 \f2infile\f1,
 197 \f4rpcgen\f1
 198 assumes that there exists a
 199 routine with the string
 200 \f4xdr_\f1
 201 prepended to the name of the data type.
 202 If this routine does not exist in the RPC/XDR
 203 library, it must be provided.
 204 Providing an undefined data type
 205 allows customization of XDR routines.
 206 .br
 207 .ne 10
 208 .P
 209 The following options are available:
 210 .TP
 211 \f4\-a\f1
 212 Generate all the files including sample code for client and server side.
 213 .TP
 214 \f4\-b\f1
 215 This generates code for the SunOS4.1 style of rpc. It is only
 216 for backward compatibilty. By default rpcgen generates code for
 217 Transport Independent RPC that is in Svr4 systems.
 218 .TP
 219 \f4\-c\f1
 220 Compile into XDR routines.
 221 .TP
 222 \f4\-C\f1
 223 Generate code in ANSI C. This option also generates code that could be
 224 compiled with the C++ compiler.
 225 .TP
 226 \f4\-D\f2name\f4[=\f2value\f4]\f1
 227 Define a symbol
 228 \f2name\f1.
 229 Equivalent to the
 230 \f4#define\f1
 231 directive in the source.
 232 If no
 233 \f2value\f1
 234 is given,
 235 \f2value\f1
 236 is defined as \f41\f1.
 237 This option may be specified more than once.
 238 .TP
 239 \f4\-h\f1
 240 Compile into
 241 \f4C\f1
 242 data-definitions (a header file).
 243 \f4\-T\f1
 244 option can be used in conjunction to produce a
 245 header file which supports RPC dispatch tables.
 246 .TP
 247 \f4-K\f2 secs\f1
 248 By default, services created using \f4rpcgen\fP wait \f4120\fP seconds
 249 after servicing a request before exiting.
 250 That interval can be changed using the \f4-K\fP flag.
 251 To create a server that exits immediately upon servicing a request,
 252 \f4-K\ 0\fP can be used.
 253 To create a server that never exits, the appropriate argument is
 254 \f4-K\ -1\fP.
 255 .IP
 256 When monitoring for a server,
 257 some portmonitors, like
 258 \f4listen\fP(1M),
 259 .I always
 260 spawn a new process in response to a service request.
 261 If it is known that a server will be used with such a monitor, the
 262 server should exit immediately on completion.
 263 For such servers, \f4rpcgen\fP should be used with \f4-K\ -1\fP.
 264 .TP
 265 \f4\-l\f1
 266 Compile into client-side stubs.
 267 .TP
 268 \f4\-m\f1
 269 Compile into server-side stubs,
 270 but do not generate a \(lqmain\(rq routine.
 271 This option is useful for doing callback-routines
 272 and for users who need to write their own
 273 \(lqmain\(rq routine to do initialization.
 274 .TP
 275 \f4\-n \f2netid\f1
 276 Compile into server-side stubs for the transport
 277 specified by
 278 \f2netid\f1.
 279 There should be an entry for
 280 \f2netid\f1
 281 in the
 282 netconfig database.
 283 This option may be specified more than once,
 284 so as to compile a server that serves multiple transports.
 285 .TP
 286 \f4\-N\f1
 287 Use the newstyle of rpcgen. This allows procedures to have multiple arguments.
 288 It also uses the style of parameter passing that closely resembles C. So, when
 289 passing an argument to a remote procedure you do not have to pass a pointer to
 290 the argument but the argument itself. This behaviour is different from the oldstyle
 291 of rpcgen generated code. The newstyle is not the default case because of
 292 backward compatibility.
 293 .TP
 294 \f4\-o \f2outfile\f1
 295 Specify the name of the output file.
 296 If none is specified,
 297 standard output is used
 298 (\f4\-c\f1,
 299 \f4\-h\f1,
 300 \f4\-l\f1,
 301 \f4\-m\f1,
 302 \f4\-n\f1,
 303 \f4\-s\f1,
 304 \f4\-s\Sc,
 305 \f4\-s\Ss
 306 and
 307 \f4\-t\f1
 308 modes only).
 309 .TP
 310 \f4\-s \f2nettype\f1
 311 Compile into server-side stubs for all the
 312 transports belonging to the class
 313 \f2nettype\f1.
 314 The supported classes are
 315 \f4netpath\f1,
 316 \f4visible\f1,
 317 \f4circuit_n\f1,
 318 \f4circuit_v\f1,
 319 \f4datagram_n\f1,
 320 \f4datagram_v\f1,
 321 \f4tcp\f1,
 322 and
 323 \f4udp\f1
 324 [see \f4rpc\fP(3N)
 325 for the meanings associated with these classes].
 326 This option may be specified more than once.
 327 Note:
 328 the transports are chosen at run time and not at compile time.
 329 .TP
 330 \f4\-Sc\f1
 331 Generate sample code to show the use of remote procedure and how to bind
 332 to the server before calling the client side stubs generated by rpcgen.
 333 .TP
 334 \f4\-Ss\f1
 335 Generate skeleton code for the remote procedures on the server side. You would need
 336 to fill in the actual code for the remote procedures.
 337 .TP
 338 \f4\-t\f1
 339 Compile into RPC dispatch table.
 340 .TP
 341 \f4\-T\f1
 342 Generate the code to support RPC dispatch tables.
 343 .P
 344 The options
 345 \f4\-c\f1,
 346 \f4\-h\f1,
 347 \f4\-l\f1,
 348 \f4\-m\f1,
 349 \f4\-s\f1
 350 and
 351 \f4\-t\f1
 352 are used exclusively to generate a particular type of file,
 353 while the options
 354 \f4\-D\f1
 355 and
 356 \f4\-T\f1
 357 are global and can be used with the other options.
 358 .br
 359 .ne 5
 360 .SH NOTES
 361 The RPC Language does not support nesting of structures.
 362 As a work-around,
 363 structures can be declared at the top-level,
 364 and their name used inside other structures in
 365 order to achieve the same effect.
 366 .P
 367 Name clashes can occur when using program definitions,
 368 since the apparent scoping does not really apply.
 369 Most of these can be avoided by giving
 370 unique names for programs,
 371 versions,
 372 procedures and types.
 373 .P
 374 The server code generated with
 375 \f4\-n\f1
 376 option refers to the transport indicated by
 377 \f2netid\f1
 378 and hence is very site specific.
 379 .SH EXAMPLE
 380 The following example:
 381 .IP
 382 .ft 4
 383 $ rpcgen \-T prot.x
 384 .ft 1
 385 .P
 386 generates the five files:
 387 \f4prot.h\f1,
 388 \f4prot_clnt.c\f1,
 389 \f4prot_svc.c\f1,
 390 \f4prot_xdr.c\f1
 391 and
 392 \f4prot_tbl.i\f1.
 393 .P
 394 The following example sends the C data-definitions (header file)
 395 to the standard output.
 396 .IP
 397 .ft 4
 398 $ rpcgen \-h prot.x
 399 .ft 1
 400 .P
 401 To send the test version of the
 402 \f4-DTEST\f1,
 403 server side stubs for
 404 all the transport belonging to the class
 405 \f4datagram_n\f1
 406 to standard output, use:
 407 .IP
 408 .ft 4
 409 $ rpcgen \-s datagram_n \-DTEST prot.x
 410 .ft 1
 411 .P
 412 To create the server side stubs for the transport indicated
 413 by
 414 \f2netid\f1
 415 \f4tcp\f1,
 416 use:
 417 .IP
 418 .ft 4
 419 $ rpcgen \-n tcp \-o prot_svc.c prot.x
 420 .ft 1
 421 .SH "SEE ALSO"
 422 \f4cc\fP(1).