1.\" $NetBSD: rpcgen.1,v 1.15 2003/02/25 10:35:52 wiz Exp $ 2.\" from: @(#)rpcgen.new.1 1.1 90/11/09 TIRPC 1.0; from 40.10 of 10/10/89 3.\" Copyright (c) 1988,1990 Sun Microsystems, Inc. - All Rights Reserved. 4.Dd January 6, 2003 5.Dt RPCGEN 1 6.Sh NAME 7.Nm rpcgen 8.Nd Remote Procedure Call (RPC) protocol compiler 9.Sh SYNOPSIS 10.Nm 11.Ar infile 12.Nm 13.Op Fl D Op Ar name=value 14.Op Fl A 15.Op Fl M 16.Op Fl T 17.Op Fl K Ar secs 18.Ar infile 19.Nm 20.Op Fl b 21.Op Fl I 22.Op Fl L 23.Op Fl M 24.Fl c Li | 25.Fl h Li | 26.Fl l Li | 27.Fl m Li | 28.Fl t Li | 29.Fl S\&c Li | 30.Fl S\&s 31.Op Fl o Ar outfile 32.Op Ar infile 33.Nm 34.Fl c Li | 35.Ar nettype 36.Op Fl o Ar outfile 37.Op Ar infile 38.Nm 39.Fl s Li | 40.Ar netid 41.Op Fl o Ar outfile 42.Op Ar infile 43.Sh DESCRIPTION 44.Nm 45is a tool that generates C code to implement an 46.Tn RPC 47protocol. 48The input to 49.Nm 50is a language similar to C known as 51.Tn RPC 52Language (Remote Procedure Call Language). 53.Nm 54is normally used as in the first synopsis where 55it takes an input file and generates up to four output files. 56If the 57.Ar infile 58is named 59.Pa proto.x , 60then 61.Nm 62will generate a header file in 63.Pa proto.h , 64.Tn XDR 65routines in 66.Pa proto_xdr.c , 67server-side stubs in 68.Pa proto_svc.c , 69and client-side stubs in 70.Pa proto_clnt.c . 71With the 72.Fl T 73option, 74it will also generate the 75.Tn RPC 76dispatch table in 77.Pa proto_tbl.i . 78With the 79.Fl S\&c 80option, 81it will also generate sample code which would illustrate how to use the 82remote procedures on the client side. 83This code would be created in 84.Pa proto_client.c . 85With the 86.Fl S\&s 87option, 88it will also generate a sample server code which would illustrate how to write 89the remote procedures. 90This code would be created in 91.Pa proto_server.c . 92.Pp 93The server created can be started both by the port monitors 94(for example, 95.Em inetd 96or 97.Em listen ) 98or by itself. 99When it is started by a port monitor, 100it creates servers only for the transport for which 101the file descriptor 0 was passed. 102The name of the transport must be specified 103by setting up the environmental variable 104.Ev PM_TRANSPORT . 105When the server generated by 106.Nm 107is executed, 108it creates server handles for all the transports 109specified in 110.Ev NETPATH 111environment variable, 112or if it is unset, 113it creates server handles for all the visible transports from 114.Pa /etc/netconfig 115file. 116.Pp 117.Em Note : 118the transports are chosen at run time and not at compile time. 119When the server is self-started, 120it backgrounds itself by default. 121A special define symbol 122.Dv RPC_SVC_FG 123can be used to run the server process in foreground. 124.P 125The second synopsis provides special features which allow 126for the creation of more sophisticated 127.Tn RPC 128servers. 129These features include support for user provided 130.Li #defines 131and 132.Tn RPC 133dispatch tables. 134The entries in the 135.Tn RPC 136dispatch table contain: 137.Pp 138.Bl -inset -offset indent -compact 139.It + 140pointers to the service routine corresponding to that procedure, 141.It + 142a pointer to the input and output arguments, 143.It + 144the size of these routines 145.El 146.Pp 147A server can use the dispatch table to check authorization 148and then to execute the service routine; 149a client library may use it to deal with the details of storage 150management and 151.Tn XDR 152data conversion. 153.Pp 154The other three synopses shown above are used when 155one does not want to generate all the output files, 156but only a particular one. 157Some examples of their usage is described in the 158.Sx EXAMPLES 159section below. 160When 161.Nm 162is executed with the 163.Fl s 164option, 165it creates servers for that particular class of transports. 166When 167executed with the 168.Fl n 169option, 170it creates a server for the transport specified by 171.Em netid . 172If 173.Ar infile 174is not specified, 175.Nm 176accepts the standard input. 177.Pp 178The C preprocessor, 179.Xr cpp 1 180is run on the input file before it is actually interpreted by 181.Nm 182For each type of output file, 183.Nm 184defines a special preprocessor symbol for use by the 185.Nm 186programmer: 187.Bl -tag -width RPC_CLNT 188.It Dv RPC_HDR 189defined when compiling into header files 190.It Dv RPC_XDR 191defined when compiling into 192.Tn XDR 193routines 194.It Dv RPC_SVC 195defined when compiling into server-side stubs 196.It Dv RPC_CLNT 197defined when compiling into client-side stubs 198.It Dv RPC_TBL 199defined when compiling into 200.Tn RPC 201dispatch tables 202.El 203.Pp 204Any line beginning with 205.Sq % 206is passed directly into the output file, 207uninterpreted by 208.Nm . 209.Pp 210For every data type referred to in 211.Ar infile 212.Nm 213assumes that there exists a 214routine with the string 215.Dq xdr_ 216prepended to the name of the data type. 217If this routine does not exist in the 218.Tn RPC/XDR 219library, it must be provided. 220Providing an undefined data type 221allows customization of 222.Tn XDR 223routines. 224.Sh OPTIONS 225.Bl -tag -width indent 226.It Fl a 227Generate all the files including sample code for client and server side. 228.It Fl b 229This generates code for the 230.Tn "SunOS 4.1" 231style of 232.Tn RPC . 233This is the default. 234.It Fl c 235Compile into 236.Tn XDR 237routines. 238.It Fl C 239Generate code in 240.Tn ANSI 241C. 242This option also generates code that could be compiled with the 243C++ compiler. 244.It Fl D Ar name Ns Op Ar =value 245Define a symbol 246.Dv name . 247Equivalent to the 248.Dv #define 249directive in the source. 250If no 251.Dv value 252is given, 253.Dv value 254is defined as 1. 255This option may be specified more than once. 256.It Fl h 257Compile into C data-definitions (a header file). 258The 259.Fl T 260option can be used in conjunction to produce a 261header file which supports 262.Tn RPC 263dispatch tables. 264.It Fl K Ar secs 265By default, services created using 266.Nm 267wait 120 seconds 268after servicing a request before exiting. 269That interval can be changed using the 270.Fl K 271flag. 272To create a server that exits immediately upon servicing a request, 273.Dq Fl K No 0 274can be used. 275To create a server that never exits, the appropriate argument is 276.Dq Fl K No -1 . 277.Pp 278When monitoring for a server, 279some port monitors, like the 280.At V.4 281utility 282.Ic listen , 283.Em always 284spawn a new process in response to a service request. 285If it is known that a server will be used with such a monitor, the 286server should exit immediately on completion. 287For such servers, 288.Nm 289should be used with 290.Dq Fl K No -1 . 291.It Fl b 292Compile stubs in "backwards compatible" mode, disabling support for 293transport-independant RPC. 294.It Fl l 295Compile into client-side stubs. 296.Xr inetd 8 . 297.It Fl I 298Compile stubs meant for use in programs started by 299.Xr inetd 8 . 300.It Fl L 301Server errors will be sent to syslog instead of stderr. 302.It Fl m 303Compile into server-side stubs, 304but do not generate a 305.Fn main 306routine. 307This option is useful for doing callback-routines 308and for users who need to write their own 309.Fn main 310routine to do initialization. 311.It Fl M 312Generate thread-safe stubs. 313This alters the calling pattern of client and 314server stubs so that storage for results is allocated by the caller. 315Note 316that all components for a particular service (stubs, client and service 317wrappers, etc.) must be built either with or without the 318.Fl M 319flag. 320.It Fl n Ar netid 321Compile into server-side stubs for the transport 322specified by 323.Ar netid . 324There should be an entry for 325.Ar netid 326in the 327netconfig database. 328This option may be specified more than once, 329so as to compile a server that serves multiple transports. 330.It Fl N 331Use the newstyle of 332.Nm . 333This allows procedures to have multiple arguments. 334It also uses the style of parameter passing that closely resembles C. 335So, when passing an argument to a remote procedure you do not have 336to pass a pointer to the argument but the argument itself. 337This behaviour is different from the oldstyle 338of 339.Nm 340generated code. 341The newstyle is not the default case because of backward compatibility. 342.It Fl o Ar outfile 343Specify the name of the output file. 344If none is specified, 345standard output is used 346.Po 347.Fl c Fl h Fl l 348.Fl m Fl n Fl s 349modes only 350.Pc 351.It Fl s Ar nettype 352Compile into server-side stubs for all the 353transports belonging to the class 354.Ar nettype . 355The supported classes are 356.Em netpath , 357.Em visible , 358.Em circuit_n , 359.Em circuit_v , 360.Em datagram_n , 361.Em datagram_v , 362.Em tcp , 363and 364.Em udp 365[see 366.Xr rpc 3 367for the meanings associated with these classes. 368.Em Note : 369.Bx 370currently supports only the 371.Em tcp 372and 373.Em udp 374classes]. 375This option may be specified more than once. 376.Em Note : 377the transports are chosen at run time and not at compile time. 378.It Fl S\&c 379Generate sample code to show the use of remote procedure and how to bind 380to the server before calling the client side stubs generated by 381.Nm . 382.It Fl S\&s 383Generate skeleton code for the remote procedures on the server side. 384You would need 385to fill in the actual code for the remote procedures. 386.It Fl t 387Compile into 388.Tn RPC 389dispatch table. 390.It Fl T 391Generate the code to support 392.Tn RPC 393dispatch tables. 394.El 395.Pp 396The options 397.Fl c , 398.Fl h , 399.Fl l , 400.Fl m , 401.Fl s , 402and 403.Fl t 404are used exclusively to generate a particular type of file, 405while the options 406.Fl D 407and 408.Fl T 409are global and can be used with the other options. 410.Sh NOTES 411The 412.Tn RPC 413Language does not support nesting of structures. 414As a work-around, 415structures can be declared at the top-level, 416and their name used inside other structures in 417order to achieve the same effect. 418.Pp 419Name clashes can occur when using program definitions, 420since the apparent scoping does not really apply. 421Most of these can be avoided by giving 422unique names for programs, 423versions, 424procedures and types. 425.Pp 426The server code generated with 427.Fl n 428option refers to the transport indicated by 429.Em netid 430and hence is very site specific. 431.Sh EXAMPLES 432The command 433.Pp 434.Bd -literal -offset indent 435$ rpcgen -T prot.x 436.Ed 437.Pp 438generates the five files: 439.Pa prot.h , 440.Pa prot_clnt.c , 441.Pa prot_svc.c , 442.Pa prot_xdr.c 443and 444.Pa prot_tbl.i . 445.Pp 446The following example sends the C data-definitions (header file) 447to standard output. 448.Pp 449.Bd -literal -offset indent 450$ rpcgen -h prot.x 451.Ed 452.Pp 453To send the test version of the 454.Dv -DTEST , 455server side stubs for 456all the transport belonging to the class 457.Em datagram_n 458to standard output, use: 459.Pp 460.Bd -literal -offset indent 461$ rpcgen -s datagram_n -DTEST prot.x 462.Ed 463.Pp 464To create the server side stubs for the transport indicated by 465.Em netid 466.Em tcp , 467use: 468.Pp 469.Bd -literal -offset indent 470$ rpcgen -n tcp -o prot_svc.c prot.x 471.Ed 472.Sh SEE ALSO 473.Xr cpp 1 , 474.Xr inetd 8 475.Sh HISTORY 476The 477.Fl M 478option was first implemented in RedHat Linux, and was reimplemented by 479Charles M. Hannum in 480.Nx 1.6 . 481