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.Pp 332.It Fl K Ar seconds 333By default, services created using 334.Nm 335and invoked through 336port monitors wait 120 seconds 337after servicing a request before exiting. 338That interval can be changed using the 339.Fl K 340flag. 341To create a server that exits immediately upon servicing a request, 342use 343.Fl K Ar 0 . 344To create a server that never exits, the appropriate argument is 345.Fl K Ar -1 . 346.Pp 347When monitoring for a server, 348some portmonitors 349.Em always 350spawn a new process in response to a service request. 351If it is known that a server will be used with such a monitor, the 352server should exit immediately on completion. 353For such servers, 354.Nm 355should be used with 356.Fl K Ar 0 . 357.It Fl l 358Compile into client-side stubs. 359.It Fl L 360When the servers are started in foreground, use 361.Xr syslog 3 362to log the server errors instead of printing them on the standard 363error. 364.It Fl m 365Compile into server-side stubs, 366but do not generate a 367.Qq main 368routine. 369This option is useful for doing callback-routines 370and for users who need to write their own 371.Qq main 372routine to do initialization. 373.It Fl M 374Generate multithread-safe stubs for passing arguments and results between 375rpcgen generated code and user written code. 376This option is useful 377for users who want to use threads in their code. 378However, the 379.Xr rpc_svc_calls 3 380functions are not yet MT-safe, which means that rpcgen generated server-side 381code will not be MT-safe. 382.It Fl N 383Allow procedures to have multiple arguments. 384It also uses the style of parameter passing that closely resembles C. 385So, when passing an argument to a remote procedure, you do not have to 386pass a pointer to the argument, but can pass the argument itself. 387This behavior is different from the old style of 388.Nm 389generated code. 390To maintain backward compatibility, 391this option is not the default. 392.It Fl n Ar netid 393Compile into server-side stubs for the transport 394specified by 395.Ar netid . 396There should be an entry for 397.Ar netid 398in the 399netconfig database. 400This option may be specified more than once, 401so as to compile a server that serves multiple transports. 402.It Fl o Ar outfile 403Specify the name of the output file. 404If none is specified, 405standard output is used 406.Fl ( c , 407.Fl h , 408.Fl l , 409.Fl m , 410.Fl n , 411.Fl s , 412.Fl \&Sc , 413.Fl \&Sm , 414.Fl \&Ss , 415and 416.Fl t 417modes only). 418.It Fl P 419Compile support for 420port monitors 421in the server side stubs. 422.Pp 423Note: 424Contrary to some systems, in 425.Fx 426this option is needed to generate 427servers that can be monitored. 428.Pp 429If the 430.Fl I 431option has been specified, 432.Fl P 433is turned off automatically. 434.It Fl s Ar nettype 435Compile into server-side stubs for all the 436transports belonging to the class 437.Ar nettype . 438The supported classes are 439.Em netpath , 440.Em visible , 441.Em circuit_n , 442.Em circuit_v , 443.Em datagram_n , 444.Em datagram_v , 445.Em tcp , 446and 447.Em udp 448(see 449.Xr rpc 3 450for the meanings associated with these classes). 451This option may be specified more than once. 452Note: 453the transports are chosen at run time and not at compile time. 454.It Fl \&Sc 455Generate sample client code that uses remote procedure calls. 456.It Fl \&Sm 457Generate a sample 458.Pa Makefile 459which can be used for compiling the application. 460.It Fl \&Ss 461Generate sample server code that uses remote procedure calls. 462.It Fl t 463Compile into 464.Tn RPC 465dispatch table. 466.It Fl T 467Generate the code to support 468.Tn RPC 469dispatch tables. 470.Pp 471The options 472.Fl c , 473.Fl h , 474.Fl l , 475.Fl m , 476.Fl s , 477.Fl \&Sc , 478.Fl \&Sm , 479.Fl \&Ss , 480and 481.Fl t 482are used exclusively to generate a particular type of file, 483while the options 484.Fl D 485and 486.Fl T 487are global and can be used with the other options. 488.It Fl Y Ar pathname 489Give the name of the directory where 490.Nm 491will start looking for the C-preprocessor. 492.El 493.Sh ENVIRONMENT 494If the 495.Ev RPCGEN_CPP 496environment variable is set, its value is used as the command line of the 497C preprocessor to be run on the input file. 498.Sh EXAMPLES 499The following example: 500.Dl example% rpcgen -T prot.x 501.Pp 502generates all the five files: 503.Pa prot.h , 504.Pa prot_clnt.c , 505.Pa prot_svc.c , 506.Pa prot_xdr.c 507and 508.Pa prot_tbl.i . 509.Pp 510The following example sends the C data-definitions (header) 511to the standard output. 512.Dl example% rpcgen -h prot.x 513.Pp 514To send the test version of the 515.Fl D Ns Ar TEST , 516server side stubs for 517all the transport belonging to the class 518.Ar datagram_n 519to standard output, use: 520.Dl example% rpcgen -s datagram_n -DTEST prot.x 521.Pp 522To create the server side stubs for the transport indicated 523by 524.Ar netid 525tcp, 526use: 527.Dl example% rpcgen -n tcp -o prot_svc.c prot.x 528.Sh SEE ALSO 529.Xr cc 1 , 530.Xr rpc 3 , 531.Xr rpc_svc_calls 3 , 532.Xr syslog 3 , 533.Xr xdr 3 , 534.Xr inetd 8 535.Rs 536.%T The rpcgen chapter in the NETP manual 537.Re 538