|
|
|
RPC routines allow C programs to make procedure calls on other machines across the network. First, the client calls a procedure to send a request to the server. Upon receipt of the request, 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.
The CLIENT data structure is defined in the RPC/XDR Library Definition of the [a manual with the abbreviation NETP].
#include <rpc/rpc.h>
bool_t clnt_control(clnt, request, info) CLIENT *clnt; int request; char *info;
Change or retrieve various information about a client object. request indicates the type of operation, and info is a pointer to the information. For both UDP and TCP, the supported values of request and their argument types and what they do are:
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_NCLOSE void leave socket open on clnt_destroy()
Note: If you set the timeout using clnt_control(), the timeout parameter passed to clnt_call() (see rpc_clnt_calls.3n will be ignored in all future calls.
CLGET_SERVER_ADDR struct sockaddr_in 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.
This routine returns
TRUE
on success, and
FALSE
on failure.
CLIENT * clnt_create(host, prognum, versnum, protocol) char *host; u_long prognum, versnum; char *protocol;
Generic client creation routine for program
prognum
and version
versnum.
host
identifies the name of the remote host where the server
is located.
protocol
indicates which kind of transport protocol to use. The
currently supported values for this field are ``udp''
and ``tcp''.
Default timeouts are set, but they can be modified using
clnt_control().
If successful it returns a client handle, otherwise it
returns
NULL.
Warning: Using UDP has its shortcomings. Since UDP-based RPC messages can only hold up to 8 Kbytes of encoded data, this transport cannot be used for procedures that take arguments or return results larger than 8 Kbytes. Use TCP instead.
Note:
If the requested version number
versnum
is not registered with the
portmap.8c
service on
host,
but at least a version number for the
given program number is registered,
clnt_create()
returns a handle.
The version mismatch will be discovered by a
clnt_call()
later
(see
rpc_clnt_calls.3n
CLIENT * clnt_create_vers(host, prognum, vers_outp, vers_low, vers_high, protocol) char *host; u_long prognum; u_long *vers_outp; u_long vers_low, vers_high; char *protocol;
This is a generic client creation routine which also checks for the version
available.
host
identifies the name of the remote host where the server
is located.
protocol
indicates which kind of transport protocol to use. The
currently supported values for this field are ``udp''
and ``tcp''.
If the routine is successful it returns a client handle created for
the highest version between
vers_low
and
vers_high
that is supported by the server.
vers_outp
is set to this value.
That is, after a successful return
vers_low
<=
*vers_outp
<=
vers_high.
If no version between
vers_low
and
vers_high
is supported by the server then the routine fails and returns
NULL.
Default timeouts are set, but can be modified using
clnt_control().
Note:
clnt_create()
returns a valid client handle even
if the particular version number supplied to
clnt_create()
is not
registered with the portmap service.
This mismatch will be discovered by a
clnt_call()
later
(see
rpc_clnt_calls.3n
However,
clnt_create_vers()
does this for you and returns a valid handle
only if a version within
the range supplied is supported by the server.
void clnt_destroy(clnt) CLIENT *clnt;
Destroy 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, or
CLSET_FD_CLOSE
was set using
clnt_control().
clnt_destroy()
closes the socket.
void clnt_pcreateerror(str) char *str;
Print a message to the standard error indicating
why a client
handle could not be created.
The message is prepended with string
s
and a colon.
Used when routines such as
clnt_create(),
clntraw_create(),
clnttcp_create(),
or
clntudp_create()
fails.
CLIENT * clntraw_create(prognum, versnum) u_long prognum, versnum;
Create an
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; also see
svcraw_create()
(see
rpc_svc_create.3n
This allows simulation of
RPC
and getting
RPC
overheads, such as round trip times, without any
kernel interference.
If successful it returns a client handle, otherwise it
returns
NULL.
char * clnt_spcreateerror(str) char *str;
Like clnt_pcreateerror(), except that it returns a string instead of printing to the standard error. It, however, does not append the message with a NEWLINE.
Note:
clnt_spcreateerror()
returns a pointer to a static buffer that is overwritten
on each call.
CLIENT * clnttcp_create(addr, prognum, versnum, sockp, sendsz, recvsz) struct sockaddr_in *addr; u_long prognum, versnum; int *sockp; u_int sendsz, recvsz;
Create a client handle 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 port on which the remote
program is listening (the remote
portmap
service is consulted for this information).
The parameter
sockp
is a pointer to a socket; if it is
RPC_ANYSOCK,
then a new socket is opened and
sockp
is updated.
Since
TCP-based
RPC
uses buffered
I/O,
the user may specify the size of the send and receive buffers
with the parameters
sendsz
and
recvsz;
values of zero choose defaults.
If successful it returns a client handle, otherwise it
returns
NULL.
Warning:
If
addr->sin_port
is zero and the requested version number
versnum
is not registered with the remote portmap service,
it returns a handle if at least a version number for the
given program number is registered. The version mismatch
will be discovered by a
clnt_call()
later
(see
rpc_clnt_calls.3n
CLIENT * clntudp_bufcreate(addr, prognum, versnum, wait, sockp, sendsz, recvsz) struct sockaddr_in *addr; u_long prognum, versnum; struct timeval wait; int *sockp; u_int sendsz; u_int recvsz;
Create a client handle for the remote program prognum, on versnum; the client uses UDP/IP as the transport. The remote program is located at the Internet address addr. If addr->sin_port is zero, it is set to port on which the remote program is listening on (the remote portmap service is consulted for this information). The parameter sockp is a pointer to a socket; if it is RPC_ANYSOCK, then a new socket is opened and sockp is updated. 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() (see rpc_clnt_calls.3n If successful it returns a client handle, otherwise it returns NULL.
The user can specify the maximum packet size for sending and receiving
by using
sendsz
and
recvsz
arguments for
UDP-based
RPC
messages.
Warning:
If
addr->sin_port
is zero and the requested version number
versnum
is not registered with the remote portmap service,
it returns a handle if at least a version number for the
given program number is registered. The version mismatch
is discovered by a
clnt_call()
later
(see
rpc_clnt_calls.3n
CLIENT * clntudp_create(addr, prognum, versnum, wait, sockp) struct sockaddr_in *addr; u_long prognum, versnum; struct timeval wait; int *sockp;
Create a client handle for the remote program prognum, version versnum; the client uses UDP/IP as the transport. The remote program is located at the 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 pointer to a socket; if it is RPC_ANYSOCK, a new socket is opened and sockp is updated. 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() (see rpc_clnt_calls.3n If successful it returns a client handle, otherwise it returns NULL.
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 arguments or results larger than 8 Kbytes.
TCP
should be used instead.
Warning:
If
addr->sin_port
is zero and the requested version number
versnum
is not registered with the remote portmap service,
it returns a handle if any version number for the
given program number is registered.
The version mismatch is be discovered by a
clnt_call()
later
(see
rpc_clnt_calls.3n
struct rpc_createerr rpc_createerr;
A global variable whose value is set by any RPC client handle creation routine that fails. It is used by the routine clnt_pcreateerror() to print the reason for the failure.
|
|
|
Created by unroff & hp-tools. © somebody (See intro for details). All Rights Reserved. Last modified 11/5/97