unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-4.1.3)
Page:
Section:
Apropos / Subsearch:
optional field

RPCGEN(1)                   General Commands Manual                  RPCGEN(1)



NAME
       rpcgen - RPC protocol compiler

SYNOPSIS
       rpcgen infile
       rpcgen [ -Dname[=value] ] [ -I [ -K seconds ] ] [ -L ] [ -T ] infile
       rpcgen -c | -h | -l | -m | -t [ -o outfile ] [ infile ]
       rpcgen -s transport [ -o outfile ] [ infile ]

DESCRIPTION
       rpcgen  generates  C  code  to implement an RPC protocol.  The input to
       rpcgen is a language similar to C known as  the  RPC  Language  (Remote
       Procedure Call Language).  Information about the syntax of RPC Language
       is available in the `rpcgen' Programming Guide in the manual.

       rpcgen is normally used as in the first  synopsis  where  it  takes  an
       input  file  and  generates  four output files.  If the infile is named
       proto.x, then rpcgen generates a header file in proto.h,  XDR  routines
       in proto_xdr.c, server side stubs in proto_svc.c, and client side stubs
       in proto_clnt.c.  With the -T option, it also generates  the  RPC  dis-
       patch table in proto_tbl.i.

       The  second synposis provides special features which allow for the cre-
       ation of more sophisticated RPC servers.  These features  include  sup-
       port  for RPC dispatch tables, and user provided #defines.  The entries
       in the RPC dispatch table contain:

              o  pointers to the service routine corresponding to that  proce-
                 dure
              o  a pointer to the input and output arguments
              o  the size of these routines

       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.

       The  other  two 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 EXAMPLES section below.

       The C-preprocessor, cpp(1), is run on the input file before it is actu-
       ally interpreted by rpcgen, so all the cpp directives are legal  within
       an  rpcgen  input  file. For each type of output file, rpcgen defines a
       special cpp symbol for use by the rpcgen programmer:

              RPC_HDR     defined when compiling into header files
              RPC_XDR     defined when compiling into XDR routines
              RPC_SVC     defined when compiling into server side stubs
              RPC_CLNT    defined when compiling into client side stubs
              RPC_TBL     defined when compiling into RPC dispatch tables

       In addition, rpcgen does a little preprocessing of its own.   Any  line
       beginning  with  `%'  is passed directly into the output file, uninter-
       preted by rpcgen.  For every data type referred to  in  infile,  rpcgen
       assumes that there exists a routine with the string `xdr_' prepended to
       the data type.  If this routine does not exist in the RPC/XDR  library,
       it  must  be  provided.   Providing  an undefined data type allows cus-
       tomization of XDR routines.

OPTIONS
       -c          Compile into XDR routines.

       -Dname[=value]
                   Define a symbol name.  Equivalent to the #define  directive
                   in the source.  If no value is given, name is defined as 1.
                   This option may be called more than once.

       -h          Compile into C data-definitions (a header  file).   The  -T
                   option  can be used in conjunction to produce a header file
                   which supports RPC dispatch tables.

       -I          Compile support for inetd(8C) in  the  server  side  stubs.
                   Such  servers  can  be  self  started  or can be started by
                   inetd.  When the server  is  self-started,  it  backgrounds
                   itself  by default.  A special define symbol RPC_SVC_FG can
                   be used to run the server process in foreground, or  alter-
                   nately  the user may just compile it without the -I option.
                   If there are no pending client requests, the inetd  servers
                   exit  after  120  seconds  (default).   The  default can be
                   changed with the -K option.  All  the  error  messages  for
                   inetd servers are always logged in with syslog(3).

       -K seconds  If  the  server  was  started by inetd, specify the time in
                   seconds after which the server should exit if there  is  no
                   further activity.  This option is useful for customization.
                   If seconds is 0, the server exits after serving that  given
                   request.   If  seconds  is  -1, the server hangs around for
                   ever after being started by inetd.  This  option  is  valid
                   only with the -I option.

       -l          Compile into client side stubs.

       -L          When the servers are started in foreground, use syslog() to
                   log the server errors instead of printing them on the stan-
                   dard error.

       -m          Compile  into  server  side  stubs,  but  do not generate a
                   "main" routine.  This option is useful for doing  callback-
                   routines  and for people who need to write their own "main"
                   routine to do  initialization.   For  inetd  support,  they
                   should  be  compiled  with the -I option. In such cases, it
                   defines 2 global  variables:  _rpcpmstart  and  _rpcfdtype.
                   The  value  of  _rpcpmstart should be 1 or 0 depending upon
                   whether it was started  by  inetd  or  not.  The  value  of
                   _rpcfdtype  should  be  SOCK_STREAM or SOCK_DGRAM depending
                   upon the type of the connection.

       -o outfile  Specify the name of the output file.  If none is specified,
                   the  standard  output  is  used  (-c, -h, -l, -m, -s and -t
                   modes only).

       -s transport
                   Compile into server side stubs  for  the  given  transport.
                   The  supported transports are udp and tcp.  This option may
                   be called more than once so as to  compile  a  server  that
                   serves multiple transports.  For inetd support, they should
                   be compiled with the -I option.

       -t          Compile into RPC dispatch table.

       -T          Generate the code to support RPC dispatch tables.

       The options -c, -h, -l, -m, -s and -t are used exclusively to  generate
       a  particular  type  of  file,  while the options -D, -I, -L and -T are
       global and can be used with the other options.

EXAMPLES
       The  following  example  generates  all   the   five   files:   prot.h,
       prot_clnt.c,  prot_svc.c,  prot_xdr.c and prot_tbl.i.  The server error
       messages are logged, instead of being sent to the standard error.

              example% rpcgen -LT prot.x

       The following example generates  prot.h,  prot_clnt.c,  prot_xdr.c  and
       prot_svc.c.   prot_svc.c  supports  server invocation by inetd.  If the
       server is started by inetd, the server exits after 20 seconds of  inac-
       tivity.

              example% rpcgen -I -K 20 prot.x

       The  following example sends the header file (with support for dispatch
       tables) on the standard output.

              example% rpcgen -hT prot.x

       The following example sends the server side stubs file for  the  trans-
       port tcp on the standard output.

              example% rpcgen -s tcp prot.x

SEE ALSO
       cpp(1), rpc(3N), inetd(8C)

       `rpcgen' Programming Guide in

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

       Name clashes can occur when using program definitions, since the appar-
       ent scoping does not really apply.  Most of these  can  be  avoided  by
       giving unique names for programs, versions, procedures and types.



                                20 January 1990                      RPCGEN(1)