| .\" @(#)rpcgen.new.1 1.1 90/11/09 TIRPC 1.0; from 40.10 of 10/10/89 |
| .\" Copyright (c) 1988,1990 Sun Microsystems, Inc. - All Rights Reserved. |
| .nr X |
| .if \nX=0 .ds x} rpcgen 1 "" "\&" |
| .if \nX=1 .ds x} rpcgen 1 "" |
| .if \nX=2 .ds x} rpcgen 1 "" "\&" |
| .if \nX=3 .ds x} rpcgen "" "" "\&" |
| .TH \*(x} |
| .SH NAME |
| \f4rpcgen\f1 \- an RPC protocol compiler |
| .SH SYNOPSIS |
| .ft 4 |
| .nf |
| rpcgen \f2infile\f4 |
| .fi |
| .ft 1 |
| .br |
| .ft 4 |
| .nf |
| rpcgen [\-D\f2name\f4[=\f2value\f4]] [\-T] [\-K \f2secs\fP] \f2infile\f4 |
| .fi |
| .ft 1 |
| .br |
| .ft 4 |
| .nf |
| rpcgen \-c|\-h|\-l|\-m|\-t [\-o \f2outfile\f4 ] \f2infile\f4 |
| .fi |
| .ft 1 |
| .br |
| .ft 4 |
| .nf |
| rpcgen \-s \f2nettype\f4 [\-o \f2outfile\f4] \f2infile\f4 |
| .fi |
| .ft 1 |
| .br |
| .ft 4 |
| .nf |
| rpcgen \-n \f2netid\f4 [\-o \f2outfile\f4] \f2infile\f4 |
| .ft 1 |
| .SH DESCRIPTION |
| .P |
| \f4rpcgen\f1 |
| is a tool that generates C code to implement an RPC protocol. |
| The input to |
| \f4rpcgen\f1 |
| is a language similar to C known as |
| RPC Language (Remote Procedure Call Language). |
| .P |
| \f4rpcgen\f1 |
| is normally used as in the first synopsis where |
| it takes an input file and generates up to four output files. |
| If the |
| \f2infile\f1 |
| is named |
| \f4proto.x\f1, |
| then |
| \f4rpcgen\f1 |
| will generate a header file in |
| \f4proto.h\f1, |
| XDR routines in |
| \f4proto_xdr.c\f1, |
| server-side stubs in |
| \f4proto_svc.c\f1, |
| and client-side stubs in |
| \f4proto_clnt.c\f1. |
| With the |
| \f4\-T\f1 |
| option, |
| it will also generate the RPC dispatch table in |
| \f4proto_tbl.i\f1. |
| With the |
| \f4\-Sc\f1 |
| option, |
| it will also generate sample code which would illustrate how to use the |
| remote procedures on the client side. This code would be created in |
| \f4proto_client.c\f1. |
| With the |
| \f4\-Ss\f1 |
| option, |
| it will also generate a sample server code which would illustrate how to write |
| the remote procedures. This code would be created in |
| \f4proto_server.c\f1. |
| .P |
| The server created can be started both by the port monitors |
| (for example, \f4inetd\f1 or \f4listen\f1) |
| or by itself. |
| When it is started by a port monitor, |
| it creates servers only for the transport for which |
| the file descriptor \f40\fP was passed. |
| The name of the transport must be specified |
| by setting up the environmental variable |
| \f4PM_TRANSPORT\f1. |
| When the server generated by |
| \f4rpcgen\f1 |
| is executed, |
| it creates server handles for all the transports |
| specified in |
| \f4NETPATH\f1 |
| environment variable, |
| or if it is unset, |
| it creates server handles for all the visible transports from |
| \f4/etc/netconfig\f1 |
| file. |
| Note: |
| the transports are chosen at run time and not at compile time. |
| When the server is self-started, |
| it backgrounds itself by default. |
| A special define symbol |
| \f4RPC_SVC_FG\f1 |
| can be used to run the server process in foreground. |
| .P |
| The second synopsis provides special features which allow |
| for the creation of more sophisticated RPC servers. |
| These features include support for user provided |
| \f4#defines\f1 |
| and RPC dispatch tables. |
| The entries in the RPC dispatch table contain: |
| .RS |
| .PD 0 |
| .TP 3 |
| \(bu |
| pointers to the service routine corresponding to that procedure, |
| .TP |
| \(bu |
| a pointer to the input and output arguments |
| .TP |
| \(bu |
| the size of these routines |
| .PD |
| .RE |
| A server can use the dispatch table to check authorization |
| and then to execute the service routine; |
| a client library may use it to deal with the details of storage |
| management and XDR data conversion. |
| .P |
| The other three synopses shown above are used when |
| one does not want to generate all the output files, |
| but only a particular one. |
| Some examples of their usage is described in the |
| EXAMPLE |
| section below. |
| When |
| \f4rpcgen\f1 |
| is executed with the |
| \f4\-s\f1 |
| option, |
| it creates servers for that particular class of transports. |
| When |
| executed with the |
| \f4\-n\f1 |
| option, |
| it creates a server for the transport specified by |
| \f2netid\f1. |
| If |
| \f2infile\f1 |
| is not specified, |
| \f4rpcgen\f1 |
| accepts the standard input. |
| .P |
| The C preprocessor, |
| \f4cc \-E\f1 |
| [see \f4cc\fP(1)], |
| is run on the input file before it is actually interpreted by |
| \f4rpcgen\f1. |
| For each type of output file, |
| \f4rpcgen\f1 |
| defines a special preprocessor symbol for use by the |
| \f4rpcgen\f1 |
| programmer: |
| .P |
| .PD 0 |
| .TP 12 |
| \f4RPC_HDR\f1 |
| defined when compiling into header files |
| .TP |
| \f4RPC_XDR\f1 |
| defined when compiling into XDR routines |
| .TP |
| \f4RPC_SVC\f1 |
| defined when compiling into server-side stubs |
| .TP |
| \f4RPC_CLNT\f1 |
| defined when compiling into client-side stubs |
| .TP |
| \f4RPC_TBL\f1 |
| defined when compiling into RPC dispatch tables |
| .PD |
| .P |
| Any line beginning with |
| `\f4%\f1' |
| is passed directly into the output file, |
| uninterpreted by |
| \f4rpcgen\f1. |
| .P |
| For every data type referred to in |
| \f2infile\f1, |
| \f4rpcgen\f1 |
| assumes that there exists a |
| routine with the string |
| \f4xdr_\f1 |
| prepended to the name of the data type. |
| If this routine does not exist in the RPC/XDR |
| library, it must be provided. |
| Providing an undefined data type |
| allows customization of XDR routines. |
| .br |
| .ne 10 |
| .P |
| The following options are available: |
| .TP |
| \f4\-a\f1 |
| Generate all the files including sample code for client and server side. |
| .TP |
| \f4\-b\f1 |
| This generates code for the SunOS4.1 style of rpc. It is only |
| for backward compatibilty. By default rpcgen generates code for |
| Transport Independent RPC that is in Svr4 systems. |
| .TP |
| \f4\-c\f1 |
| Compile into XDR routines. |
| .TP |
| \f4\-C\f1 |
| Generate code in ANSI C. This option also generates code that could be |
| compiled with the C++ compiler. |
| .TP |
| \f4\-D\f2name\f4[=\f2value\f4]\f1 |
| Define a symbol |
| \f2name\f1. |
| Equivalent to the |
| \f4#define\f1 |
| directive in the source. |
| If no |
| \f2value\f1 |
| is given, |
| \f2value\f1 |
| is defined as \f41\f1. |
| This option may be specified more than once. |
| .TP |
| \f4\-h\f1 |
| Compile into |
| \f4C\f1 |
| data-definitions (a header file). |
| \f4\-T\f1 |
| option can be used in conjunction to produce a |
| header file which supports RPC dispatch tables. |
| .TP |
| \f4-K\f2 secs\f1 |
| By default, services created using \f4rpcgen\fP wait \f4120\fP seconds |
| after servicing a request before exiting. |
| That interval can be changed using the \f4-K\fP flag. |
| To create a server that exits immediately upon servicing a request, |
| \f4-K\ 0\fP can be used. |
| To create a server that never exits, the appropriate argument is |
| \f4-K\ -1\fP. |
| .IP |
| When monitoring for a server, |
| some portmonitors, like |
| \f4listen\fP(1M), |
| .I always |
| spawn a new process in response to a service request. |
| If it is known that a server will be used with such a monitor, the |
| server should exit immediately on completion. |
| For such servers, \f4rpcgen\fP should be used with \f4-K\ -1\fP. |
| .TP |
| \f4\-l\f1 |
| Compile into client-side stubs. |
| .TP |
| \f4\-m\f1 |
| Compile into server-side stubs, |
| but do not generate a \(lqmain\(rq routine. |
| This option is useful for doing callback-routines |
| and for users who need to write their own |
| \(lqmain\(rq routine to do initialization. |
| .TP |
| \f4\-n \f2netid\f1 |
| Compile into server-side stubs for the transport |
| specified by |
| \f2netid\f1. |
| There should be an entry for |
| \f2netid\f1 |
| in the |
| netconfig database. |
| This option may be specified more than once, |
| so as to compile a server that serves multiple transports. |
| .TP |
| \f4\-N\f1 |
| Use the newstyle of rpcgen. This allows procedures to have multiple arguments. |
| It also uses the style of parameter passing that closely resembles C. So, when |
| passing an argument to a remote procedure you do not have to pass a pointer to |
| the argument but the argument itself. This behaviour is different from the oldstyle |
| of rpcgen generated code. The newstyle is not the default case because of |
| backward compatibility. |
| .TP |
| \f4\-o \f2outfile\f1 |
| Specify the name of the output file. |
| If none is specified, |
| standard output is used |
| (\f4\-c\f1, |
| \f4\-h\f1, |
| \f4\-l\f1, |
| \f4\-m\f1, |
| \f4\-n\f1, |
| \f4\-s\f1, |
| \f4\-s\Sc, |
| \f4\-s\Ss |
| and |
| \f4\-t\f1 |
| modes only). |
| .TP |
| \f4\-s \f2nettype\f1 |
| Compile into server-side stubs for all the |
| transports belonging to the class |
| \f2nettype\f1. |
| The supported classes are |
| \f4netpath\f1, |
| \f4visible\f1, |
| \f4circuit_n\f1, |
| \f4circuit_v\f1, |
| \f4datagram_n\f1, |
| \f4datagram_v\f1, |
| \f4tcp\f1, |
| and |
| \f4udp\f1 |
| [see \f4rpc\fP(3N) |
| for the meanings associated with these classes]. |
| This option may be specified more than once. |
| Note: |
| the transports are chosen at run time and not at compile time. |
| .TP |
| \f4\-Sc\f1 |
| Generate sample code to show the use of remote procedure and how to bind |
| to the server before calling the client side stubs generated by rpcgen. |
| .TP |
| \f4\-Ss\f1 |
| Generate skeleton code for the remote procedures on the server side. You would need |
| to fill in the actual code for the remote procedures. |
| .TP |
| \f4\-t\f1 |
| Compile into RPC dispatch table. |
| .TP |
| \f4\-T\f1 |
| Generate the code to support RPC dispatch tables. |
| .P |
| The options |
| \f4\-c\f1, |
| \f4\-h\f1, |
| \f4\-l\f1, |
| \f4\-m\f1, |
| \f4\-s\f1 |
| and |
| \f4\-t\f1 |
| are used exclusively to generate a particular type of file, |
| while the options |
| \f4\-D\f1 |
| and |
| \f4\-T\f1 |
| are global and can be used with the other options. |
| .br |
| .ne 5 |
| .SH NOTES |
| The RPC Language does not support nesting of structures. |
| As a work-around, |
| structures can be declared at the top-level, |
| and their name used inside other structures in |
| order to achieve the same effect. |
| .P |
| Name clashes can occur when using program definitions, |
| since the apparent scoping does not really apply. |
| Most of these can be avoided by giving |
| unique names for programs, |
| versions, |
| procedures and types. |
| .P |
| The server code generated with |
| \f4\-n\f1 |
| option refers to the transport indicated by |
| \f2netid\f1 |
| and hence is very site specific. |
| .SH EXAMPLE |
| The following example: |
| .IP |
| .ft 4 |
| $ rpcgen \-T prot.x |
| .ft 1 |
| .P |
| generates the five files: |
| \f4prot.h\f1, |
| \f4prot_clnt.c\f1, |
| \f4prot_svc.c\f1, |
| \f4prot_xdr.c\f1 |
| and |
| \f4prot_tbl.i\f1. |
| .P |
| The following example sends the C data-definitions (header file) |
| to the standard output. |
| .IP |
| .ft 4 |
| $ rpcgen \-h prot.x |
| .ft 1 |
| .P |
| To send the test version of the |
| \f4-DTEST\f1, |
| server side stubs for |
| all the transport belonging to the class |
| \f4datagram_n\f1 |
| to standard output, use: |
| .IP |
| .ft 4 |
| $ rpcgen \-s datagram_n \-DTEST prot.x |
| .ft 1 |
| .P |
| To create the server side stubs for the transport indicated |
| by |
| \f2netid\f1 |
| \f4tcp\f1, |
| use: |
| .IP |
| .ft 4 |
| $ rpcgen \-n tcp \-o prot_svc.c prot.x |
| .ft 1 |
| .SH "SEE ALSO" |
| \f4cc\fP(1). |