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