RPC_CLNT_CALLS(3R)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:
Page 1
RPC_CLNT_CALLS(3R)RPC_CLNT_CALLS(3R)
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.
Page 2
RPC_CLNT_CALLS(3R)RPC_CLNT_CALLS(3R)
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.
Page 3
RPC_CLNT_CALLS(3R)RPC_CLNT_CALLS(3R)
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 ALSOrpc(3R), rpc_clnt_cr(3R), xdr(3R), IRIX Network Programming Guide.
Page 4