Adding upstream version 1:2.6.4.upstream/1%2.6.4upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

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).