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