rpcgen(1)                                               rpcgen(1)

NAME
       rrppccggeenn - an RPC protocol compiler

SYNOPSIS
       rrppccggeenn infile
       rrppccggeenn [[--DDname[[==value]]]] [[--TT]] [[--KK secs]] infile
       rrppccggeenn --cc||--hh||--ll||--mm||--tt [[--oo outfile ]] infile
       rrppccggeenn [[--II]] --ss nettype [[--oo outfile]] infile
       rrppccggeenn --nn netid [[--oo outfile]] infile

DESCRIPTION
       rrppccggeenn is a tool that generates C code to implement an RPC
       protocol.  The input to rrppccggeenn is a language similar to  C
       known as RPC Language (Remote Procedure Call Language).

       rrppccggeenn  is normally used as in the first synopsis where it
       takes an input file and generates up to four output files.
       If  the infile is named pprroottoo..xx, then rrppccggeenn will generate
       a header file in pprroottoo..hh,  XDR  routines  in  pprroottoo__xxddrr..cc,
       server-side stubs in pprroottoo__ssvvcc..cc, and client-side stubs in
       pprroottoo__ccllnntt..cc.  With the --TT option, it will  also  generate
       the  RPC  dispatch  table  in  pprroottoo__ttbbll..ii.   With the --SScc
       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 pprroottoo__cclliieenntt..cc.   With
       the --SSss option, it will also generate a sample server code
       which would illustrate how to write the remote procedures.
       This code would be created in pprroottoo__sseerrvveerr..cc.

       The  server  created can be started both by the port moni-
       tors (for example, iinneettdd or lliisstteenn) or by itself.  When it
       is  started by a port monitor, it creates servers only for
       the transport for which the file descriptor 00 was  passed.
       The  name of the transport must be specified by setting up
       the environmental variable PPMM__TTRRAANNSSPPOORRTT.  When the  server
       generated by rrppccggeenn is executed, it creates server handles
       for all the transports specified  in  NNEETTPPAATTHH  environment
       variable, or if it is unset, it creates server handles for
       all  the  visible  transports  from  //eettcc//nneettccoonnffiigg  file.
       Note:  the  transports  are  chosen at run time and not at
       compile time.  When the server is self-started,  it  back-
       grounds  itself  by  default.   A  special  define  symbol
       RRPPCC__SSVVCC__FFGG can be used to run the server process in  fore-
       ground.

       The  second synopsis provides special features which allow
       for the creation of more sophisticated RPC servers.  These
       features  include  support  for user provided ##ddeeffiinneess and
       RPC dispatch tables.  The  entries  in  the  RPC  dispatch
       table contain:
              o  pointers to the service routine corresponding to
                 that procedure,
              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  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  rrppccggeenn  is  executed
       with the --ss option, it creates servers for that particular
       class of transports.  When executed with the --nn option, it
       creates a server for the transport specified by netid.  If
       infile is  not  specified,  rrppccggeenn  accepts  the  standard
       input.

       The C preprocessor, cccc --EE [see cccc(1)], is run on the input
       file before it is actually  interpreted  by  rrppccggeenn.   For
       each type of output file, rrppccggeenn defines a special prepro-
       cessor symbol for use by the rrppccggeenn programmer:

       RRPPCC__HHDDRR     defined when compiling into header files
       RRPPCC__XXDDRR     defined when compiling into XDR routines
       RRPPCC__SSVVCC     defined when compiling into server-side stubs
       RRPPCC__CCLLNNTT    defined when compiling into client-side stubs
       RRPPCC__TTBBLL     defined  when  compiling  into  RPC   dispatch
                   tables

       Any  line  beginning  with `%%' is passed directly into the
       output file, uninterpreted by rrppccggeenn.

       For every data type referred to in infile, rrppccggeenn  assumes
       that there exists a routine with the string xxddrr__ prepended
       to the name of the data type.  If this  routine  does  not
       exist  in  the RPC/XDR library, it must be provided.  Pro-
       viding an undefined data type allows customization of  XDR
       routines.

       The following options are available:

       --aa     Generate  all  the  files including sample code for
              client and server side.

       --bb     This generates code for the SunOS4.1 style of  rpc.
              It  is  for  backward  compatibilty.   This  is the
              default.

       --55     This generates code for the SysVr4 style of rpc. It
              is used by the Transport Independent RPC that is in
              Svr4 systems.  By default rpcgen generates code for
              SunOS4.1 stype of rpc.

       --cc     Compile into XDR routines.

       --CC     Generate code in ANSI C. This option also generates
              code that could be compiled with the C++  compiler.
              This is the default.

       --kk     Generate code in K&R C.  The default is ANSI C.

       --DDname[[==value]]
              Define  a  symbol  name.  Equivalent to the ##ddeeffiinnee
              directive in the source.  If  no  value  is  given,
              value  is  defined as 11.  This option may be speci-
              fied more than once.

       --hh     Compile into CC data-definitions  (a  header  file).
              --TT  option  can be used in conjunction to produce a
              header file which supports RPC dispatch tables.

       --II     Generate a service that can be started from  inetd.
              The  default  is  to generate a static service that
              handles transports  selected  with  --ss.   Using  --II
              allows starting a service by either method.

       --KK secs
              By  default, services created using rrppccggeenn wait 112200
              seconds after servicing a request  before  exiting.
              That interval can be changed using the --KK flag.  To
              create a server that exits immediately upon servic-
              ing  a  request,  --KK 00  can  be  used.  To create a
              server that never exits, the  appropriate  argument
              is --KK --11.

              When  monitoring  for  a server, some portmonitors,
              like lliisstteenn(1M), 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, rrppccggeenn should be used with --KK --11.

       --ll     Compile into client-side stubs.

       --mm     Compile into server-side stubs, but do not generate
              a  "main" routine.  This option is useful for doing
              callback-routines and for users who need  to  write
              their own "main" routine to do initialization.

       --nn netid
              Compile  into  server-side  stubs for the transport
              specified by netid.  There should be an  entry  for
              netid  in  the netconfig database.  This option may
              be specified more than once, so  as  to  compile  a
              server that serves multiple transports.

       --NN     Use  the newstyle of rpcgen. 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  rpcgen generated code. The
              newstyle is not the default case because  of  back-
              ward compatibility.

       --oo outfile
              Specify  the  name  of the output file.  If none is
              specified, standard output is used (--cc, --hh, --ll, --mm,
              --nn, --ss, --ss --ssaanndd --tt modes only).

       --ss nettype
              Compile  into  server-side stubs for all the trans-
              ports belonging to the  class  nettype.   The  sup-
              ported  classes  are  nneettppaatthh,  vviissiibbllee, cciirrccuuiitt__nn,
              cciirrccuuiitt__vv, ddaattaaggrraamm__nn,  ddaattaaggrraamm__vv,  ttccpp,  and  uuddpp
              [see rrppcc(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.

       --SScc    Generate sample code to show the use of remote pro-
              cedure and how to bind to the server before calling
              the client side stubs generated by rpcgen.

       --SSss    Generate skeleton code for the remote procedures on
              the  server  side.  You  would  need to fill in the
              actual code for the remote procedures.

       --tt     Compile into RPC dispatch table.

       --TT     Generate the code to support RPC dispatch tables.

       The options --cc, --hh, --ll, --mm, --ss and --tt are used exclusively
       to  generate  a particular type of file, while the options
       --DD and --TT are global  and  can  be  used  with  the  other
       options.

NOTES
       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 apparent scoping does not really apply.  Most of
       these can be avoided by giving unique names for  programs,
       versions, procedures and types.

       The  server  code  generated  with --nn option refers to the
       transport indicated by netid and hence is very  site  spe-
       cific.

EXAMPLE
       The following example:

              $$ rrppccggeenn --TT pprroott..xx

       generates the five files: pprroott..hh, pprroott__ccllnntt..cc, pprroott__ssvvcc..cc,
       pprroott__xxddrr..cc and pprroott__ttbbll..ii.

       The following example sends the C data-definitions (header
       file) to the standard output.

              $$ rrppccggeenn --hh pprroott..xx

       To  send the test version of the --DDTTEESSTT, server side stubs
       for all the transport belonging to the class ddaattaaggrraamm__nn to
       standard output, use:

              $$ rrppccggeenn --ss ddaattaaggrraamm__nn --DDTTEESSTT pprroott..xx

       To  create  the  server side stubs for the transport indi-
       cated by netid ttccpp, use:

              $$ rrppccggeenn --nn ttccpp --oo pprroott__ssvvcc..cc pprroott..xx

SEE ALSO
       cccc(1).

                                                               0a