1.\" @(#)rpcgen.1 1.35 93/06/02 SMI 2.\" $FreeBSD: src/usr.bin/rpcgen/rpcgen.1,v 1.24 2005/09/02 18:37:34 stefanf Exp $ 3.\" $DragonFly: src/usr.bin/rpcgen/rpcgen.1,v 1.4 2008/04/16 07:21:57 swildner Exp $ 4.\" Copyright 1985-1993 Sun Microsystems, Inc. 5.\" 6.Dd September 2, 2005 7.Dt RPCGEN 1 8.Os 9.Sh NAME 10.Nm rpcgen 11.Nd an RPC protocol compiler 12.Sh SYNOPSIS 13.Nm 14.Ar infile 15.Nm 16.Op Fl a 17.Op Fl b 18.Op Fl C 19.Oo 20.Fl D Ns Ar name Ns Op Ar =value 21.Oc 22.Op Fl i Ar size 23.Op Fl I Fl P Op Fl K Ar seconds 24.Op Fl L 25.Op Fl M 26.Op Fl N 27.Op Fl T 28.Op Fl Y Ar pathname 29.Ar infile 30.Nm 31.Oo 32.Fl c | 33.Fl h | 34.Fl l | 35.Fl m | 36.Fl t | 37.Fl \&Sc | 38.Fl \&Ss | 39.Fl \&Sm 40.Oc 41.Op Fl o Ar outfile 42.Op Ar infile 43.Nm 44.Op Fl s Ar nettype 45.Op Fl o Ar outfile 46.Op Ar infile 47.Nm 48.Op Fl n Ar netid 49.Op Fl o Ar outfile 50.Op Ar infile 51.\" .SH AVAILABILITY 52.\" .LP 53.\" SUNWcsu 54.Sh DESCRIPTION 55The 56.Nm 57utility is a tool that generates C code to implement an 58.Tn RPC 59protocol. 60The input to 61.Nm 62is a language similar to C known as 63.Tn RPC 64Language (Remote Procedure Call Language). 65.Pp 66The 67.Nm 68utility is normally used as in the first synopsis where 69it takes an input file and generates three output files. 70If the 71.Ar infile 72is named 73.Pa proto.x , 74then 75.Nm 76generates a header in 77.Pa proto.h , 78XDR routines in 79.Pa proto_xdr.c , 80server-side stubs in 81.Pa proto_svc.c , 82and client-side stubs in 83.Pa proto_clnt.c . 84With the 85.Fl T 86option, 87it also generates the 88.Tn RPC 89dispatch table in 90.Pa proto_tbl.i . 91.Pp 92The 93.Nm 94utility can also generate sample client and server files 95that can be customized to suit a particular application. 96The 97.Fl \&Sc , 98.Fl \&Ss 99and 100.Fl \&Sm 101options generate sample client, server and makefile, respectively. 102The 103.Fl a 104option generates all files, including sample files. 105If the 106.Ar infile 107is 108.Pa proto.x , 109then the client side sample file is written to 110.Pa proto_client.c , 111the server side sample file to 112.Pa proto_server.c 113and the sample makefile to 114.Pa makefile.proto . 115.Pp 116If option 117.Fl I 118is set, 119the server created can be started both by the port monitors 120(for example, 121.Xr inetd 8 ) 122or by itself. 123When it is started by a port monitor, 124it creates servers only for the transport for which 125the file descriptor 126.Em 0 127was passed. 128The name of the transport may be specified 129by setting up the environment variable 130.Ev NLSPROVIDER . 131When the server generated by 132.Nm 133is executed, 134it creates server handles for all the transports 135specified in 136.Ev NETPATH 137environment variable, 138or if it is unset, 139it creates server handles for all the visible transports from 140.Pa /etc/netconfig 141file. 142Note: 143the transports are chosen at run time and not at compile time. 144When the server is self-started, 145it backgrounds itself by default. 146A special define symbol 147.Em RPC_SVC_FG 148can be used to run the server process in foreground. 149.Pp 150The second synopsis provides special features which allow 151for the creation of more sophisticated 152.Tn RPC 153servers. 154These features include support for user provided 155.Em #defines 156and 157.Tn RPC 158dispatch tables. 159The entries in the 160.Tn RPC 161dispatch table contain: 162.Bl -bullet -offset indent -compact 163.It 164pointers to the service routine corresponding to that procedure, 165.It 166a pointer to the input and output arguments, 167.It 168the size of these routines. 169.El 170A server can use the dispatch table to check authorization 171and then to execute the service routine; 172a client library may use it to deal with the details of storage 173management and XDR data conversion. 174.Pp 175The other three synopses shown above are used when 176one does not want to generate all the output files, 177but only a particular one. 178See the 179.Sx EXAMPLES 180section below for examples of 181.Nm 182usage. 183When 184.Nm 185is executed with the 186.Fl s 187option, 188it creates servers for that particular class of transports. 189When 190executed with the 191.Fl n 192option, 193it creates a server for the transport specified by 194.Ar netid . 195If 196.Ar infile 197is not specified, 198.Nm 199accepts the standard input. 200.Pp 201The C preprocessor, 202.Em cc -E 203is run on the input file before it is actually interpreted by 204.Nm . 205For each type of output file, 206.Nm 207defines a special preprocessor symbol for use by the 208.Nm 209programmer: 210.Bl -tag -width indent 211.It RPC_HDR 212defined when compiling into headers 213.It RPC_XDR 214defined when compiling into XDR routines 215.It RPC_SVC 216defined when compiling into server-side stubs 217.It RPC_CLNT 218defined when compiling into client-side stubs 219.It RPC_TBL 220defined when compiling into RPC dispatch tables 221.El 222.Pp 223Any line beginning with 224.Dq % 225is passed directly into the output file, 226uninterpreted by 227.Nm . 228To specify the path name of the C preprocessor use 229.Fl Y 230flag. 231.Pp 232For every data type referred to in 233.Ar infile , 234.Nm 235assumes that there exists a 236routine with the string 237.Em xdr_ 238prepended to the name of the data type. 239If this routine does not exist in the 240.Tn RPC/XDR 241library, it must be provided. 242Providing an undefined data type 243allows customization of 244.Xr xdr 3 245routines. 246.Sh OPTIONS 247The following options are available: 248.Bl -tag -width indent 249.It Fl a 250Generate all files, including sample files. 251.It Fl b 252Backward compatibility mode. 253Generate transport specific 254.Tn RPC 255code for older versions 256of the operating system. 257.It Fl c 258Compile into 259.Tn XDR 260routines. 261.It Fl C 262Generate ANSI C code. 263This is always done, the flag is only provided for backwards compatibility. 264.It Fl D Ns Ar name 265.It Fl D Ns Ar name=value 266.\".It Fl D Ns Ar name Ns Op Ar =value 267Define a symbol 268.Ar name . 269Equivalent to the 270.Em #define 271directive in the source. 272If no 273.Ar value 274is given, 275.Ar value 276is defined as 277.Em 1 . 278This option may be specified more than once. 279.It Fl h 280Compile into C data-definitions (a header). 281.Fl T 282option can be used in conjunction to produce a 283header which supports 284.Tn RPC 285dispatch tables. 286.It Fl i Ar size 287Size at which to start generating inline code. 288This option is useful for optimization. 289The default size is 5. 290.Pp 291Note: in order to provide backwards compatibility with the older 292.Nm 293on the 294.Dx 295platform, the default is actually 0 (which means 296that inline code generation is disabled by default). 297You must specify 298a non-zero value explicitly to override this default. 299.It Fl I 300Compile support for 301.Xr inetd 8 302in the server side stubs. 303Such servers can be self-started or can be started by 304.Xr inetd 8 . 305When the server is self-started, it backgrounds itself by default. 306A special define symbol 307.Em RPC_SVC_FG 308can be used to run the 309server process in foreground, or the user may simply compile without 310the 311.Fl I 312option. 313.Pp 314If there are no pending client requests, the 315.Xr inetd 8 316servers exit after 120 seconds (default). 317The default can be changed with the 318.Fl K 319option. 320All the error messages for 321.Xr inetd 8 322servers 323are always logged with 324.Xr syslog 3 . 325.Pp 326Note: 327Contrary to some systems, in 328.Dx 329this option is needed to generate 330servers that can be invoked through portmonitors and 331.Xr inetd 8 . 332.Pp 333.It Fl K Ar seconds 334By default, services created using 335.Nm 336and invoked through 337port monitors wait 120 seconds 338after servicing a request before exiting. 339That interval can be changed using the 340.Fl K 341flag. 342To create a server that exits immediately upon servicing a request, 343use 344.Fl K Ar 0 . 345To create a server that never exits, the appropriate argument is 346.Fl K Ar -1 . 347.Pp 348When monitoring for a server, 349some portmonitors 350.Em always 351spawn a new process in response to a service request. 352If it is known that a server will be used with such a monitor, the 353server should exit immediately on completion. 354For such servers, 355.Nm 356should be used with 357.Fl K Ar 0 . 358.It Fl l 359Compile into client-side stubs. 360.It Fl L 361When the servers are started in foreground, use 362.Xr syslog 3 363to log the server errors instead of printing them on the standard 364error. 365.It Fl m 366Compile into server-side stubs, 367but do not generate a 368.Qq main 369routine. 370This option is useful for doing callback-routines 371and for users who need to write their own 372.Qq main 373routine to do initialization. 374.It Fl M 375Generate multithread-safe stubs for passing arguments and results between 376rpcgen generated code and user written code. 377This option is useful 378for users who want to use threads in their code. 379However, the 380.Xr rpc_svc_calls 3 381functions are not yet MT-safe, which means that rpcgen generated server-side 382code will not be MT-safe. 383.It Fl N 384Allow procedures to have multiple arguments. 385It also uses the style of parameter passing that closely resembles C. 386So, when passing an argument to a remote procedure, you do not have to 387pass a pointer to the argument, but can pass the argument itself. 388This behavior is different from the old style of 389.Nm 390generated code. 391To maintain backward compatibility, 392this option is not the default. 393.It Fl n Ar netid 394Compile into server-side stubs for the transport 395specified by 396.Ar netid . 397There should be an entry for 398.Ar netid 399in the 400netconfig database. 401This option may be specified more than once, 402so as to compile a server that serves multiple transports. 403.It Fl o Ar outfile 404Specify the name of the output file. 405If none is specified, 406standard output is used 407.Fl ( c , 408.Fl h , 409.Fl l , 410.Fl m , 411.Fl n , 412.Fl s , 413.Fl \&Sc , 414.Fl \&Sm , 415.Fl \&Ss , 416and 417.Fl t 418modes only). 419.It Fl P 420Compile support for 421port monitors 422in the server side stubs. 423.Pp 424Note: 425Contrary to some systems, in 426.Dx 427this option is needed to generate 428servers that can be monitored. 429.Pp 430If the 431.Fl I 432option has been specified, 433.Fl P 434is turned off automatically. 435.It Fl s Ar nettype 436Compile into server-side stubs for all the 437transports belonging to the class 438.Ar nettype . 439The supported classes are 440.Em netpath , 441.Em visible , 442.Em circuit_n , 443.Em circuit_v , 444.Em datagram_n , 445.Em datagram_v , 446.Em tcp , 447and 448.Em udp 449(see 450.Xr rpc 3 451for the meanings associated with these classes). 452This option may be specified more than once. 453Note: 454the transports are chosen at run time and not at compile time. 455.It Fl \&Sc 456Generate sample client code that uses remote procedure calls. 457.It Fl \&Sm 458Generate a sample 459.Pa Makefile 460which can be used for compiling the application. 461.It Fl \&Ss 462Generate sample server code that uses remote procedure calls. 463.It Fl t 464Compile into 465.Tn RPC 466dispatch table. 467.It Fl T 468Generate the code to support 469.Tn RPC 470dispatch tables. 471.Pp 472The options 473.Fl c , 474.Fl h , 475.Fl l , 476.Fl m , 477.Fl s , 478.Fl \&Sc , 479.Fl \&Sm , 480.Fl \&Ss , 481and 482.Fl t 483are used exclusively to generate a particular type of file, 484while the options 485.Fl D 486and 487.Fl T 488are global and can be used with the other options. 489.It Fl Y Ar pathname 490Give the name of the directory where 491.Nm 492will start looking for the C-preprocessor. 493.El 494.Sh EXAMPLES 495The following example: 496.Dl example% rpcgen -T prot.x 497.Pp 498generates all the five files: 499.Pa prot.h , 500.Pa prot_clnt.c , 501.Pa prot_svc.c , 502.Pa prot_xdr.c 503and 504.Pa prot_tbl.i . 505.Pp 506The following example sends the C data-definitions (header) 507to the standard output. 508.Dl example% rpcgen -h prot.x 509.Pp 510To send the test version of the 511.Fl D Ns Ar TEST , 512server side stubs for 513all the transport belonging to the class 514.Ar datagram_n 515to standard output, use: 516.Dl example% rpcgen -s datagram_n -DTEST prot.x 517.Pp 518To create the server side stubs for the transport indicated 519by 520.Ar netid 521tcp, 522use: 523.Dl example% rpcgen -n tcp -o prot_svc.c prot.x 524.Sh SEE ALSO 525.Xr cc 1 , 526.Xr rpc 3 , 527.Xr rpc_svc_calls 3 , 528.Xr syslog 3 , 529.Xr xdr 3 , 530.Xr inetd 8 531.Rs 532.%T The rpcgen chapter in the NETP manual 533.Re 534