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