rpc_clnt, 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_bufcreate, clntudp_create -
library routines for client ONC remote procedure calls
#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 );
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 multithreaded 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 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 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 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. 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 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 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 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 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()
Note
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.
Note
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.
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 standard 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 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. 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 procedures that take large arguments
or return huge results.
rpc_misc(3), rpc_svc(3), rpc_xdr(3), xdr(3)
Remote Procedure Calls: Protocol Specifications -- RFC
1050
rpc_clnt(3)
[ Back ] |
