callrpc, clnt_broadcast, clnt_call, clnt_freeres, clnt_geterr, clnt_perrno, clnt_perror, clnt_sperrno, clnt_sperror - library routines for client side calls

---

DESCRIPTION

RPC routines allow C programs to make procedure calls on other machines across the network. First, the client calls a procedure to send a request to the server. Upon receipt of the request, 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.

The clnt_call(), callrpc() and clnt_broadcast() routines handle the client side of the procedure call. The remaining routines deal with error handling in the case of errors.

Routines

The CLIENT data structure is defined in the RPC/XDR Library Definition of the [a manual with the abbreviation NETP].

#include <rpc/rpc.h>

int callrpc(host, prognum, versnum, procnum, inproc, in, outproc, out)
char *host;
u_long prognum, versnum, procnum;
char *in;
xdrproc_t inproc;
char *out;
xdrproc_t outproc;

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, and out is the address of where to place the result; inproc is an XDR function used to encode the procedure's parameters, and outproc is an XDR function 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. Use clnt_perrno() to translate failure statuses into messages.

Warning: Calling remote procedures with this routine uses UDP/IP as the transport; see clntudp_create() on rpc_clnt_create.3n for restrictions. You do not have control of timeouts or authentication using this routine.

enum clnt_stat clnt_broadcast(prognum, versnum, procnum, inproc, in, outproc, out, eachresult)
u_long prognum, versnum, procnum;
char *in;
xdrproc_t inproc;
char *out;
xdrproc_t outproc;
bool_t eachresult;

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

int eachresult(out, addr)
char *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. If eachresult() is NULL, clnt_broadcast() returns without waiting for any replies.

Note: clnt_broadcast() uses AUTH_UNIX style of authentication.

Warning: Broadcast packets are limited in size to the maximum transfer unit of the data link. For Ethernet, the callers argument size should not exceed 1400 bytes.

enum clnt_stat clnt_call(clnt, procnum, inproc, in, outproc, out, timeout)
CLIENT *clnt;
u_long procnum;
xdrproc_t inproc, outproc;
char *in, *out;
struct timeval timeout;

Call the remote procedure procnum associated with the client handle, clnt, which is obtained with an RPC client creation routine such as clnt_create() (see rpc_clnt_create.3n The parameter in is the address of the procedure's argument, and out is the address of where to place the result; inproc is an XDR function used to encode the procedure's parameters in XDR, and outproc is used to decode the procedure's results; timeout is the time allowed for a response from the server.

bool_t clnt_freeres(clnt, outproc, out)
CLIENT *clnt;
xdrproc_t outproc;
char *out;

Free 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 TRUE if the results were successfully freed, and FALSE otherwise. Note: This is equivalent to doing xdr_free(outproc, out) (see xdr_simple.3n

void clnt_geterr(clnt, errp)
CLIENT *clnt;
struct rpc_err *errp;

Copy the error structure out of the client handle to the structure at address errp. errp should point to preallocated space.

void clnt_perrno(stat)
enum clnt_stat stat;

Print a message to the standard error corresponding to the condition indicated by stat. A NEWLINE is appended at the end of the message. Used after callrpc() or clnt_broadcast().

void clnt_perror(clnt, str)
CLIENT *clnt;
char *str;

Print a message to the 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. A NEWLINE is appended at the end of the message. Used after clnt_call().

char *clnt_sperrno(stat)
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 failed, return a pointer to a string which contains the message. clnt_sperrno() does not append a NEWLINE at the end of the message.

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

char *clnt_sperror(clnt, str)
CLIENT *clnt;
char *str;

Like clnt_perror(), except that (like clnt_sperrno()) it returns a string instead of printing to the standard error. Unlike clnt_perror(), it does not append the message with a NEWLINE.

Note: clnt_sperror() returns pointer to a static buffer that is overwritten on each call.

SEE ALSO

Created by unroff & hp-tools. © somebody (See intro for details). All Rights Reserved. Last modified 11/5/97