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