1.\" $NetBSD: rpcgen.1,v 1.24 2013/12/15 09:18:14 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 December 14, 2013 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 AaBbILMNTv 15.Op Fl D Ar name Op =value 16.Op Fl i Ar size 17.Op Fl K Ar secs 18.Op Fl Y Ar pathname 19.Ar infile 20.Nm 21.Fl c Li | 22.Fl h Li | 23.Fl l Li | 24.Fl m Li | 25.Fl t Li | 26.Fl S\&c Li | 27.Fl S\&s 28.\" .Fl S\&m 29.Op Fl o Ar outfile 30.Op Ar infile 31.Nm 32.Op Fl s Ar nettype 33.Op Fl o Ar outfile 34.Op Ar infile 35.Nm 36.Op Fl n Ar netid 37.Op Fl o Ar outfile 38.Op Ar infile 39.Sh DESCRIPTION 40.Nm 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 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 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. 79This code would be created in 80.Pa proto_client.c . 81With the 82.Fl S\&s 83option, 84it will also generate a sample server code which would illustrate how to write 85the remote procedures. 86This 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.Pp 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 an 224.Fn svc_caller 225function. 226.It Fl a 227Generate all the files including sample code for client and server side. 228.It Fl B 229Generate BSD cplusplus macros (__BEGIN_DECLS, __END_DECLS). 230.It Fl b 231Compile stubs in "backwards compatible" mode, disabling support for 232transport-independent RPC. 233The 234.Fl b 235should always be specified when generating files for 236.Nx , 237since there is no transport-independent RPC support in 238.Nx . 239.It Fl c 240Compile into 241.Tn XDR 242routines. 243.It Fl D Ar name Ns Op Ar =value 244Define a symbol 245.Dv name . 246Equivalent to the 247.Dv #define 248directive in the source. 249If no 250.Dv value 251is given, 252.Dv value 253is defined as 1. 254This option may be specified more than once. 255.It Fl h 256Compile into C data-definitions (a header file). 257The 258.Fl T 259option can be used in conjunction to produce a 260header file which supports 261.Tn RPC 262dispatch tables. 263.It Fl I 264Support 265.Xr inetd 8 266in the server side stubs. 267Servers generated using this flag can either be standalone or 268started from 269.Xr inetd 8 . 270If a server is started as standalone, then it places itself 271in the background, unless 272.Dv RCP_SVC_FG 273is defined, or the server is compiled without 274.Fl I . 275.It Fl i Ar size 276Size to decide when to start generating inline code. 277The default size is 3. 278.It Fl K Ar secs 279By default, services created using 280.Nm 281wait 120 seconds 282after servicing a request before exiting. 283That interval can be changed using the 284.Fl K 285flag. 286To create a server that exits immediately upon servicing a request, 287.Dq Fl K No 0 288can be used. 289To create a server that never exits, the appropriate argument is 290.Dq Fl K No -1 . 291.Pp 292When monitoring for a server, 293some port monitors, like the 294.At V.4 295utility 296.Ic listen , 297.Em always 298spawn a new process in response to a service request. 299If it is known that a server will be used with such a monitor, the 300server should exit immediately on completion. 301For such servers, 302.Nm 303should be used with 304.Dq Fl K No -1 . 305.It Fl L 306Server errors will be sent to syslog instead of stderr. 307.It Fl l 308Compile into client-side stubs. 309.Xr inetd 8 . 310.It Fl M 311Generate thread-safe stubs. 312This alters the calling pattern of client and 313server stubs so that storage for results is allocated by the caller. 314Note 315that all components for a particular service (stubs, client and service 316wrappers, etc.) must be built either with or without the 317.Fl M 318flag. 319.It Fl m 320Compile into server-side stubs, 321but do not generate a 322.Fn main 323routine. 324This option is useful for doing callback-routines 325and for users who need to write their own 326.Fn main 327routine to do initialization. 328.It Fl N 329Use the newstyle of 330.Nm . 331This allows procedures to have multiple arguments. 332It also uses the style of parameter passing that closely resembles C. 333So, when passing an argument to a remote procedure you do not have 334to pass a pointer to the argument but the argument itself. 335This behaviour is different from the oldstyle 336of 337.Nm 338generated code. 339The newstyle is not the default case because of backward compatibility. 340.It Fl n Ar netid 341Compile into server-side stubs for the transport 342specified by 343.Ar netid . 344There should be an entry for 345.Ar netid 346in the 347netconfig database. 348This option may be specified more than once, 349so as to compile a server that serves multiple transports. 350.It Fl o Ar outfile 351Specify the name of the output file. 352If none is specified, 353standard output is used 354.Po 355.Fl c Fl h Fl l 356.Fl m Fl n Fl s 357modes only 358.Pc 359.It Fl s Ar nettype 360Compile into server-side stubs for all the 361transports belonging to the class 362.Ar nettype . 363The supported classes are 364.Em netpath , 365.Em visible , 366.Em circuit_n , 367.Em circuit_v , 368.Em datagram_n , 369.Em datagram_v , 370.Em tcp , 371and 372.Em udp 373[see 374.Xr rpc 3 375for the meanings associated with these classes. 376.Em Note : 377.Bx 378currently supports only the 379.Em tcp 380and 381.Em udp 382classes]. 383This option may be specified more than once. 384.Em Note : 385the transports are chosen at run time and not at compile time. 386.It Fl S\&c 387Generate sample code to show the use of remote procedure and how to bind 388to the server before calling the client side stubs generated by 389.Nm . 390.It Fl S\&s 391Generate skeleton code for the remote procedures on the server side. 392You would need 393to fill in the actual code for the remote procedures. 394.\" .It Fl S\&m 395.\" Generate a sample Makefile that can be used to compile the application. 396.It Fl T 397Generate the code to support 398.Tn RPC 399dispatch tables. 400.It Fl t 401Compile into 402.Tn RPC 403dispatch table. 404.It Fl v 405Display the version number. 406.It Fl Y Ar pathname 407Specify the directory where 408.Nm 409looks for the C pre-processor. 410.El 411.Pp 412The options 413.Fl c , 414.Fl h , 415.Fl l , 416.Fl m , 417.Fl s , 418and 419.Fl t 420are used exclusively to generate a particular type of file, 421while the options 422.Fl D 423and 424.Fl T 425are global and can be used with the other options. 426.Sh ENVIRONMENT 427If the 428.Ev RPCGEN_CPP 429environment variable is set, its value is used as the pathname of the 430C preprocessor to be run on the input file. 431.Sh NOTES 432The 433.Tn RPC 434Language does not support nesting of structures. 435As a work-around, 436structures can be declared at the top-level, 437and their name used inside other structures in 438order to achieve the same effect. 439.Pp 440Name clashes can occur when using program definitions, 441since the apparent scoping does not really apply. 442Most of these can be avoided by giving 443unique names for programs, 444versions, 445procedures and types. 446.Pp 447The server code generated with 448.Fl n 449option refers to the transport indicated by 450.Em netid 451and hence is very site specific. 452.Sh EXAMPLES 453The command 454.Pp 455.Bd -literal -offset indent 456$ rpcgen -T prot.x 457.Ed 458.Pp 459generates the five files: 460.Pa prot.h , 461.Pa prot_clnt.c , 462.Pa prot_svc.c , 463.Pa prot_xdr.c 464and 465.Pa prot_tbl.i . 466.Pp 467The following example sends the C data-definitions (header file) 468to standard output. 469.Pp 470.Bd -literal -offset indent 471$ rpcgen -h prot.x 472.Ed 473.Pp 474To send the test version of the 475.Dv -DTEST , 476server side stubs for 477all the transport belonging to the class 478.Em datagram_n 479to standard output, use: 480.Pp 481.Bd -literal -offset indent 482$ rpcgen -s datagram_n -DTEST prot.x 483.Ed 484.Pp 485To create the server side stubs for the transport indicated by 486.Em netid 487.Em tcp , 488use: 489.Pp 490.Bd -literal -offset indent 491$ rpcgen -n tcp -o prot_svc.c prot.x 492.Ed 493.Sh SEE ALSO 494.Xr cpp 1 , 495.Xr inetd 8 496.Sh HISTORY 497The 498.Fl M 499option was first implemented in RedHat Linux, and was reimplemented by 500Charles M. Hannum in 501.Nx 1.6 . 502