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