 |
Index for
Section 3 |
|
 |
Alphabetical
listing for R |
|
 |
Bottom of
page |
|
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,
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_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 multithreaded
environment). Routines that are not thread safe are flagged as such.
callrpc() 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.
enum clnt_stat clnt_broadcast()
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:
eachresult()
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.
enum clnt_stat clnt_call()
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.
clnt_destroy()
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.
CLIENT * clnt_create(
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.
bool_t clnt_control()
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.
clnt_freeres()
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.
void clnt_geterr()
A macro that copies the error structure out of the client handle
to the structure at address errp.
void clnt_pcreateerror()
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.
void clnt_perrno()
Prints a message to standard error corresponding to the condition
indicated by stat. Used after callrpc().
clnt_perror()
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().
char * clnt_spcreateerror(
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.
char * clnt_sperrno()
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.
char *clnt_sperror()
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.
CLIENT *clntraw_create()
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.
CLIENT * clnttcp_create()
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.
CLIENT * clntudp_create()
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
|
Index for
Section 3 |
|
|
Alphabetical
listing for R |
|
 |
Top of
page |
|