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