aboutsummaryrefslogtreecommitdiffstats
path: root/usr.bin/rpcgen/rpcgen.1
diff options
context:
space:
mode:
authorBill Paul <wpaul@FreeBSD.org>1995-12-13 03:21:09 +0000
committerBill Paul <wpaul@FreeBSD.org>1995-12-13 03:21:09 +0000
commitee4f614e7e8de002a02c0a83d1af810196e6514a (patch)
tree7b15f8667f850d441bc04980c58773734aeaad24 /usr.bin/rpcgen/rpcgen.1
downloadsrc-ee4f614e7e8de002a02c0a83d1af810196e6514a.tar.gz
src-ee4f614e7e8de002a02c0a83d1af810196e6514a.zip
Import a newer and more functional version of rpcgen.vendor/rpcgen
Obtained from: the Sun TI-RPC 2.3 source distribution
Notes
Notes: svn path=/cvs2svn/branches/SUNRPC/; revision=12795
Diffstat (limited to 'usr.bin/rpcgen/rpcgen.1')
-rw-r--r--usr.bin/rpcgen/rpcgen.1554
1 files changed, 554 insertions, 0 deletions
diff --git a/usr.bin/rpcgen/rpcgen.1 b/usr.bin/rpcgen/rpcgen.1
new file mode 100644
index 000000000000..cb81c98f180f
--- /dev/null
+++ b/usr.bin/rpcgen/rpcgen.1
@@ -0,0 +1,554 @@
+.\" @(#)rpcgen.1 1.35 93/06/02 SMI
+'\"macro stdmacro
+.\" Copyright 1985-1993 Sun Microsystems, Inc.
+.nr X
+.TH rpcgen 1 "28 Mar 1993"
+.SH NAME
+rpcgen \- an RPC protocol compiler
+.SH SYNOPSIS
+.BI rpcgen " infile"
+.LP
+.B rpcgen
+[
+.B \-a
+] [
+.B \-b
+] [
+.B \-C
+] [
+.BI \-D name
+[ =
+.I value
+] ]
+.if n .ti +5n
+[
+.BI \-i " size"
+]
+[
+.B \-I
+[
+.BI \-K " seconds"
+] ]
+[
+.B \-L
+] [
+.B \-M
+]
+.if n .ti +5n
+.if t .ti +5n
+[
+.B \-N
+]
+[
+.B \-T
+] [
+.BI \-Y " pathname"
+]
+.I infile
+.LP
+.B rpcgen
+[
+.B \-c
+|
+.B \-h
+|
+.B \-l
+|
+.B \-m
+|
+.B \-t
+|
+.B \-Sc
+|
+.B \-Ss
+|
+.B \-Sm
+]
+.if n .ti +5n
+[
+.BI \-o " outfile"
+] [
+.I infile
+]
+.LP
+.B rpcgen
+[
+.BI \-s " nettype"
+] [
+.BI \-o " outfile"
+] [
+.I infile
+]
+.LP
+.B rpcgen
+[
+.BI \-n " netid"
+] [
+.BI \-o " outfile"
+] [
+.I infile
+]
+.\" .SH AVAILABILITY
+.\" .LP
+.\" SUNWcsu
+.SH DESCRIPTION
+.IX "rpcgen" "" "\fLrpcgen\fP \(em RPC protocol compiler"
+.IX "RPC" "protocol compiler" "" "protocol compiler \(em \fLrpcgen\fP"
+.IX "RPC Language" "RPC protocol compiler" "" "RPC protocol compiler \(em \fLrpcgen\fP"
+.IX "compilers" "RPC protocol compiler" "" "RPC protocol compiler \(em \fLrpcgen\fP"
+.IX "programming tools" "RPC protocol compiler" "" "RPC protocol compiler \(em \fLrpcgen\fP"
+.LP
+\f3rpcgen\f1
+is a tool that generates C code to implement an RPC protocol.
+The input to
+\f3rpcgen\f1
+is a language similar to C known as
+RPC Language (Remote Procedure Call Language).
+.LP
+\f3rpcgen\f1
+is normally used as in the first synopsis where
+it takes an input file and generates three output files.
+If the
+\f2infile\f1
+is named
+\f3proto.x\f1,
+then
+\f3rpcgen\f1
+generates a header in
+\f3proto.h\f1,
+XDR routines in
+\f3proto_xdr.c\f1,
+server-side stubs in
+\f3proto_svc.c\f1,
+and client-side stubs in
+\f3proto_clnt.c\f1.
+With the
+\f3\-T\f1
+option,
+it also generates the RPC dispatch table in
+\f3proto_tbl.i\f1.
+.LP
+.B rpcgen
+can also generate sample client and server files
+that can be customized to suit a particular application. The
+\f3\-Sc\f1,
+\f3\-Ss\f1
+and
+\f3\-Sm\f1
+options generate sample client, server and makefile, respectively.
+The
+\f3\-a\f1
+option generates all files, including sample files. If the infile
+is \f3proto.x\f1, then the client side sample file is written to
+\f3proto_client.c\f1, the server side sample file to \f3proto_server.c\f1
+and the sample makefile to \f3makefile.proto\f1.
+.LP
+The server created can be started both by the port monitors
+(for example, \f3inetd\f1 or \f3listen\f1)
+or by itself.
+When it is started by a port monitor,
+it creates servers only for the transport for which
+the file descriptor \f30\fP was passed.
+The name of the transport must be specified
+by setting up the environment variable
+\f3PM_TRANSPORT\f1.
+When the server generated by
+\f3rpcgen\f1
+is executed,
+it creates server handles for all the transports
+specified in
+\f3NETPATH\f1
+environment variable,
+or if it is unset,
+it creates server handles for all the visible transports from
+\f3/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
+\f3RPC_SVC_FG\f1
+can be used to run the server process in foreground.
+.LP
+The second synopsis provides special features which allow
+for the creation of more sophisticated RPC servers.
+These features include support for user provided
+\f3#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.
+.LP
+The other three synopses shown above are used when
+one does not want to generate all the output files,
+but only a particular one.
+See the
+.SM EXAMPLES
+section below for examples of
+.B rpcgen
+usage.
+When
+\f3rpcgen\f1
+is executed with the
+\f3\-s\f1
+option,
+it creates servers for that particular class of transports.
+When
+executed with the
+\f3\-n\f1
+option,
+it creates a server for the transport specified by
+\f2netid\f1.
+If
+\f2infile\f1
+is not specified,
+\f3rpcgen\f1
+accepts the standard input.
+.LP
+The C preprocessor,
+\f3cc \-E\f1
+is run on the input file before it is actually interpreted by
+\f3rpcgen\f1.
+For each type of output file,
+\f3rpcgen\f1
+defines a special preprocessor symbol for use by the
+\f3rpcgen\f1
+programmer:
+.LP
+.PD 0
+.RS
+.TP 12
+\f3RPC_HDR\f1
+defined when compiling into headers
+.TP
+\f3RPC_XDR\f1
+defined when compiling into XDR routines
+.TP
+\f3RPC_SVC\f1
+defined when compiling into server-side stubs
+.TP
+\f3RPC_CLNT\f1
+defined when compiling into client-side stubs
+.TP
+\f3RPC_TBL\f1
+defined when compiling into RPC dispatch tables
+.RE
+.PD
+.LP
+Any line beginning with
+``\f3%\f1''
+is passed directly into the output file,
+uninterpreted by
+\f3rpcgen\f1.
+To specify the path name of the C preprocessor use \f3\-Y\f1 flag.
+.LP
+For every data type referred to in
+\f2infile\f1,
+\f3rpcgen\f1
+assumes that there exists a
+routine with the string
+\f3xdr_\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
+.SH OPTIONS
+.TP 15
+\f3\-a\f1
+Generate all files, including sample files.
+.TP
+\f3\-b\f1
+Backward compatibility mode.
+Generate transport specific RPC code for older versions
+of the operating system.
+.IP
+Note: in FreeBSD, this compatibility flag is turned on by
+default since FreeBSD supports only the older ONC RPC library.
+.TP
+\f3\-c\f1
+Compile into XDR routines.
+.TP
+\f3\-C\f1
+Generate header and stub files which can be used with
+.SM ANSI C
+compilers. Headers generated with this flag can also be
+used with C++ programs.
+.TP
+\f3\-D\f2name\f3[=\f2value\f3]\f1
+Define a symbol
+\f2name\f1.
+Equivalent to the
+\f3#define\f1
+directive in the source.
+If no
+\f2value\f1
+is given,
+\f2value\f1
+is defined as \f31\f1.
+This option may be specified more than once.
+.TP
+\f3\-h\f1
+Compile into
+\f3C\f1
+data-definitions (a header).
+\f3\-T\f1
+option can be used in conjunction to produce a
+header which supports RPC dispatch tables.
+.TP
+\f3\-i \f2size\f1
+Size at which to start generating inline code.
+This option is useful for optimization. The default size is 5.
+.IP
+Note: in order to provide backwards compatibility with the older
+.B rpcgen
+on the FreeBSD platform, the default is actually 0 (which means
+that inline code generation is disabled by default). You must specify
+a non-zero value explicitly to override this default.
+.TP
+\f3\-I\f1
+Compile support for
+.BR inetd (1M)
+in the server side stubs.
+Such servers can be self-started or can be started by \f3inetd\f1.
+When the server is self-started, it backgrounds itself by default.
+A special define symbol \f3RPC_SVC_FG\f1 can be used to run the
+server process in foreground, or the user may simply compile without
+the \f3\-I\f1 option.
+.br
+.ne 5
+.IP
+If there are no pending client requests, the
+\f3inetd\f1 servers exit after 120 seconds (default).
+The default can be changed with the
+.B \-K
+option.
+All the error messages for \f3inetd\f1 servers
+are always logged with
+.BR syslog (3).
+.\" .IP
+.\" Note:
+.\" this option is supported for backward compatibility only.
+.\" By default,
+.\" .B rpcgen
+.\" generates servers that can be invoked through portmonitors.
+.TP
+.BI \-K " seconds"
+By default, services created using \f3rpcgen\fP and invoked through
+port monitors wait \f3120\fP seconds
+after servicing a request before exiting.
+That interval can be changed using the \f3\-K\fP flag.
+To create a server that exits immediately upon servicing a request,
+use
+.BR "\-K\ 0".
+To create a server that never exits, the appropriate argument is
+\f3\-K \-1\fP.
+.IP
+When monitoring for a server,
+some portmonitors, like
+.BR listen (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, \f3rpcgen\fP should be used with \f3\-K 0\fP.
+.TP
+\f3\-l\f1
+Compile into client-side stubs.
+.TP
+.B \-L
+When the servers are started in foreground, use
+.BR syslog (3)
+to log the server errors instead of printing them on the standard
+error.
+.TP
+\f3\-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
+\f3\-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. However, the
+.BR rpc_svc_calls (3N)
+functions are not yet MT-safe, which means that rpcgen generated server-side
+code will not be MT-safe.
+.TP
+.B \-N
+This option 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 can pass the argument itself.
+This behavior is different from the old style of
+.B rpcgen
+generated code.
+To maintain backward compatibility,
+this option is not the default.
+.TP
+\f3\-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
+\f3\-o \f2outfile\f1
+Specify the name of the output file.
+If none is specified,
+standard output is used
+(\f3\-c\f1,
+\f3\-h\f1,
+\f3\-l\f1,
+\f3\-m\f1,
+\f3\-n\f1,
+\f3\-s\f1,
+\f3\-Sc\f1,
+\f3\-Sm\f1,
+\f3\-Ss\f1,
+and
+\f3\-t\f1
+modes only).
+.TP
+\f3\-s \f2nettype\f1
+Compile into server-side stubs for all the
+transports belonging to the class
+\f2nettype\f1.
+The supported classes are
+\f3netpath\f1,
+\f3visible\f1,
+\f3circuit_n\f1,
+\f3circuit_v\f1,
+\f3datagram_n\f1,
+\f3datagram_v\f1,
+\f3tcp\f1,
+and
+\f3udp\f1
+(see
+.BR rpc (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
+\f3\-Sc\f1
+Generate sample client code that uses remote procedure calls.
+.br
+.ne 5
+.TP
+\f3\-Sm\f1
+Generate a sample Makefile which can be used for compiling the
+application.
+.TP
+\f3\-Ss\f1
+Generate sample server code that uses remote procedure calls.
+.TP
+\f3\-t\f1
+Compile into RPC dispatch table.
+.TP
+\f3\-T\f1
+Generate the code to support RPC dispatch tables.
+.IP
+The options
+\f3\-c\f1,
+\f3\-h\f1,
+\f3\-l\f1,
+\f3\-m\f1,
+\f3\-s\f1,
+\f3\-Sc\f1,
+\f3\-Sm\f1,
+\f3\-Ss\f1,
+and
+\f3\-t\f1
+are used exclusively to generate a particular type of file,
+while the options
+\f3\-D\f1
+and
+\f3\-T\f1
+are global and can be used with the other options.
+.TP
+\f3\-Y\f2 pathname\f1
+Give the name of the directory where
+.B rpcgen
+will start looking for the C-preprocessor.
+.br
+.ne 5
+.SH EXAMPLES
+The following example:
+.LP
+.RS
+.B example% rpcgen \-T prot.x
+.RE
+.LP
+generates all the five files:
+.BR prot.h ,
+.BR prot_clnt.c ,
+.BR prot_svc.c ,
+.B prot_xdr.c
+and
+.BR prot_tbl.i .
+.LP
+The following example sends the C data-definitions (header)
+to the standard output.
+.LP
+.RS
+.B example% rpcgen \-h prot.x
+.RE
+.LP
+To send the test version of the
+.BR -DTEST ,
+server side stubs for
+all the transport belonging to the class
+.B datagram_n
+to standard output, use:
+.LP
+.RS
+.B example% rpcgen \-s datagram_n \-DTEST prot.x
+.RE
+.LP
+To create the server side stubs for the transport indicated
+by
+\f2netid\f1
+\f3tcp\f1,
+use:
+.LP
+.RS
+.B example% rpcgen \-n tcp \-o prot_svc.c prot.x
+.RE
+.SH "SEE ALSO"
+.BR cc (1B),
+.BR inetd (1M),
+.BR listen (1M),
+.BR syslog (3),
+.BR rpc (3N),
+.\" .BR rpc_svc_calls (3N)
+.LP
+The
+.B rpcgen
+chapter in the
+.TZ NETP
+manual.