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