rpc_svc_cr(3R)

NAME
     rpc_svc_create:  svc_create, svc_destroy, svc_dg_create, svc_fd_create,
     svc_raw_create, svc_tli_create, svc_tp_create, svc_vc_create,
     svcraw_create, svctcp_create, svcudp_bufcreate, svcudp_create - library
     routines for dealing with the creation of server handles

DESCRIPTION
     These routines are part of the RPC library which allows C language
     programs to make procedure calls on servers across the network.  These
     routines deal with the creation of service handles.  Once the handle is
     created, the server can be invoked by calling svc_run.

     This page describes functions in the IRIX standard C library (libc).
     Some of these functions are part of the new Transport Independent RPC
     (TI-RPC) functionality added to the IRIX standard C library in IRIX
     release 6.5.21 (known as BSD TI-RPC) and should not be confused with the
     older TI-RPC functionality in the UNIX System V Networking Library (known
     as System V TI-RPC, see intro(3N)).  In particular, the BSD TI-RPC
     functions use the BSD socket network API instead of the System V TLI
     network API.

     BSD TI-RPC functions are marked in this page as BSD TI-RPC only.  To use
     them code must be compiled with:

          cc -D_BSD_TIRPC prog.c


     The BSD TI-RPC functions in this page did not exist in IRIX before
     release 6.5.21.  Applications using them should use the
     _MIPS_SYMBOL_PRESENT macro to provide a graceful failure mode when run on
     older IRIX releases.

   Routines
     #include <rpc/rpc.h>
     #ifdef _BSD_TIRPC
     #include <netconfig.h>
     #endif

     int
     svc_create(
          void (*dispatch)(struct svc_req *, SVCXPRT *),
          rpcprog_t prognum, rpcvers_t versnum,
          const char *nettype);

          BSD TI-RPC only.  svc_create creates server handles for all the
          transports belonging to the class nettype.

          nettype defines a class of transports which can be used for a
          particular application.  The transports are tried in left to right
          order in NETPATH variable or in top to down order in the netconfig
          database.
          If nettype is NULL, it defaults to netpath.  svc_create registers
          itself with the rpcbind service [see rpcbind(1M)].  dispatch is
          called when there is a remote procedure call for the given prognum
          and versnum; this requires calling svc_run [see svc_run in rpc(3R)].
          If it succeeds, svc_create returns the number of server handles it
          created, otherwise it returns 0 and the error message is logged.

     void
     svc_destroy(SVCXPRT *xprt);

          A function macro that destroys the RPC service transport handle
          xprt.  Destruction usually involves deallocation of private data
          structures, including xprt itself.  Use of xprt is undefined after
          calling this routine.

     SVCXPRT *
     svc_dg_create(int fd, u_int sendsz, u_int recvsz);

          BSD TI-RPC only.  This routine creates a connectionless RPC service
          handle, and returns a pointer to it.  This routine returns NULL if
          it fails, and an error message is logged.  sendsz and recvsz are
          parameters used to specify the size of the buffers.  If they are 0,
          suitable defaults are chosen.  The file descriptor fd should be open
          and bound.

          Note:  since connectionless-based RPC messages can only hold limited
          amount of encoded data, this transport cannot be used for procedures
          that take large arguments or return huge results.

     SVCXPRT *
     svc_fd_create(int fd, u_int sendsz, u_int recvsz);

          BSD TI-RPC only.  This routine creates a service on top of any open
          and bound descriptor, and returns the handle to it.  Typically, this
          descriptor is a connected file descriptor for a connection-oriented
          transport.  sendsz and recvsz indicate sizes for the send and
          receive buffers.  If they are 0, a reasonable default is chosen.
          This routine returns NULL, if it fails, and an error message is
          logged.

     SVCXPRT *
     svc_raw_create(void);

          BSD TI-RPC only.  This routine creates a toy RPC service transport,
          to which it returns a pointer.  The transport is really a buffer
          within the process's address space, so the corresponding RPC client
          should live in the same address space; [see clnt_raw_create in
          rpc_clnt_create(3R)].  This routine allows simulation of RPC and
          acquisition of RPC overheads (such as round trip times), without any
          kernel interference.  This routine returns NULL if it fails, and an
          error message is logged.
     SVCXPRT *
     svc_tli_create(int fd, struct netconfig *netconf,
          struct t_bind *bindaddr, u_int sendsz,
          u_int recvsz);

          BSD TI-RPC only.  This routine creates an RPC server handle, and
          returns a pointer to it.  fd is the file descriptor on which the
          service is listening. If fd is RPC_ANYFD, it opens a file descriptor
          on the transport specified by netconf.  If the file descriptor is
          unbound, it is bound to the address specified by bindaddr, if
          bindaddr is non-null, otherwise it is bound to a default address
          chosen by the transport.  In the case where the default address is
          chosen, the number of outstanding connect requests is set to 8 for
          connection-oriented transports.  The user may specify the size of
          the send and receive buffers with the parameters sendsz and recvsz;
          values of 0 choose suitable defaults.  This routine returns NULL if
          it fails, and an error message is logged.

     SVCPRT *
     svc_tp_create(void (*dispatch)(struct svc_req *, SVCXPRT *),
          rpcprog_t prognum, rpcvers_t versnum,
          struct netconfig *netconf);

          BSD TI-RPC only.  svc_tp_create creates a server handle for the
          network specified by netconf, and registers itself with the rpcbind
          service.  dispatch is called when there is a remote procedure call
          for the given prognum and versnum; this requires calling svc_run.
          svc_tp_create returns the service handle if it succeeds, otherwise a
          NULL is returned, and an error message is logged.

     SVCXPRT *
     svc_vc_create(int fd, u_int sendsz, u_int recvsz);

          BSD TI-RPC only.  This routine creates a connection-oriented RPC
          service and returns a pointer to it.  This routine returns NULL if
          it fails, and an error message is logged.  The users may specify the
          size of the send and receive buffers with the parameters sendsz and
          recvsz; values of 0 choose suitable defaults.  The file descriptor
          fd should be open and bound.


     SVCXPRT *
     svcraw_create(void)

          This routine creates a toy RPC service transport, to which it
          returns a pointer.  The transport is really a buffer within the
          process's address space, so the corresponding RPC client should live
          in the same address space; see clntraw_create().  This routine
          allows simulation of RPC and acquisition of RPC overheads (such as
          round trip times), without any kernel interference.  This routine
          returns NULL if it fails.
     SVCXPRT *
     svctcp_create(int sock, u_int sendsize, u_int recvsize)

          This routine creates a TCP/IP-based RPC service transport, to which
          it returns a pointer.  The transport is associated with the socket
          sock, which may be RPC_ANYSOCK, in which case a new socket is
          created.  If the socket is not bound to a local TCP port, then this
          routine binds it to an arbitrary port.  Upon completion, -
          xprt->xp_sock is the transport's socket descriptor, and -
          xprt->xp_port is the transport's port number.  This routine returns
          NULL if it fails. Since TCP-based RPC uses buffered I/O, users may
          specify the size of the send and receive buffers; values of 0 choose
          suitable defaults.


     SVCXPRT *
     svcfd_create(int fd, u_int sendsize, u_int recvsize)

          Create a service on top of any open descriptor. Typically, this
          descriptor is a connected socket for a stream protocol such as TCP.
          sendsize and recvsize indicate sizes for the send and receive
          buffers.  If they are zero, a reasonable default is chosen.


     SVCXPRT *
     svcudp_bufcreate(int sock, u_int sendsize, u_int recvsize)

          This routine creates a UDP/IP-based RPC service transport, to which
          it returns a pointer.  The transport is associated with the socket
          sock, which may be RPC_ANYSOCK, in which case a new socket is
          created.  If the socket is not bound to a local UDP port, then this
          routine binds it to an arbitrary port. Upon completion, -
          xprt->xp_sock is the transport's socket descriptor, and -
          xprt->xp_port is the transport's port number.  This routine returns
          NULL if it fails.

          This allows the user to specify the maximun packet size for sending
          and receiving UDP-based RPC messages.


     SVCXPRT *
     svcudp_create(int sock)

          This routine creates a UDP/IP-based RPC service transport, to which
          it returns a pointer.  The transport is associated with the socket
          sock, which may be RPC_ANYSOCK, in which case a new socket is
          created.  If the socket is not bound to a local UDP port, then this
          routine binds it to an arbitrary port.  Upon completion,
          xprt->xp_sock is the transport's socket number, and xprt->xp_port is
          the transport's port number.  This routine returns NULL if it fails.

          Warning: since UDP-based RPC messages can only hold up to 8
          kilobytes of encoded data, this transport cannot be used for
          procedures that take large arguments or return huge results.

SEE ALSO
     getnetconfigent(3R), rpcbind(1M), rpc(3R), rpc_svc_calls(3R),
     rpc_svc_err(3R), rpc_svc_reg(3R)