RPC_CLNT_CREATE(3) | Library Functions Manual | RPC_CLNT_CREATE(3) |
rpc_clnt_create
, clnt_control
,
clnt_create
, clnt_create_vers
,
clnt_destroy
, clnt_dg_create
,
clnt_pcreateerror
,
clnt_raw_create
,
clnt_spcreateerror
,
clnt_tli_create
,
clnt_tp_create
,
clnt_vc_create
, rpc_createerr
—
#include <rpc/rpc.h>
bool_t
clnt_control
(CLIENT
*clnt, const u_int
req, char
*info);
CLIENT *
clnt_create
(const
char * host, const
rpcprog_t prognum, const
rpcvers_t versnum, const
char *nettype);
CLIENT *
clnt_create_vers
(const
char * host, const
rpcprog_t prognum,
rpcvers_t *vers_outp,
const rpcvers_t vers_low,
const rpcvers_t
vers_high, char
*nettype);
void
clnt_destroy
(CLIENT
* clnt);
CLIENT *
clnt_dg_create
(const
int fildes, const struct
netbuf *svcaddr, const
rpcprog_t prognum, const
rpcvers_t versnum, const
u_int sendsz, const u_int
recvsz);
void
clnt_pcreateerror
(const
char *s);
char *
clnt_spcreateerror
(const
char *s);
CLIENT *
clnt_raw_create
(const
rpcprog_t prognum, const
rpcvers_t versnum);
CLIENT *
clnt_tli_create
(const
int fildes, const struct
netconfig *netconf, const
struct netbuf *svcaddr,
const rpcprog_t prognum,
const rpcvers_t versnum,
const u_int sendsz,
const u_int recvsz);
CLIENT *
clnt_tp_create
(const
char * host, const
rpcprog_t prognum, const
rpcvers_t versnum, const
struct netconfig *netconf);
CLIENT *
clnt_vc_create
(const
int fildes, const struct
netbuf *svcaddr, const
rpcprog_t prognum, const
rpcvers_t versnum, const
u_int sendsz, const u_int
recvsz);
CLIENT
handle is
created and then the client calls a procedure to send a request to the server.
On receipt of the request, the server calls a dispatch routine to perform the
requested service, and then sends a reply.
clnt_control
()CLSET_TIMEOUT |
struct timeval * | set total timeout |
CLGET_TIMEOUT |
struct timeval * | get total timeout |
Note: if you set the timeout using
clnt_control
(), the timeout argument passed by
clnt_call
() is ignored in all subsequent
calls.
Note: If you set the timeout value to 0
clnt_control
() immediately returns an error
(RPC_TIMEDOUT
). Set the timeout parameter to 0
for batching calls.
CLGET_SVC_ADDR |
struct netbuf * | get servers address |
CLGET_FD |
int * | get fd from handle |
CLSET_FD_CLOSE |
void | close fd on destroy |
CLSET_FD_NCLOSE |
void | don't close fd on destroy |
CLGET_VERS |
unsigned long * | get RPC program version |
CLSET_VERS |
unsigned long * | set RPC program version |
CLGET_XID |
unsigned long * | get XID of previous call |
CLSET_XID |
unsigned long * | set XID of next call |
The following operations are valid for connectionless transports 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 RPC waits for the server to
reply before retransmitting the request.
clnt_control
() returns
TRUE
on success and
FALSE
on failure.
clnt_create
()NETPATH
environment variable or in top to bottom
order in the netconfig database. clnt_create
()
tries all the transports of the nettype class
available from the NETPATH
environment variable
and the netconfig database, and chooses the first successful one. A
default timeout is set and can be modified using
clnt_control
(). This routine returns
NULL
if it fails. The
clnt_pcreateerror
() routine can be used to print
the reason for failure.
Note: clnt_create
() returns a valid
client handle even if the particular version number supplied to
clnt_create
() is not registered with the
rpcbind(8) service. This
mismatch will be discovered by a clnt_call
()
later (see
rpc_clnt_calls(3)).
clnt_create_vers
()clnt_create
() but which also checks for the
version availability. host identifies the name of
the remote host where the server is located. nettype
indicates the class transport protocols to be used. 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
. A default timeout is set and can be modified
using clnt_control
(). This routine returns
NULL
if it fails. The
clnt_pcreateerror
() routine can be used to print
the reason for failure. Note: clnt_create
()
returns a valid client handle even if the particular version number
supplied to clnt_create
() is not registered with
the rpcbind(8) service.
This mismatch will be discovered by a clnt_call
()
later (see
rpc_clnt_calls(3)).
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.clnt_destroy
()clnt_destroy
(). If the RPC
library opened the associated file descriptor, or
CLSET_FD_CLOSE
was set using
clnt_control
(), the file descriptor will be
closed. The caller should call
auth_destroy
(clnt->cl_auth)
(before calling clnt_destroy
()) to destroy the
associated AUTH
structure (see
rpc_clnt_auth(3)).clnt_dg_create
()clnt_call
() (see
clnt_call
() in
rpc_clnt_calls(3)).
The retry time out and the total time out periods can be changed using
clnt_control
(). The user may set the size of the
send and receive buffers with the parameters sendsz
and recvsz; values of 0 choose suitable defaults.
This routine returns NULL
if it fails.clnt_pcreateerror
()clnt_spcreateerror
()clnt_pcreateerror
(), except that it returns a
string instead of printing to the standard error. A newline is not
appended to the message in this case. Warning: returns a pointer to a
buffer that is overwritten on each call.clnt_raw_create
()svc_raw_create
() in
rpc_svc_create(3)).
This allows simulation of RPC and measurement of RPC overheads, such as
round trip times, without any kernel or networking interference. This
routine returns NULL
if it fails.
clnt_raw_create
() should be called after
svc_raw_create
().clnt_tli_create
()NULL
and it is
connection-oriented, it is assumed that the file descriptor is connected.
For connectionless transports, if svcaddr is
NULL
, RPC_UNKNOWNADDR
error is set. fildes is a file descriptor which may
be open, bound and connected. If it is RPC_ANYFD
,
it opens a file descriptor on the transport specified by
netconf. If fildes is
RPC_ANYFD
and netconf is
NULL
, a RPC_UNKNOWNPROTO
error is set. If fildes is unbound, then it will
attempt to bind the descriptor. The user may specify the size of the
buffers with the parameters sendsz and
recvsz; values of 0 choose suitable defaults.
Depending upon the type of the transport (connection-oriented or
connectionless), clnt_tli_create
() calls
appropriate client creation routines. This routine returns
NULL
if it fails. The
clnt_pcreateerror
() routine can be used to print
the reason for failure. The remote rpcbind service (see
rpcbind(8)) is not
consulted for the address of the remote service.clnt_tp_create
()clnt_create
() except
clnt_tp_create
() tries only one transport
specified through netconf.
clnt_tp_create
() creates a client handle for the
program prognum, the version
versnum, and for the transport specified by
netconf. Default options are set, which can be
changed using clnt_control
() calls. The remote
rpcbind service on the host host is consulted for
the address of the remote service. This routine returns
NULL
if it fails. The
clnt_pcreateerror
() routine can be used to print
the reason for failure.clnt_vc_create
()NULL
if it fails. The address
svcaddr should not be NULL
and should point to the actual address of the remote program.
clnt_vc_create
() does not consult the remote
rpcbind service for this information.clnt_pcreateerror
() to print the reason for the
failure.May 23, 2009 | NetBSD 9.0 |