 |
Index for
Section 3 |
|
 |
Alphabetical
listing for R |
|
 |
Bottom of
page |
|
rpc_clnt(3)
NAME
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
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 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.
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_bufcreate()
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.
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.
SEE ALSO
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 |
|