diff options
Diffstat (limited to 'tools/rpcgen/rpcgen.1')
-rw-r--r-- | tools/rpcgen/rpcgen.1 | 442 |
1 files changed, 442 insertions, 0 deletions
diff --git a/tools/rpcgen/rpcgen.1 b/tools/rpcgen/rpcgen.1 new file mode 100644 index 0000000..9db1b4a --- /dev/null +++ b/tools/rpcgen/rpcgen.1 @@ -0,0 +1,442 @@ +.\" @(#)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|\-M|\-t [\-o \f2outfile\f4 ] \f2infile\f4 +.fi +.ft 1 +.br +.ft 4 +.nf +rpcgen [\-I] \-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. +.P +When built for a port monitor (\f4rpcgen\f1 \f4\-I\f1), and that 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 +for backward compatibility. This is the default. +.TP +\f4\-5\f1 +This generates code for the SysVr4 style of rpc. It is used by the +Transport Independent RPC that is in Svr4 systems. +By default rpcgen generates code for SunOS4.1 stype of rpc. +.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. This is the default. +.TP +\f4\-k\f1 +Generate code in K&R C. The default is ANSI C. +.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\-I\f1 +Generate a service that can be started from inetd. The default is +to generate a static service that handles transports selected with \f4\-s\f1. +Using \f4\-I\f1 allows starting a service by either method. +.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\-M\f1 +Generate multithread-safe stubs for passing arguments +and results between rpcgen-generated code and user written code. +This option is useful for users who want to use threads in their code. +.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\-Sc\f1, +\f4\-Sm\f1, +\f4\-Ss\f1, +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\-Sm\f1 +Generate a sample Makefile which can be used for compiling the application. +.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). |