rpc_clnt_calls(3R)

NAME
     rpc_clnt_calls: callrpc, clnt_broadcast, clnt_broadcast_exp, clnt_call,
     clnt_freeres, clnt_geterr, clnt_perrno, clnt_perror,
     clnt_setbroadcastbackoff, clnt_sperrno, clnt_sperror, clnt_syslog,
     get_myaddress - library routines of client side Remote Procedure Call
     (RPC) library

SYNOPSIS AND DESCRIPTION
     These routines allow C programs to make procedure calls on other machines
     across the network. First, 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. Finally, the procedure call returns to the client.

     This page describes routines in the IRIX standard C library (libc).

     #include <rpc/rpc.h>


     enum clnt_stat
     callrpc(const char *host, rpcprog_t prognum,
          rpcvers_t versnum, rpcproc_t procnum,
          xdrproc_t inproc, void *in,
          xdrproc_t outproc, void *out)

          Call the remote procedure associated with prognum, versnum, and
          procnum on the machine, host.  The parameter in is the address of
          the procedure's argument(s), and out is the address of where to
          place the result(s); inproc is used to encode the procedure's
          parameters, and outproc is used to decode the procedure's results.
          This routine returns 0 if it succeeds, or the value of enum
          clnt_stat cast to an integer if it fails.  The routine clnt_perrno()
          is handy for translating failure statuses into messages.

          Warning: calling remote procedures with this routine uses UDP/IP as
          a transport; see clntudp_create() for restrictions.  You do not have
          control of timeouts or authentication using this routine.


     enum clnt_stat
     clnt_broadcast(rpcprog_t prognum,
         rpcvers_t versnum, rpcproc_t procnum,
         xdrproc_t inproc, void *in,
         xdrproc_t outproc, void *out,
         bool_t (*eachresult)(void *, struct sockaddr_in *))

          Like callrpc(), except the call message is broadcast to all locally
          connected broadcast nets. Each time it receives a response, this
          routine calls eachresult(), whose form is:

               bool_t
               eachresult(void *out, struct sockaddr_in *addr)

          where out is the same as out passed to clnt_broadcast(), except that
          the remote procedure's output is decoded there; addr points to the
          address of the machine that sent the results.  If eachresult()
          returns 0, clnt_broadcast() waits for more replies; otherwise it
          returns with appropriate status.  Initially, it waits 4 seconds for
          a response before retrying.  The next wait interval is doubled until
          it reaches a total wait time of 45 seconds.  See also
          clnt_setbroadcastbackoff().

          Warning: broadcast sockets are limited in size to the maximum
          transfer unit of the data link.  For ethernet, this value is 1500
          bytes.  For FDDI, this value is 4532 bytes.


     enum clnt_stat
     clnt_broadcast_exp(rpcprog_t prognum,
         rpcvers_t versnum, rpcproc_t procnum,
         xdrproc_t inproc, void *in,
         xdrproc_t outproc, void *out,
         bool_t (*eachresult)(void *, struct sockaddr_in *),
         int inittime, waittime)

          Like clnt_broadcast(), except you can specify the initial and total
          wait time.  See also clnt_setbroadcastbackoff().


     enum clnt_stat
     clnt_call(CLIENT *clnt, rpcproc_t procnum,
          xdrproc_t inproc, void *in,
          xdrproc_t outproc, void *out,
          struct timeval tout)

          A macro that calls the remote procedure procnum associated with the
          client handle, clnt, which is obtained with an RPC client creation
          routine such as clntudp_create().  The parameter in is the address
          of the procedure's argument(s), and out is the address of where to
          place the result(s); inproc is used to encode the procedure's
          parameters, and outproc is used to decode the procedure's results;
          tout is the time allowed for results to come back.


     bool_t
     clnt_freeres(CLIENT *clnt, xdrproc_t outproc, void *out)

          A macro that frees any data allocated by the RPC/XDR system when it
          decoded the results of an RPC call.  The parameter out is the
          address of the results, and outproc is the XDR routine describing
          the results.  This routine returns 1 if the results were
          successfully freed, and 0 otherwise.
     void
     clnt_geterr(CLIENT *clnt, struct rpc_err *errp)

          A macro that copies the error structure out of the client handle to
          the structure at address errp.


     void
     clnt_perrno(enum clnt_stat stat)

          Print a message to standard error corresponding to the condition
          indicated by stat.  Used after callrpc().


     void
     clnt_perror(CLIENT *clnt, const char *s)

          Print a message to standard error indicating why an RPC call failed;
          clnt is the handle used to do the call.  The message is prepended
          with string s and a colon.  Used after clnt_call().


     void
     clnt_setbroadcastbackoff(void (*first)(struct timeval *tv),
          int (*next)(struct timeval *tv))

          Set the timeout backoff iterator for clnt_broadcast().  The initial
          timeout is stored in *tv by first().  Subsequent timeouts are
          computed in *tv by next() , which returns 1 until a backoff limit is
          reached, and thereafter returns 0.


     char *
     clnt_sperrno(enum clnt_stat stat)

          Take the same arguments as clnt_perrno(), but instead of sending a
          message to the standard error indicating why an RPC call failed,
          return a pointer to a string which contains the message.  The string
          ends with a NEWLINE.

          clnt_sperrno() is used instead of clnt_perrno() if the program does
          not have a standard error (a server program quite likely does not),
          or if the programmer does not want the message to be output with
          printf, or if a message format different than that supported by
          clnt_perrno() is to be used.

          Note: unlike clnt_sperror() and clnt_spcreaterror(), clnt_sperrno()
          returns a pointer to static data, but the result will not get
          overwritten on each call.

     char *
     clnt_sperror(CLIENT *clnt, const char *s)

          Like clnt_perror(), except that (like clnt_sperrno()) it returns a
          string instead of printing to standard error.

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


     void
     clnt_syslog(CLIENT *clnt, const char *s)

          Logs a LOG_ERR error to syslog(3) indicating why an RPC call failed;
          clnt is the handle used to do the call.  The message is prepended
          with string s and a colon.


     void
     get_myaddress(struct sockaddr_in *addr)

          Stuff the machine's IP address into *addr, without consulting the
          library routines that deal with /etc/hosts.  The port number is
          always set to htons(PMAPPORT).

SEE ALSO
     rpc(3R), rpc_clnt_cr(3R), xdr(3R), IRIX Network Programming Guide.