rpc_clnt(3)rpc_clnt(3)NAME
rpc_clnt, callrpc, clnt_broadcast, clnt_call, clnt_create, clnt_con‐
trol, clnt_destroy, clnt_freeres, clnt_geterr, clnt_pcreateerror,
clnt_perrno, clnt_perror, clnt_spcreateerror, clnt_sperrno, clnt_sper‐
ror, clntraw_create, clnttcp_create, clntudp_bufcreate, 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,
xdrproc_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_bufcreate(
struct sockaddr_in *addr,
u_int prognum,
u_int versnum,
struct timeval wait,
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 proc‐
num on the machine host. The in parameter is the address of the proce‐
dure'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
zero if it succeeds, or the value of enum clnt_stat cast to an integer
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 rou‐
tine. 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. The out
parameter is the same as the out parameter passed to clnt_broad‐
cast(), 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
eachresult() 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 argu‐
ment 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 proce‐
dure'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. 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 proce‐
dures 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 opera‐
tion, 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()
Note
If you set the timeout using clnt_control(), the timeout parame‐
ter 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.
Note
Returns pointer to static data that is overwritten on each call.
Takes the same arguments as clnt_perrno(), but instead of send‐
ing 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 differ‐
ent than that supported by clnt_perrno() is to be used.
Note
Unlike clnt_sperror() and clnt_spcreaterror(), clnt_sperrno()
does not return pointer to static data so the result will not be
overwritten on each call. Like clnt_perror(), except that, like
clnt_sperrno(), it returns a string instead of printing to stan‐
dard error.
Note
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
corresponding RPC server should live in the same address space;
see svcraw_create(). This allows simulation of RPC and acquisi‐
tion 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 pro‐
gram 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 rou‐
tine returns NULL if it fails. Like clntudp_create(), except
that this routine allows the size of the maximum UDP packet that
can be sent or received to be specified. If sendz or recvsz is
set to 0, a default maximum size is used. 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 proce‐
dures that take large arguments or return huge results.
SEE ALSOrpc_misc(3), rpc_svc(3), rpc_xdr(3), xdr(3)
Remote Procedure Calls: Protocol Specifications -- RFC 1050
rpc_clnt(3)
