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