1 files changed, 541 insertions, 143 deletions
diff --git a/usr.bin/rpcgen/rpcgen.1 b/usr.bin/rpcgen/rpcgen.1
index 5fd9274..cb81c98 100644
--- a/usr.bin/rpcgen/rpcgen.1
+++ b/usr.bin/rpcgen/rpcgen.1
@@ -1,156 +1,554 @@
-.\"	from: @(#)rpcgen.1	2.2 88/08/02 4.0 RPCSRC
-.\"	$Id: rpcgen.1,v 1.1 1993/09/13 23:20:21 jtc Exp $
-.\"
-.Dd January 18, 1988
-.Dt RPCGEN 1
-.Os
-.Sh NAME
-.Nm rpcgen
-.Nd RPC protocol compiler
-.Sh SYNOPSIS
-.Nm rpcgen
-.Ar infile
-.Nm rpcgen
-.Fl c Li |
-.Fl h Li |
-.Fl l Li |
-.Fl m
-.Op Fl o Ar outfile
-.Op Ar infile
-.Nm rpcgen
-.Fl s Ar transport
-.Op Fl o Ar outfile
-.Op Ar infile
-.Sh DESCRIPTION
-.Nm rpcgen
-is a tool that generates C code to implement an
-.Tn RPC
-protocol.  The input to
-.Nm rpcgen
+.\" @(#)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
-.Tn RPC
-Language (Remote Procedure Call Language).  Information about the
-syntax of
-.Tn RPC
-Language is available in the
-.Rs
-.%T "rpcgen Programming Guide"
-.Re
-.Pp
-.Nm rpcgen
-is normally used as in the first synopsis where it takes an input file
-and generates four output files. If the
-.Ar infile
+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
-.Pa proto.x ,
+\f3proto.x\f1,
 then
-.Nm rpcgen
-will generate a header file in
-.Pa proto.h ,
-.Tn XDR
-routines in
-.Pa proto_xdr.c ,
+\f3rpcgen\f1
+generates a header in
+\f3proto.h\f1,
+XDR routines in
+\f3proto_xdr.c\f1,
 server-side stubs in
-.Pa proto_svc.c ,
+\f3proto_svc.c\f1,
 and client-side stubs in
-.Pa proto_clnt.c .
-.Pp
-The other synopses shown above are used when one does not want to
-generate all the output files, but only a particular one. 
-.\" Their usage is described in the
-.\" .Sx USAGE
-.\" section below.
-.Pp
-The C-preprocessor,
-.Xr cpp 1 ,
-is run on all input files before they are actually
-interpreted by
-.Nm rpcgen ,
-so all the
-.Xr cpp
-directives are legal within an
-.Nm rpcgen
-input file.  For each type of output file,
-.Nm rpcgen
-defines a special
-.Xr cpp
-symbol for use by the
-.Nm rpcgen
+\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:
-.Pp
-.Bl -tag -width RPC_CLNT -compact
-.It Dv RPC_HDR
-defined when compiling into header files
-.It Dv RPC_XDR
-defined when compiling into
-.Tn XDR
-routines
-.It Dv RPC_SVC
+.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
-.It Dv RPC_CLNT
+.TP
+\f3RPC_CLNT\f1
 defined when compiling into client-side stubs
-.El
-.Pp
-In addition,
-.Nm rpcgen
-does a little preprocessing of its own.  Any line beginning with
-.Sq %
-is passed directly into the output file, uninterpreted by
-.Nm rpcgen .
-.Pp
-You can customize some of your
-.Tn XDR
-routines by leaving those data types undefined.  For every data type
-that is undefined,
-.Nm rpcgen
-will assume that there exists a routine with the name
-.Tn xdr_
-prepended to the name of the undefined type.
-.Sh OPTIONS
-.Bl -tag -width indent
-.It Fl c
+.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
-.Tn XDR
-routines.
-.It Fl h
-Compile into C data-definitions (a header file).
-.It Fl l
+\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.
-.It Fl m
-Compile into server-side stubs, but do not generate a 
-.Fn main
-routine.  This option is useful for doing callback-routines and for
-people who need to write their own 
-.Fn main
-routine to do initialization.
-.It Fl o Ar outfile
-Specify the name of the output file.  If none is specified, standard
-output is used (
-.Fl c , 
-.Fl h , 
-.Fl l 
+.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
-.Fl s
+\f3\-t\f1
 modes only).
-.It Fl s Ar transport
-Compile into server-side stubs, using the the given transport.  The
-supported transports are
-.Tn udp
+.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
-.Tn tcp .
-This option may be invoked more than once so as to compile a server
-that serves multiple transports.
-.El
-.Sh SEE ALSO
-.Xr cpp 1
-.Rs
-.%T "rpcgen Programming Guide"
-.Re
-.Sh BUGS
-Nesting is not supported.  As a work-around, structures can be
-declared at top-level, and their name used inside other structures in
-order to achieve the same effect.
-.Pp
-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.
+.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.