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