diff options
Diffstat (limited to 'developer_cmds/rpcgen/rpcgen.1')
| -rw-r--r-- | developer_cmds/rpcgen/rpcgen.1 | 452 |
1 files changed, 452 insertions, 0 deletions
diff --git a/developer_cmds/rpcgen/rpcgen.1 b/developer_cmds/rpcgen/rpcgen.1 new file mode 100644 index 0000000..a5764a6 --- /dev/null +++ b/developer_cmds/rpcgen/rpcgen.1 @@ -0,0 +1,452 @@ +.\" $NetBSD: rpcgen.1,v 1.8 1998/04/28 07:19:29 fair Exp $ +.\" from: @(#)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. +.Dd June 11, 1995 +.Dt RPCGEN 1 +.Sh NAME +.Nm rpcgen +.Nd Remote Procedure Call (RPC) protocol compiler +.Sh SYNOPSIS +.Nm +.Ar infile +.Nm +.Op Fl D Op Ar name=value +.Op Fl A +.Op Fl M +.Op Fl T +.Op Fl K Ar secs +.Ar infile +.Nm +.Op Fl L +.Fl c Li | +.Fl h Li | +.Fl l Li | +.Fl m Li | +.Fl t Li | +.Fl S\&c Li | +.Fl S\&s Li | +.Op Fl o Ar outfile +.Op Ar infile +.Nm +.Fl c Li | +.Ar nettype +.Op Fl o Ar outfile +.Op Ar infile +.Nm +.Fl s Li | +.Ar netid +.Op Fl o Ar outfile +.Op Ar infile +.Sh DESCRIPTION +.Nm +is a tool that generates C code to implement an +.Tn RPC +protocol. +The input to +.Nm +is a language similar to C known as +.Tn RPC +Language (Remote Procedure Call Language). +.Nm +is normally used as in the first synopsis where +it takes an input file and generates up to four output files. +If the +.Ar infile +is named +.Pa proto.x , +then +.Nm +will generate a header file in +.Pa proto.h , +.Tn XDR +routines in +.Pa proto_xdr.c , +server-side stubs in +.Pa proto_svc.c , +and client-side stubs in +.Pa proto_clnt.c . +With the +.Fl T +option, +it will also generate the +.Tn RPC +dispatch table in +.Pa proto_tbl.i . +With the +.Fl S\&c +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 +.Pa proto_client.c . +With the +.Fl S\&s +option, +it will also generate a sample server code which would illustrate how to write +the remote procedures. This code would be created in +.Pa proto_server.c . +.Pp +The server created can be started both by the port monitors +(for example, +.Em inetd +or +.Em listen ) +or by itself. +When it is started by a port monitor, +it creates servers only for the transport for which +the file descriptor 0 was passed. +The name of the transport must be specified +by setting up the environmental variable +.Ev PM_TRANSPORT . +When the server generated by +.Nm +is executed, +it creates server handles for all the transports +specified in +.Ev NETPATH +environment variable, +or if it is unset, +it creates server handles for all the visible transports from +.Pa /etc/netconfig +file. +.Pp +.Em 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 +.Dv RPC_SVC_FG +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 +.Tn RPC +servers. +These features include support for user provided +.Li #defines +and +.Tn RPC +dispatch tables. +The entries in the +.Tn RPC +dispatch table contain: +.Pp +.Bl -inset -offset indent -compact +.It + +pointers to the service routine corresponding to that procedure, +.It + +a pointer to the input and output arguments, +.It + +the size of these routines +.El +.Pp +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 +.Tn XDR +data conversion. +.Pp +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 +.Nm +is executed with the +.Fl s +option, +it creates servers for that particular class of transports. +When +executed with the +.Fl n +option, +it creates a server for the transport specified by +.Em netid . +If +.Ar infile +is not specified, +.Nm +accepts the standard input. +.Pp +The C preprocessor, +.Xr cpp 1 +is run on the input file before it is actually interpreted by +.Nm +For each type of output file, +.Nm +defines a special preprocessor symbol for use by the +.Nm +programmer: +.Bl -tag -width RPC_CLNT +.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 +defined when compiling into server-side stubs +.It Dv RPC_CLNT +defined when compiling into client-side stubs +.It Dv RPC_TBL +defined when compiling into +.Tn RPC +dispatch tables +.El +.Pp +Any line beginning with +.Sq % +is passed directly into the output file, +uninterpreted by +.Nm . +.Pp +For every data type referred to in +.Ar infile +.Nm +assumes that there exists a +routine with the string +.Dq xdr_ +prepended to the name of the data type. +If this routine does not exist in the +.Tn RPC/XDR +library, it must be provided. +Providing an undefined data type +allows customization of +.Tn XDR +routines. +.Sh OPTIONS +.Bl -tag -width indent +.It Fl a +Generate all the files including sample code for client and server side. +.It Fl b +This generates code for the +.Tn "SunOS 4.1" +style of +.Tn RPC . +This is the default. +.It Fl C +Generate code in +.Tn ANSI +C. +This option also generates code that could be compiled with the +C++ compiler. +.It Fl c +Compile into +.Tn XDR +routines. +.It Fl D Ar name Ns Op Ar =value +Define a symbol +.Dv name . +Equivalent to the +.Dv #define +directive in the source. +If no +.Dv value +is given, +.Dv value +is defined as 1. +This option may be specified more than once. +.It Fl h +Compile into C data-definitions (a header file). +The +.Fl T +option can be used in conjunction to produce a +header file which supports +.Tn RPC +dispatch tables. +.It Fl K Ar secs +By default, services created using +.Nm +wait 120 seconds +after servicing a request before exiting. +That interval can be changed using the +.Fl K +flag. +To create a server that exits immediately upon servicing a request, +.Dq Fl K No 0 +can be used. +To create a server that never exits, the appropriate argument is +.Dq Fl K No -1 . +.Pp +When monitoring for a server, +some port monitors, like the +.At V.4 +utility +.Xr listen 1 , +.Em 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, +.Nm +should be used with +.Dq Fl K No -1 . +.It Fl L +Server errors will be sent to syslog instead of stderr. +.It Fl l +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 users who need to write their own +.Fn main +routine to do initialization. +.It Fl N +Use the newstyle of +.Nm . +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 +.Nm +generated code. +The newstyle is not the default case because of backward compatibility. +.It Fl n Ar netid +Compile into server-side stubs for the transport +specified by +.Ar netid. +There should be an entry for +.Ar netid +in the +netconfig database. +This option may be specified more than once, +so as to compile a server that serves multiple transports. +.It Fl o Ar outfile +Specify the name of the output file. +If none is specified, +standard output is used +.Po +.Fl c Fl h Fl l +.Fl m Fl n Fl s +modes only +.Pc +.It Fl S\&c +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 +.Nm . +.It Fl S\&s +Generate skeleton code for the remote procedures on the server side. You would need +to fill in the actual code for the remote procedures. +.It Fl s Ar nettype +Compile into server-side stubs for all the +transports belonging to the class +.Ar nettype . +The supported classes are +.Em netpath, +.Em visible, +.Em circuit_n, +.Em circuit_v, +.Em datagram_n, +.Em datagram_v, +.Em tcp, +and +.Em udp +[see +.Xr rpc 3 +for the meanings associated with these classes. +.Em Note: +.Bx +currently supports only the +.Em tcp +and +.Em udp +classes]. +This option may be specified more than once. +.Em Note: +the transports are chosen at run time and not at compile time. +.It Fl T +Generate the code to support +.Tn RPC +dispatch tables. +.It Fl t +Compile into +.Tn RPC +dispatch table. +.El +.Pp +The options +.Fl c , +.Fl h , +.Fl l , +.Fl m , +.Fl s , +and +.Fl t +are used exclusively to generate a particular type of file, +while the options +.Fl D +and +.Fl T +are global and can be used with the other options. +.Sh NOTES +The +.Tn 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. +.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. +.Pp +The server code generated with +.Fl n +option refers to the transport indicated by +.Em netid +and hence is very site specific. +.Sh EXAMPLE +.Pp +The command +.Pp +.Bd -literal -offset indent +$ rpcgen -T prot.x +.Ed +.Pp +generates the five files: +.Pa prot.h , +.Pa prot_clnt.c , +.Pa prot_svc.c , +.Pa prot_xdr.c +and +.Pa prot_tbl.i . +.Pp +The following example sends the C data-definitions (header file) +to standard output. +.Pp +.Bd -literal -offset indent +$ rpcgen -h prot.x +.Ed +.Pp +To send the test version of the +.Dv -DTEST , +server side stubs for +all the transport belonging to the class +.Em datagram_n +to standard output, use: +.Pp +.Bd -literal -offset indent +$ rpcgen -s datagram_n -DTEST prot.x +.Ed +.Pp +To create the server side stubs for the transport indicated by +.Em netid +.Em tcp , +use: +.Pp +.Bd -literal -offset indent +$ rpcgen -n tcp -o prot_svc.c prot.x +.Ed +.Sh SEE ALSO +.Xr cpp 1 |