rpc_clnt_calls(3C)

NAME

callrpc, clnt_broadcast, clnt_call, clnt_freeres, clnt_geterr, clnt_perrno, clnt_perror, clnt_sperrno, clnt_sperror − library of routines for handling the client-side of RPC calls and errors

SYNOPSIS

#include <rpc/rpc.h>

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

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

/* clnt_call() */
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;

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

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

/* clnt_perrno() */
void
clnt_perrno(stat)
enum clnt_stat stat;

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

/* clnt_sperrno() */
char *
clnt_sperrno(stat)
enum clnt_stat stat;

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

DESCRIPTION

The rpc_clnt_calls() routines clnt_call(), callrpc(), and clnt_broadcast() handle the client side of RPC calls. The remaining routines in this library are for error-handling.

Routines

These routines use the CLIENT data structure, which is defined in Power Programming with RPC.

To use these routines, the C client program must include the RPC header file, <rpc.h>.

callrpc() Calls a procedure on a remote machine. The callrpc() parameters are defined as follows:

host is the host id. of the remote machine.

prognum is the program number associated with the remote procedure.

versnum is the version number associated with the remote procedure.

procnum is the procedure number associated with the remote procedure.

in is the address of the argument of the remote procedure.

out is the address of the result of the remote procedure.

inproc is the XDR function used to encode the remote procedure.

outproc is the XDR function used to decode the results of the remote procedure.

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 the description of the clntudp_create() routine in rpc_clnt_create(3C) for restrictions. You do not have control of timeouts or authentication using this routine.

clnt_broadcast()
Similar to the callrpc() routine with one exception: the RPC message is broadcast to all broadcast nets connected locally. Each time the caller receives a response, this routine calls eachresult():

int eachresult(out, addr)
char *out;
struct sockaddr_in *addr;

The eachresult() parameters are defined as follows:

out is the address where the result of the RPC call is decoded.

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 the appropriate status. If eachresult() is NULL, clnt_broadcast() returns without waiting for any replies.

Note: clnt_broadcast() uses the 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.

clnt_call() Calls a remote procedure associated with a client handle (which is created with an RPC routine such as clnt_create(), as described in rpc_clnt_create(3C)). The clnt_call() parameters are defined as follows:

clnt is the client handle.

procnum is the procedure number associated with the remote procedure.

inproc is the XDR function used to encode the parameters of the remote proceudre.

in is the address of the argument of the remote procedure.

outproc is the XDR function used to decode the results of the remote procedure.

out is the address is the address of the result of the remote procedure.

timeout is the time allowed for a response from the server.

clnt_freeres()
Frees any data allocated by the RPC/XDR system when the results of an RPC call were decoded. The clnt_freeres() parameters are defined as follows:

clnt is the client handle.

outproc is the XDR function used to decode the RPC results.

out is the address where the RPC result is placed.

This routine returns TRUE if the results were successfully freed, and FALSE otherwise.

Note: This routine is equivalent to doing xdr_free() , as described in xdr_simple(3C).

clnt_geterr() Copies the error structure out of the client handle to the rpc_err structure. The clnt_geterr() parameters are defined as follows:

clnt is the client handle.

errp is the address of the structure, rpc_err. errp should point to a preallocated space.

clnt_perrno() Used after callrpc() or clnt_broadcast(): Prints a message to the standard error indicating to the condition obtained by stat(). A newline is appended at the end of the message.

clnt_perror() Used after clnt_call(): Prints a message to the standard error indicating why an RPC call failed. A newline is appended at the end of the message. The clnt_perror() parameters are defined as follows:

clnt is the client handle.

str is the error message, prefixed with string s and a colon.

clnt_sperrno()
Similar to clnt_perrno() with one exception: instead of sending a message to standard error that indicates why an RPC failed, this routine returns a pointer to a message string, and does not append a newline at the end of the message.

Use clnt_sperrno() instead of clnt_perrno() for any of the following reasons:

• the program does not have a standard error (as a program running
as a server quite likely does not).

• the programmer does not want the message to be output with printf( ).

• a message format different than that supported by clnt_perrno( )
is to be used.

clnt_sperror()
Similiar to the clnt_perror() routine with one exception: like clnt_sperrno(), it returns a string instead of printing to standard error and does not append the message with a newline. clnt_sperror() returns a pointer to a static buffer that is overwritten on each call.

AUTHOR

rpc() was developed by Sun Microsystems, Inc.

Museum

Related Articles

rpc_clnt_calls(3C)

NAME

SYNOPSIS

DESCRIPTION

Routines

AUTHOR

SEE ALSO