rpc_clnt_cr(3R)

NAME
     rpc_clnt_create:  clnt_control, clnt_create, clnt_create_vers,
     clnt_destroy, clnt_dg_create, clnt_pcreateerror, clntraw_create,
     clnt_raw_create, clnt_spcreateerror, clnttcp_create, clnt_tli_create,
     clnt_tp_create, clntudp_create, clntudp_bufcreate, clnt_vc_create -
     library routines for dealing with creation and manipulation of CLIENT
     handles

DESCRIPTION
     RPC library routines allow C language programs to make procedure calls on
     other machines across the network.  First a CLIENT handle is created and
     then the client calls a procedure to send a data packet to the server.
     Upon receipt of the packet, the server calls a dispatch routine to
     perform the requested service, and then sends back a reply.

     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.20 (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.20.  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

     bool_t
     clnt_control(CLIENT *clnt, int req, void *info);

          A function macro used to change or retrieve various information
          about a client object.  req indicates the type of operation, and
          info is a pointer to the information.  For both connectionless (UDP)
          and connection-oriented (TCP) transports, the supported values of
          req and their argument types and what they do are:
          CLSET_TIMEOUT       struct timeval       set total timeout

          CLGET_TIMEOUT       struct timeval       get total timeout
          CLGET_SERVER_ADDR   struct sockaddr_in   get server's address
          CLGET_SVC_ADDR      struct netbuf        get server's address (fills in netbuf to point to internal storage)
          CLGET_FD            int                  get connection's file descriptor
          CLSET_FD_CLOSE      (ignored)            let clnt_destroy close fd
          CLSET_FD_NCLOSE     (ignored)            don't let clnt_destroy close fd
          CLGET_XID           uint32_t             get transaction id
          CLSET_XID           uint32_t             set transaction id
          CLGET_VERS          rpcvers_t            get program version
          CLSET_VERS          rpcvers_t            set program version
          CLGET_PROG          rpcprog_t            get program number
          CLSET_PROG          rpcprog_t            set program number

          Note: if you set the timeout using clnt_control, the timeout
          parameter passed to clnt_call will be ignored in all future calls.


          The following operations are valid for connectionless (UDP)
          transports only:
          CLSET_RETRY_TIMEOUT   struct timeval   set the retry timeout
          CLGET_RETRY_TIMEOUT   struct timeval   get the retry timeout
          CLSET_SVC_ADDR        struct netbuf    set server's address

          The retry timeout is the time that RPC waits for the server to reply
          before retransmitting the request.

          The following operations are valid for connection-oriented (TCP)
          transports only:
          CLSET_EINTR_RETURN   bool_t   set parameter to 1 to return on EINTR
          CLGET_EINTR_RETURN   bool_t   get return on EINTR flag
          clnt_control returns 1 on success and 0 on failure.

     CLIENT *
     clnt_create(const char *host, u_long prognum,
          u_long versnum, const char *nettype);

          Generic client creation routine for program prognum and version
          versnum.  host identifies the name of the remote host where the
          server is located.  nettype indicates which kind of transport
          protocol to use.  The currently supported values for this field are
          "udp" and "tcp".

          Default timeouts are set, but can be modified using clnt_control.

          Warning: Using UDP has its shortcomings.  Since UDP-based RPC
          messages can only hold up to a few kilobytes of encoded data, this
          transport cannot be used for procedures that take large arguments or
          return huge results.

     CLIENT *
     clnt_create_vers(const char *host, u_long prognum,
          u_long *vers_out, u_long vers_low,
          u_long vers_high, const char *proto);

          Generic client creation with version checking. The server must
          support a version between vers_low and vers_high, inclusive.  An
          error results if this can not be done.  The value of *vers_out is
          set to the highest server-supported value.

     void
     clnt_destroy(CLIENT *clnt);

          A function macro that destroys the client's RPC handle.  Destruction
          usually involves deallocation of private data structures, including
          clnt itself.  Use of clnt is undefined after calling clnt_destroy.
          If the RPC library opened the associated socket, or CLSET_FD_CLOSE
          was set using clnt_control, it will be closed.  Otherwise, the
          socket remains open and it is the responsibility of the caller to
          close the socket.

     CLIENT *
     clnt_dg_create(int sock, const struct netbuf *svcaddr,
          u_long prognum, u_long versnum,
          u_int sendsz, u_int recvsz);

          BSD TI-RPC only.  This routine creates an RPC client for the remote
          program prognum and version versnum; the client uses a
          connectionless (e.g. UDP) transport.  The remote program is located
          at address svcaddr.  The parameter sock is an open socket of type
          SOCK_DGRAM.  This routine returns NULL if it fails.  This routine
          will set the resend timeout to 15 seconds; the retry time out and
          the total time out periods can be changed using clnt_control.  The
          user may set the size of the send and receive buffers with the
          parameters sendsz and recvsz; values of 0 choose suitable defaults.

     void
     clnt_pcreateerror(const char *s);

          Print a message to standard error indicating why a client RPC handle
          could not be created.  The message is prepended with the string s
          and a colon, and appended with a newline.  Should be used when a
          client creation function call (e.g. clnt_create, clntraw_create,
          clnttcp_create, etc) fails.

     CLIENT *
     clntraw_create(u_long prognum, u_long versnum);

          This routine creates a toy RPC client for the remote program prognum
          and version versnum.  The transport used to pass messages to the
          service is a buffer within the process's address space, so the
          corresponding RPC server should live in the same address space; (see
          svcraw_create in rpc(3R)).  This 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.
          clntraw_create should be called after svcraw_create.

     CLIENT *
     clnt_raw_create(u_long prognum, u_long versnum);

          BSD TI-RPC only.  Same as clntraw_create.

     char *
     clnt_spcreateerror(const char *s);

          Like clnt_pcreateerror, except that it returns a string instead of
          printing to the standard error.  A newline is not appended to the
          message in this case.

          Note:  returns a pointer to static data that is overwritten on each
          call.

     CLIENT *
     clnttcp_create(struct sockaddr_in *addr,
          u_long prognum, u_long versnum,
          int *sockp, u_int sendsize, u_int recvsize);

          This routine creates an RPC client for the remote program prognum,
          version versnum; the client uses TCP/IPv4 as a transport. The remote
          program is located at Internet address *addr.  If addr->sin_port is
          0, then it is set to the actual port that the remote program is
          listening on (the remote portmap service is consulted for this
          information). The parameter sockp is a socket; if it is RPC_ANYSOCK,
          then this routine opens a new one and sets *sockp.  Since TCP-based
          RPC uses buffered I/O, the user may specify the size of the send and
          receive buffers with the parameters sendsize and recvsize; values of
          0 choose suitable defaults.  This routine returns NULL if it fails.

     CLIENT *
     clnt_tli_create(int sock, const struct netconfig *netconf,
          const struct netbuf *svcaddr, u_long prognum,
          u_long versnum, u_int sendsz,
          u_int recvsz);

          BSD TI-RPC only.  This routine creates an RPC client handle for the
          remote program prognum and version versnum.  The remote program is
          located at address svcaddr.  If svcaddr is NULL and if netconf
          describes a connection-oriented transport, it is assumed that the
          socket is connected.  For connectionless transports, if svcaddr is
          NULL, RPC_UNKNOWNADDR error is set.  sock is a socket which may be
          open and connected.  If it is RPC_ANYSOCK, the function creates a
          socket on the transport specified by netconf.  If netconf is NULL, a
          RPC_UNKNOWNPROTO error is set.  For connection-oriented transports,
          if sock is unconnected, and svcaddr is not NULL, the function will
          attempt to connect.  The user may specify the size of the buffers
          with the parameters sendsz and recvsz; values of 0 choose suitable
          defaults.  Depending upon the type of the transport (connection-
          oriented or connectionless), clnt_tli_create calls appropriate
          client creation routines.  This routine returns NULL if it fails.
          The clnt_pcreaterror routine can be used to print the reason for
          failure.  The remote portmap service [see portmap(1M)] will not be
          consulted for the address of the remote service.

     CLIENT *
     clnt_tp_create(const char *host, u_long prognum,
          u_long versnum, const struct netconfig *netconf);

          BSD TI-RPC only.  clnt_tp_create creates a client handle for the
          transport specified by netconf.  Default options are set, which can
          be changed using clnt_control calls.  The remote portmap service on
          the host host is consulted for the address of the remote service.
          This routine returns NULL if it fails.  The clnt_pcreaterror routine
          can be used to print the reason for failure.

     CLIENT *
     clntudp_create(struct sockaddr_in *addr,
          u_long prognum, u_long versnum,
          struct timeval wait, int *sockp)

          This routine creates an RPC client for the remote program prognum,
          version versnum; the client uses use UDP/IPv4 as a transport. The
          remote program is located at Internet address addr.  If
          addr->sin_port is 0, then it is set to actual port that the remote
          program is listening on (the remote portmap service is consulted for
          this information).  The parameter *sockp is a socket; if it is
          RPC_ANYSOCK, then this routine opens a new one and sets *sockp.  The
          UDP transport resends the call message in intervals of wait time
          until a response is received or until the call times out.  The total
          time for the call to time out is specified by clnt_call and
          clnt_control.

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

     CLIENT *
     clntudp_bufcreate(struct sockaddr_in *addr,
          u_long prognum, u_long versnum,
          struct timeval wait, int *sockp,
          u_int sendsize, u_int recvsize)

          Like clntudp_create, except this call allows the user to specify the
          maximum packet size for sending and receiving UDP-based RPC
          messages.

     CLIENT *
     clnt_vc_create(int sock, const struct netbuf *svcaddr,
          u_long prognum, u_long versnum,
          u_int sendsz, u_int recvsz);

          BSD TI-RPC only.  This routine creates an RPC client for the remote
          program prognum and version versnum.  The client uses a connection-
          oriented transport.  The remote program is located at address
          svcaddr.  The parameter sock is an open socket of type SOCK_STREAM.
          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.

          The address svcaddr should not be NULL and should point to the
          actual address of the remote program.  clnt_vc_create will not
          consult the remote portmap service for this information.


     struct rpc_createerr     rpc_createerr

          A global variable whose value is set by any RPC client creation
          routine that does not succeed.  Use the routine clnt_pcreateerror()
          to print the reason why.

SEE ALSO
     getnetconfigent(3N), portmap(1M), rpc_clnt_calls(3R).  rpc(3R).