diff options
Diffstat (limited to 'package/libtirpc/src/rpcgen/rpcgen.1')
| -rw-r--r-- | package/libtirpc/src/rpcgen/rpcgen.1 | 521 |
1 files changed, 521 insertions, 0 deletions
diff --git a/package/libtirpc/src/rpcgen/rpcgen.1 b/package/libtirpc/src/rpcgen/rpcgen.1 new file mode 100644 index 000000000..89df7ed02 --- /dev/null +++ b/package/libtirpc/src/rpcgen/rpcgen.1 @@ -0,0 +1,521 @@ +.\" @(#)rpcgen.1 1.35 93/06/02 SMI +.\" $FreeBSD: src/usr.bin/rpcgen/rpcgen.1,v 1.12.2.4 2002/06/21 15:28:50 charnier Exp $ +.\" Copyright 1985-1993 Sun Microsystems, Inc. +.Dd March 28, 1993 +.Dt RPCGEN 1 +.Os +.Sh NAME +.Nm rpcgen +.Nd an RPC protocol compiler +.Sh SYNOPSIS +.Nm +.Ar infile +.Nm +.Op Fl a +.Op Fl b +.Op Fl C +.Oo +.Fl D Ns Ar name Ns Op Ar =value +.Oc +.Op Fl i Ar size +.Op Fl I Op Fl K Ar seconds +.Op Fl L +.Op Fl M +.Op Fl N +.Op Fl T +.Op Fl Y Ar pathname +.Ar infile +.Nm +.Oo +.Fl c | +.Fl h | +.Fl l | +.Fl m | +.Fl t | +.Fl \&Sc | +.Fl \&Ss | +.Fl \&Sm +.Oc +.Op Fl o Ar outfile +.Op Ar infile +.Nm +.Op Fl s Ar nettype +.Op Fl o Ar outfile +.Op Ar infile +.Nm +.Op Fl n Ar netid +.Op Fl o Ar outfile +.Op Ar infile +.\" .SH AVAILABILITY +.\" .LP +.\" SUNWcsu +.Sh DESCRIPTION +The +.Nm +utility 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). +.Pp +The +.Nm +utility is normally used as in the first synopsis where +it takes an input file and generates three output files. +If the +.Ar infile +is named +.Pa proto.x , +then +.Nm +generates a header in +.Pa proto.h , +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 also generates the +.Tn RPC +dispatch table in +.Pa proto_tbl.i . +.Pp +The +.Nm +utility can also generate sample client and server files +that can be customized to suit a particular application. +The +.Fl \&Sc , +.Fl \&Ss +and +.Fl \&Sm +options generate sample client, server and makefile, respectively. +The +.Fl a +option generates all files, including sample files. +If the +.Ar infile +is +.Pa proto.x , +then the client side sample file is written to +.Pa proto_client.c , +the server side sample file to +.Pa proto_server.c +and the sample makefile to +.Pa makefile.proto . +.Pp +The server created can be started both by the port monitors +(for example, +.Xr inetd 8 ) +or by itself. +When it is started by a port monitor, +it creates servers only for the transport for which +the file descriptor +.Em 0 +was passed. +The name of the transport must be specified +by setting up the environment 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. +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 +.Em RPC_SVC_FG +can be used to run the server process in foreground. +.Pp +The second synopsis provides special features which allow +for the creation of more sophisticated +.Tn RPC +servers. +These features include support for user provided +.Em #defines +and +.Tn RPC +dispatch tables. +The entries in the +.Tn RPC +dispatch table contain: +.Bl -bullet -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 +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. +.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. +See the +.Sx EXAMPLES +section below for examples of +.Nm +usage. +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 +.Ar netid . +If +.Ar infile +is not specified, +.Nm +accepts the standard input. +.Pp +The C preprocessor, +.Em cc -E +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 indent +.It RPC_HDR +defined when compiling into headers +.It RPC_XDR +defined when compiling into XDR routines +.It RPC_SVC +defined when compiling into server-side stubs +.It RPC_CLNT +defined when compiling into client-side stubs +.It RPC_TBL +defined when compiling into RPC dispatch tables +.El +.Pp +Any line beginning with +.Dq % +is passed directly into the output file, +uninterpreted by +.Nm . +To specify the path name of the C preprocessor use +.Fl Y +flag. +.Pp +For every data type referred to in +.Ar infile , +.Nm +assumes that there exists a +routine with the string +.Em 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 +.Xr xdr 3 +routines. +.Sh OPTIONS +The following options are available: +.Bl -tag -width indent +.It Fl a +Generate all files, including sample files. +.It Fl b +Backward compatibility mode. +Generate transport specific +.Tn RPC +code for older versions +of the operating system. +.Pp +Note: in +.Fx , +this compatibility flag is turned on by +default since +.Fx +supports only the older +.Tn ONC RPC +library. +.It Fl c +Compile into +.Tn XDR +routines. +.It Fl C +Generate header and stub files which can be used with +.Tn ANSI +C compilers. Headers generated with this flag can also be +used with C++ programs. +.It Fl D Ns Ar name +.It Fl D Ns Ar name=value +.\".It Fl D Ns Ar name Ns Op Ar =value +Define a symbol +.Ar name . +Equivalent to the +.Em #define +directive in the source. +If no +.Ar value +is given, +.Ar value +is defined as +.Em 1 . +This option may be specified more than once. +.It Fl h +Compile into C data-definitions (a header). +.Fl T +option can be used in conjunction to produce a +header which supports +.Tn RPC +dispatch tables. +.It Fl i Ar size +Size at which to start generating inline code. +This option is useful for optimization. +The default size is 5. +.Pp +Note: in order to provide backwards compatibility with the older +.Nm +on the +.Fx +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. +.It Fl I +Compile support for +.Xr inetd 8 +in the server side stubs. +Such servers can be self-started or can be started by +.Nm inetd . +When the server is self-started, it backgrounds itself by default. +A special define symbol +.Em RPC_SVC_FG +can be used to run the +server process in foreground, or the user may simply compile without +the +.Fl I +option. +.Pp +If there are no pending client requests, the +.Nm inetd +servers exit after 120 seconds (default). +The default can be changed with the +.Fl K +option. +All the error messages for +.Nm inetd +servers +are always logged with +.Xr syslog 3 . +.\" .IP +.\" Note: +.\" this option is supported for backward compatibility only. +.\" By default, +.\" .B rpcgen +.\" generates servers that can be invoked through portmonitors. +.Pp +.It Fl K Ar seconds +By default, services created using +.Nm +and invoked through +port monitors 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, +use +.Fl K Ar 0 . +To create a server that never exits, the appropriate argument is +.Fl k Ar -1 . +.Pp +When monitoring for a server, +some portmonitors +.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 +.Fl K Ar 0 . +.It Fl l +Compile into client-side stubs. +.It Fl L +When the servers are started in foreground, use +.Xr syslog 3 +to log the server errors instead of printing them on the standard +error. +.It Fl m +Compile into server-side stubs, +but do not generate a +.Qq main +routine. +This option is useful for doing callback-routines +and for users who need to write their own +.Qq main +routine to do initialization. +.It Fl M +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 +.Xr rpc_svc_calls 3 +functions are not yet MT-safe, which means that rpcgen generated server-side +code will not be MT-safe. +.It Fl 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 +.Nm +generated code. +To maintain backward compatibility, +this option is not the default. +.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 +( +.Fl c , +.Fl h , +.Fl l , +.Fl m , +.Fl n , +.Fl s , +.Fl \&Sc , +.Fl \&Sm , +.Fl \&Ss , +and +.Fl t +modes only). +.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). +This option may be specified more than once. +Note: +the transports are chosen at run time and not at compile time. +.It Fl \&Sc +Generate sample client code that uses remote procedure calls. +.It Fl \&Sm +Generate a sample +.Pa Makefile +which can be used for compiling the application. +.It Fl \&Ss +Generate sample server code that uses remote procedure calls. +.It Fl t +Compile into +.Tn RPC +dispatch table. +.It Fl T +Generate the code to support +.Tn RPC +dispatch tables. +.Pp +The options +.Fl c , +.Fl h , +.Fl l , +.Fl m , +.Fl s , +.Fl \&Sc , +.Fl \&Sm , +.Fl \&Ss , +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. +.It Fl Y Ar pathname +Give the name of the directory where +.Nm +will start looking for the C-preprocessor. +.El +.Sh EXAMPLES +The following example: +.Dl example% rpcgen -T prot.x +.Pp +generates all 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) +to the standard output. +.Dl example% rpcgen -h prot.x +.Pp +To send the test version of the +.Fl D Ns Ar TEST , +server side stubs for +all the transport belonging to the class +.Ar datagram_n +to standard output, use: +.Dl example% rpcgen -s datagram_n -DTEST prot.x +.Pp +To create the server side stubs for the transport indicated +by +.Ar netid +tcp, +use: +.Dl example% rpcgen -n tcp -o prot_svc.c prot.x +.Sh SEE ALSO +.Xr cc 1 , +.Xr rpc 3 , +.Xr syslog 3 , +.Xr inetd 8 +.\" .BR rpc_svc_calls (3) +.Rs +.%T The rpcgen chapter in the NETP manual +.Re |