rpc_clnt(3) Library Functions Manual rpc_clnt(3)
NAME
callrpc, clnt_broadcast, clnt_call, clnt_create, clnt_control, clnt_destroy, clnt_freeres, clnt_geterr, clnt_pcreateerror, clnt_perrno,
clnt_perror, clnt_spcreateerror, clnt_sperrno, clnt_sperror, clntraw_create, clnttcp_create, clntudp_create - Library routines for client
ONC remote procedure calls
SYNOPSIS
#include <rpc/rpc.h>
callrpc( char *host, u_int prognum, u_int versnum, u_int procnum, xdrproc_t inproc, char *in, xdrproc_t
outproc, char *out);
enum clnt_stat clnt_broadcast( u_int prognum, u_int versnum, u_int procnum, xdrproc_t inproc, char *in, xdr-
proc_t outproc, char *out, resultproc_t eachresult);
eachresult( char *out, struct sockaddr_in *addr);
enum clnt_stat clnt_call( CLIENT *clnt, u_int procnum, xdrproc_t inproc, char *in, xdrproc_t outproc, char
*out, struct timeval tout);
clnt_destroy(CLIENT *clnt);
CLIENT * clnt_create( char *host, u_int prog, u_int vers, char *proto);
bool_t clnt_control( CLIENT *cl, int req, char *info);
clnt_freeres( CLIENT *clnt, xdrproc_t outproc, char *out);
void clnt_geterr( CLIENT *clnt, struct rpc_err *errp);
void clnt_pcreateerror(char *s);
void clnt_perrno(enum clnt_stat stat);
clnt_perror( CLIENT *clnt, char *s);
char * clnt_spcreateerror(char *s);
char * clnt_sperrno(enum clnt_stat stat);
char *clnt_sperror( CLIENT *rpch, char *s);
CLIENT *clntraw_create( u_int prognum, u_int versnum);
CLIENT * clnttcp_create( struct sockaddr_in *addr, u_int prognum, u_int versnum, int *sockp, u_int sendsz,
u_int recvsz);
CLIENT * clntudp_create( struct sockaddr_in *addr, u_int prognum, u_int versnum, struct timeval wait, int *sockp);
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.
Unless otherwise indicated, the routines described in this reference page are thread safe (that is, they can be used safely in a multi-
threaded environment). Routines that are not thread safe are flagged as such.
Calls the remote procedure associated with prognum, versnum, and procnum on the machine host. The in parameter is the address of the pro-
cedure'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 out-
proc is used to decode the procedure's results. This routine returns zero if it succeeds, or the value of enum clnt_stat cast to an inte-
ger if it fails. The clnt_perrno() routine 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. Like callrpc(), except the call message is broadcast to all locally
connected broadcast nets. Each time it receives a response, this routine calls the eachresult() routine, which has the following
form: The out parameter is the same as the out parameter 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 zero, clnt_broadcast() waits for more replies; otherwise it returns with appropriate status. If eachre-
sult() is NULL, clnt_broadcast() returns without waiting for any replies.
Warning: Broadcast sockets are limited in size to the maximum transfer unit of the data link. For Ethernet, the caller's argument
size should not exceed 1400 bytes. 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 clnt_create(). The in parameter is the address of the procedure's argu-
ment(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. A 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, it will close it also. Otherwise, the socket
remains open. Generic client creation routine. The host parameter identifies the name of the remote host where the server is
located. The proto parameter 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: Since UDP-based RPC messages can only hold up to 8 Kbytes of encoded data, this transport cannot be used for procedures
that take large arguments or return huge results. A macro that is used to change or retrieve various information about a client
object. The req parameter indicates the type of operation, and info is a pointer to the information. For UDP and TCP, req has the
following supported values, argument types, and purposes:
CLSET_TIMEOUT struct timeval set total timeout
CLGET_TIMEOUT struct timeval get total timeout
CLGET_FD int get associated socket
CLSET_FD_CLOSE void close socket on clnt_destroy()
CLSET_FD_NOCLOSE void leave socket open on clnt_destroy()
If you set the timeout using clnt_control(), the timeout parameter passed to clnt_call() will be ignored in all future calls.
CLGET_SERVER_ADDR struct sockaddr get server's address
The following operations are valid for UDP only:
CLSET_RETRY_TIMEOUT struct timeval set the retry timeout
CLGET_RETRY_TIMEOUT struct timeval get the retry timeout
The retry timeout is the time that UDP RPC waits for the server to reply before retransmitting the request. A macro that frees any
data allocated by the RPC/XDR system when it decoded the results of an RPC call. The out parameter is the address of the results,
and outproc is the XDR routine describing the results. This routine returns one (1) if the results were successfully freed, and
zero (0) otherwise. A macro that copies the error structure out of the client handle to the structure at address errp. Prints a
message to standard error indicating why a client RPC handle could not be created. The message is prepended with string s and a
colon. Used when a clnt_create(), clntraw_create(), clnttcp_create(), or clntudp_create() call fails. Prints a message to standard
error corresponding to the condition indicated by stat. Used after callrpc(). Prints 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(). Like clnt_pcreateerror(), except that it returns a string instead of printing to the standard error.
Returns pointer to static data that is overwritten on each call. Takes the same arguments as clnt_perrno(), but instead of sending
a message to the standard error indicating why an RPC call failed, returns a pointer to a string that 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 (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, or if a message format different
than that supported by clnt_perrno() is to be used.
Unlike clnt_sperror() and clnt_spcreaterror(), clnt_sperrno() does not return pointer to static data so the result will not be over-
written on each call. Like clnt_perror(), except that (like clnt_sperrno()) it returns a string instead of printing to standard
error.
Returns pointer to static data that is overwritten on each call. Creates a toy RPC client for the remote program prognum, version
versnum. The transport used to pass messages to the service is actually a buffer within the process's address space, so the corre-
sponding RPC server should live in the same address space; see svcraw_create(). 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. Creates an RPC
client for the remote program prognum, version versnum; the client uses TCP/IP as a transport. The remote program is located at
Internet address *addr. If addr->sin_port is zero, 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, this routine opens a new
socket 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 sendsz and recvsz parameters; values of zero choose suitable defaults. This routine returns NULL if it fails. Creates an RPC
client for the remote program prognum, version versnum; the client uses use UDP/IP as a transport. The remote program is located at
Internet address addr. If addr->sin_port is zero, 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, this routine opens a new
socket 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().
Warning: Since UDP-based RPC messages can only hold up to 8 Kbytes of encoded data, this transport cannot be used for procedures
that take large arguments or return huge results.
RELATED INFORMATION
rpc_misc(3), rpc_svc(3), rpc_xdr(3), xdr(3)
Remote Procedure Calls: Protocol Specifications - RFC 1050 delim off
rpc_clnt(3)