1.\" $NetBSD: rpcgen.1,v 1.26 2024/06/17 01:28:31 uwe 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 Ns Op Li = Ns Ar 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 \&Sc Li | 27.Fl \&Ss 28.\" .Fl \&Sm 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 \&Sc 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 \&Ss 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.Po 91for example, 92.Xr inetd 8 93or 94.Xr listen 1M \" sic! System V 95.Pc 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 preprocessor symbol 120.Dv RPC_SVC_FG 121can be used to run the server process in foreground. 122.Pp 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 #define Ns s 129and 130.Tn RPC 131dispatch tables. 132The entries in the 133.Tn RPC 134dispatch table contain: 135.Pp 136.\" XXX: uwe: -dash has too much space after the dash and causes the 137.\" first item to exceed the page width in text mode. 138.Bl -inset -offset indent -compact 139.It - 140pointers to the service routine corresponding to that procedure, 141.It - 142a pointer to the input and output arguments, 143.It - 144the size of these routines 145.El 146.Pp 147A server can use the dispatch table to check authorization 148and then to execute the service routine; 149a client library may use it to deal with the details of storage 150management and 151.Tn XDR 152data conversion. 153.Pp 154The other three synopses shown above are used when 155one does not want to generate all the output files, 156but only a particular one. 157Some examples of their usage is described in the 158.Sx EXAMPLES 159section below. 160When 161.Nm 162is executed with the 163.Fl s 164option, 165it creates servers for that particular class of transports. 166When 167executed with the 168.Fl n 169option, 170it creates a server for the transport specified by 171.Ar netid . 172If 173.Ar infile 174is not specified, 175.Nm 176accepts the standard input. 177.Pp 178The C preprocessor, 179.Xr cpp 1 180is run on the input file before it is actually interpreted by 181.Nm . 182For each type of output file, 183.Nm 184defines a special preprocessor symbol for use by the 185.Nm 186programmer: 187.Bl -tag -offset indent -width Dv 188.It Dv RPC_HDR 189defined when compiling into header files 190.It Dv RPC_XDR 191defined when compiling into 192.Tn XDR 193routines 194.It Dv RPC_SVC 195defined when compiling into server-side stubs 196.It Dv RPC_CLNT 197defined when compiling into client-side stubs 198.It Dv RPC_TBL 199defined when compiling into 200.Tn RPC 201dispatch tables 202.El 203.Pp 204Any line beginning with 205.Ql % 206is passed directly into the output file, 207uninterpreted by 208.Nm . 209.Pp 210For every data type referred to in 211.Ar infile 212.Nm 213assumes that there exists a 214routine with the string 215.Ql xdr_ 216prepended to the name of the data type. 217If this routine does not exist in the 218.Tn RPC/XDR 219library, it must be provided. 220Providing an undefined data type 221allows customization of 222.Tn XDR 223routines. 224.Sh OPTIONS 225.Bl -tag -width Fl 226.It Fl A 227Generate an 228.Fn svc_caller 229function. 230.It Fl a 231Generate all the files including sample code for client and server side. 232.It Fl B 233Generate BSD cplusplus macros 234.Pq Dv __BEGIN_DECLS , Dv __END_DECLS . 235.It Fl b 236Compile stubs in 237.Dq backwards compatible 238mode, disabling support for 239transport-independent RPC. 240.Bd -filled -offset indent 241.Em Note : 242The 243.Fl b 244should 245.Em always 246be specified when generating files for 247.Nx , 248since there is no transport-independent RPC support in 249.Nx . 250.Ed 251.It Fl c 252Compile into 253.Tn XDR 254routines. 255.It Fl D Ar name Ns Op Ar =value 256Define a symbol 257.Dv name . 258Equivalent to the 259.Li #define 260directive in the source. 261If no 262.Ar value 263is given, 264.Ar value 265is defined as 1. 266This option may be specified more than once. 267.It Fl h 268Compile into C data-definitions (a header file). 269The 270.Fl T 271option can be used in conjunction to produce a 272header file which supports 273.Tn RPC 274dispatch tables. 275.It Fl I 276Support 277.Xr inetd 8 278in the server side stubs. 279Servers generated using this flag can either be standalone or 280started from 281.Xr inetd 8 . 282If a server is started as standalone, then it places itself 283in the background, unless 284.Dv RCP_SVC_FG 285is defined, or the server is compiled without 286.Fl I . 287.It Fl i Ar size 288Size to decide when to start generating inline code. 289The default size is 3. 290.It Fl K Ar secs 291By default, services created using 292.Nm 293wait 120 seconds 294after servicing a request before exiting. 295That interval can be changed using the 296.Fl K 297flag. 298To create a server that exits immediately upon servicing a request, 299.Fl K Cm 0 300can be used. 301To create a server that never exits, the appropriate argument is 302.Fl K Cm \-1 . 303.Pp 304When monitoring for a server, 305some port monitors, like the 306.At V.4 307utility 308.Xr listen 1M , 309.Em always 310spawn a new process in response to a service request. 311If it is known that a server will be used with such a monitor, the 312server should exit immediately on completion. 313For such servers, 314.Nm 315should be used with 316.Fl K Cm \-1 . 317.It Fl L 318Server errors will be sent to 319.Xr syslog 3 320instead of 321.Va stderr . 322.It Fl l 323Compile into client-side stubs. 324.Xr inetd 8 . 325.It Fl M 326Generate thread-safe stubs. 327This alters the calling pattern of client and 328server stubs so that storage for results is allocated by the caller. 329Note 330that all components for a particular service 331(stubs, client and service wrappers, 332.Em etc . ) 333must be built either with or without the 334.Fl M 335flag. 336.It Fl m 337Compile into server-side stubs, 338but do not generate a 339.Fn main 340routine. 341This option is useful for doing callback-routines 342and for users who need to write their own 343.Fn main 344routine to do initialization. 345.It Fl N 346Use the newstyle of 347.Nm . 348This allows procedures to have multiple arguments. 349It also uses the style of parameter passing that closely resembles C. 350So, when passing an argument to a remote procedure you do not have 351to pass a pointer to the argument but the argument itself. 352This behaviour is different from the oldstyle 353of 354.Nm 355generated code. 356The newstyle is not the default case because of backward compatibility. 357.It Fl n Ar netid 358Compile into server-side stubs for the transport 359specified by 360.Ar netid . 361There should be an entry for 362.Ar netid 363in the 364netconfig database. 365This option may be specified more than once, 366so as to compile a server that serves multiple transports. 367.It Fl o Ar outfile 368Specify the name of the output file. 369If none is specified, 370standard output is used 371.Po 372.Fl c , Fl h , Fl l , Fl m , Fl n , Fl s 373modes only 374.Pc 375.It Fl s Ar nettype 376Compile into server-side stubs for all the 377transports belonging to the class 378.Ar nettype . 379The supported classes are 380.Cm netpath , 381.Cm visible , 382.Cm circuit_n , 383.Cm circuit_v , 384.Cm datagram_n , 385.Cm datagram_v , 386.Cm tcp , 387and 388.Cm udp 389See 390.Xr rpc 3 391for the meanings associated with these classes. 392.Bd -filled -offset indent 393.Em Note : 394.Nx 395currently supports only the 396.Cm tcp 397and 398.Cm udp 399classes 400.Ed 401.Pp 402This option may be specified more than once. 403.Bd -filled -offset indent 404.Em Note : 405the transports are chosen at run time and not at compile time. 406.Ed 407.It Fl \&Sc 408Generate sample code to show the use of remote procedure and how to bind 409to the server before calling the client side stubs generated by 410.Nm . 411.It Fl \&Ss 412Generate skeleton code for the remote procedures on the server side. 413You would need 414to fill in the actual code for the remote procedures. 415.\" .It Fl \&Sm 416.\" Generate a sample Makefile that can be used to compile the application. 417.It Fl T 418Generate the code to support 419.Tn RPC 420dispatch tables. 421.It Fl t 422Compile into 423.Tn RPC 424dispatch table. 425.It Fl v 426Display the version number. 427.It Fl Y Ar pathname 428Specify the directory where 429.Nm 430looks for the C preprocessor. 431.El 432.Pp 433The options 434.Fl c , 435.Fl h , 436.Fl l , 437.Fl m , 438.Fl s , 439and 440.Fl t 441are used exclusively to generate a particular type of file, 442while the options 443.Fl D 444and 445.Fl T 446are global and can be used with the other options. 447.Sh ENVIRONMENT 448If the 449.Ev RPCGEN_CPP 450environment variable is set, its value is used as the pathname of the 451C preprocessor to be run on the input file. 452.Sh NOTES 453The 454.Tn RPC 455Language does not support nesting of structures. 456As a work-around, 457structures can be declared at the top-level, 458and their name used inside other structures in 459order to achieve the same effect. 460.Pp 461Name clashes can occur when using program definitions, 462since the apparent scoping does not really apply. 463Most of these can be avoided by giving 464unique names for programs, 465versions, 466procedures and types. 467.Pp 468The server code generated with 469.Fl n 470option refers to the transport indicated by 471.Ar netid 472and hence is very site specific. 473.Sh EXAMPLES 474The command 475.Pp 476.Dl $ rpcgen -T prot.x 477.Pp 478generates the five files: 479.Pa prot.h , 480.Pa prot_clnt.c , 481.Pa prot_svc.c , 482.Pa prot_xdr.c 483and 484.Pa prot_tbl.i . 485.Pp 486The following example sends the C data-definitions (header file) 487to standard output. 488.Pp 489.Dl $ rpcgen -h prot.x 490.Pp 491To send the test version of the 492.Ql -DTEST , 493server side stubs for 494all the transport belonging to the class 495.Cm datagram_n 496to standard output, use: 497.Pp 498.Dl $ rpcgen -s datagram_n -DTEST prot.x 499.Pp 500To create the server side stubs for the transport indicated by 501.Ar netid 502.Cm tcp , 503use: 504.Dl $ rpcgen -n tcp -o prot_svc.c prot.x 505.Sh SEE ALSO 506.Xr cpp 1 , 507.Xr inetd 8 508.Sh HISTORY 509The 510.Fl M 511option was first implemented in RedHat Linux, and was reimplemented by 512Charles M. Hannum in 513.Nx 1.6 . 514