1.\" @(#)rpcgen.1 1.35 93/06/02 SMI 2.\" $FreeBSD$ 3.\" Copyright 1985-1993 Sun Microsystems, Inc. 4.\" 5.Dd March 28, 1993 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 header and stub files which can be used with 262.Tn ANSI 263C compilers. 264Headers generated with this flag can also be 265used with C++ programs. 266.It Fl D Ns Ar name 267.It Fl D Ns Ar name=value 268.\".It Fl D Ns Ar name Ns Op Ar =value 269Define a symbol 270.Ar name . 271Equivalent to the 272.Em #define 273directive in the source. 274If no 275.Ar value 276is given, 277.Ar value 278is defined as 279.Em 1 . 280This option may be specified more than once. 281.It Fl h 282Compile into C data-definitions (a header). 283.Fl T 284option can be used in conjunction to produce a 285header which supports 286.Tn RPC 287dispatch tables. 288.It Fl i Ar size 289Size at which to start generating inline code. 290This option is useful for optimization. 291The default size is 5. 292.Pp 293Note: in order to provide backwards compatibility with the older 294.Nm 295on the 296.Fx 297platform, the default is actually 0 (which means 298that inline code generation is disabled by default). 299You 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.Xr inetd 8 . 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.Xr inetd 8 318servers exit after 120 seconds (default). 319The default can be changed with the 320.Fl K 321option. 322All the error messages for 323.Xr inetd 8 324servers 325are always logged with 326.Xr syslog 3 . 327.Pp 328Note: 329Contrary to some systems, in 330.Fx 331this option is needed to generate 332servers that can be invoked through portmonitors and 333.Xr inetd 8 . 334.Pp 335.It Fl K Ar seconds 336By default, services created using 337.Nm 338and invoked through 339port monitors wait 120 seconds 340after servicing a request before exiting. 341That interval can be changed using the 342.Fl K 343flag. 344To create a server that exits immediately upon servicing a request, 345use 346.Fl K Ar 0 . 347To create a server that never exits, the appropriate argument is 348.Fl k Ar -1 . 349.Pp 350When monitoring for a server, 351some portmonitors 352.Em always 353spawn a new process in response to a service request. 354If it is known that a server will be used with such a monitor, the 355server should exit immediately on completion. 356For such servers, 357.Nm 358should be used with 359.Fl K Ar 0 . 360.It Fl l 361Compile into client-side stubs. 362.It Fl L 363When the servers are started in foreground, use 364.Xr syslog 3 365to log the server errors instead of printing them on the standard 366error. 367.It Fl m 368Compile into server-side stubs, 369but do not generate a 370.Qq main 371routine. 372This option is useful for doing callback-routines 373and for users who need to write their own 374.Qq main 375routine to do initialization. 376.It Fl M 377Generate multithread-safe stubs for passing arguments and results between 378rpcgen generated code and user written code. 379This option is useful 380for users who want to use threads in their code. 381However, the 382.Xr rpc_svc_calls 3 383functions are not yet MT-safe, which means that rpcgen generated server-side 384code will not be MT-safe. 385.It Fl N 386Allow procedures to have multiple arguments. 387It also uses the style of parameter passing that closely resembles C. 388So, when passing an argument to a remote procedure, you do not have to 389pass a pointer to the argument, but can pass the argument itself. 390This behavior is different from the old style of 391.Nm 392generated code. 393To maintain backward compatibility, 394this option is not the default. 395.It Fl n Ar netid 396Compile into server-side stubs for the transport 397specified by 398.Ar netid . 399There should be an entry for 400.Ar netid 401in the 402netconfig database. 403This option may be specified more than once, 404so as to compile a server that serves multiple transports. 405.It Fl o Ar outfile 406Specify the name of the output file. 407If none is specified, 408standard output is used 409( 410.Fl c , 411.Fl h , 412.Fl l , 413.Fl m , 414.Fl n , 415.Fl s , 416.Fl \&Sc , 417.Fl \&Sm , 418.Fl \&Ss , 419and 420.Fl t 421modes only). 422.It Fl P 423Compile support for 424port monitors 425in the server side stubs. 426.Pp 427Note: 428Contrary to some systems, in 429.Fx 430this option is needed to generate 431servers that can be monitored. 432.Pp 433If the 434.Fl I 435option has been specified, 436.Fl P 437is turned off automatically. 438.It Fl s Ar nettype 439Compile into server-side stubs for all the 440transports belonging to the class 441.Ar nettype . 442The supported classes are 443.Em netpath , 444.Em visible , 445.Em circuit_n , 446.Em circuit_v , 447.Em datagram_n , 448.Em datagram_v , 449.Em tcp , 450and 451.Em udp 452(see 453.Xr rpc 3 454for the meanings associated with these classes). 455This option may be specified more than once. 456Note: 457the transports are chosen at run time and not at compile time. 458.It Fl \&Sc 459Generate sample client code that uses remote procedure calls. 460.It Fl \&Sm 461Generate a sample 462.Pa Makefile 463which can be used for compiling the application. 464.It Fl \&Ss 465Generate sample server code that uses remote procedure calls. 466.It Fl t 467Compile into 468.Tn RPC 469dispatch table. 470.It Fl T 471Generate the code to support 472.Tn RPC 473dispatch tables. 474.Pp 475The options 476.Fl c , 477.Fl h , 478.Fl l , 479.Fl m , 480.Fl s , 481.Fl \&Sc , 482.Fl \&Sm , 483.Fl \&Ss , 484and 485.Fl t 486are used exclusively to generate a particular type of file, 487while the options 488.Fl D 489and 490.Fl T 491are global and can be used with the other options. 492.It Fl Y Ar pathname 493Give the name of the directory where 494.Nm 495will start looking for the C-preprocessor. 496.El 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