rpc_clnt_create(3N) NETWORK FUNCTIONS rpc_clnt_create(3N)
NAME
rpcclntcreate: clntcontrol, clntcreate, clntdestroy,
clntdgcreate, clntpcreateerror, clntrawcreate,
clntspcreateerror, clnttlicreate, clnttpcreate,
clntvccreate - library routines for dealing with creation
and manipulation of CLIENT handles
DESCRIPTION
RPC library routines allow C language programs to make pro-
cedure calls on other machines across the network. First a
CLIENT handle is created and then the client calls a pro-
cedure 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.
Routines
See rpc(3N) for the definition of the CLIENT data structure.
#include <rpc/rpc.h>
boolt
clntcontrol(CLIENT *clnt, const uint req, char *info);
A function macro used to change or retrieve various
information about a client object. req indicates the
type of operation, and info is a pointer to the infor-
mation. For both connectionless and connection-
oriented transports, the supported values of req and
their argument types and what they do are:
CLSETTIMEOUT struct timevalset total timeout
CLGETTIMEOUT struct timevalget total timeout
Note: if you set the timeout using clntcontrol, the
timeout parameter passed to clntcall will be ignored
in all future calls.
CLGETFD int get the associated file descriptor
CLGETSVCADDR struct netbufget servers address
CLSETFDCLOSE intclose the file descriptor when
destroying the client handle
[see clntdestroy]
CLSETFDNCLOSE intdo not close the file
descriptor when destroying
the client handle
The following operations are valid for connectionless
transports only:
CLSETRETRYTIMEOUT struct timevalset the retry timeout
Last change: 1
rpc_clnt_create(3N) NETWORK FUNCTIONS rpc_clnt_create(3N)
CLGETRETRYTIMEOUT struct timevalget the retry timeout
The retry timeout is the time that RPC waits for the
server to reply before retransmitting the request.
clntcontrol returns 1 on success and 0 on failure.
CLIENT *
clntcreate(const char *host, const ulong prognum,
const ulong versnum, const char *nettype);
Generic client creation routine for program prognum and
version versnum. host identifies the name of the
remote host where the server is located. nettype indi-
cates the class of transport protocol to use. The
transports are tried in left to right order in NETPATH
variable or in top to down order in the netconfig data-
base.
clntcreate tries all the transports of the nettype
class available from the NETPATH environment variable
and the the netconfig database, and chooses the first
successful one. Default timeouts are set, but can be
modified using clntcontrol.
void
clntdestroy(CLIENT *clnt);
A function 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 clntdestroy. If the RPC
library opened the associated file descriptor, or
CLSETFDCLOSE was set using clntcontrol, it will be
closed.
CLIENT *
clntdgcreate(const int fd, const struct netbuf *svcaddr,
const ulong prognum, const ulong versnum,
const uint sendsz, const uint recvsz);
This routine creates an RPC client for the remote pro-
gram prognum and version versnum; the client uses a
connectionless transport. The remote program is
located at address svcaddr. The parameter fd is an
open and bound file descriptor. This routine will
resend the call message in intervals of 15 seconds
until a response is received or until the call times
out. The total time for the call to time out is speci-
fied by clntcall [see clntcall in
rpcclntcalls(3N)]. This routine returns NULL if it
fails. The retry time out and the total time out
periods can be changed using clntcontrol. The user
may set the size of the send and receive buffers with
Last change: 2
rpc_clnt_create(3N) NETWORK FUNCTIONS rpc_clnt_create(3N)
the parameters sendsz and recvsz; values of 0 choose
suitable defaults.
void
clntpcreateerror(const char *s);
Print a message to standard error indicating why a
client RPC handle could not be created. The message is
prepended with the string s and a colon, and appended
with a newline.
CLIENT *
clntrawcreate(const ulong prognum, const ulong versnum);
This routine creates a toy RPC client for the remote
program prognum and version versnum. The transport
used to pass messages to the service is a buffer within
the process's address space, so the corresponding RPC
server should live in the same address space; [see
svcrawcreate in rpcclntcalls(3N)]. This allows
simulation of RPC and acquisition of RPC overheads,
such as round trip times, without any kernel interfer-
ence. This routine returns NULL if it fails.
clntrawcreate should be called after svcrawcreate.
char *
clntspcreateerror(const char *s);
Like clntpcreateerror, 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 static data that is
overwritten on each call.
CLIENT *
clnttlicreate(const int fd, const struct netconfig *netconf,
const struct netbuf *svcaddr, u constlong prognum,
const ulong versnum, const uint sendsz,
const uint recvsz);
This routine creates an RPC client handle for the
remote program prognum and version versnum. The remote
program is located at address svcaddr. If svcaddr is
NULL and it is connection-oriented, it is assumed that
the file descriptor is connected. For connectionless
transports, if svcaddr is NULL, RPCUNKNOWNADDR error
is set. fd is a file descriptor which may be open,
bound and connected. If it is RPCANYFD, it opens a
file descriptor on the transport specified by netconf.
If netconf is NULL, a RPCUNKNOWNPROTO error is set.
If fd 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
Last change: 3
rpc_clnt_create(3N) NETWORK FUNCTIONS rpc_clnt_create(3N)
of 0 choose suitable defaults. Depending upon the type
of the transport (connection-oriented or connection-
less), clnttlicreate calls appropriate client crea-
tion routines. This routine returns NULL if it fails.
The clntpcreaterror routine can be used to print the
reason for failure. The remote rpcbind service [see
rpcbind(1M)] will not be consulted for the address of
the remote service.
CLIENT *
clnttpcreate(const char *host, const ulong prognum,
const ulong versnum, const struct netconfig *netconf);
clnttpcreate creates a client handle for the tran-
sport specified by netconf. Default options are set,
which can be changed using clntcontrol 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 clntpcreaterror routine
can be used to print the reason for failure.
CLIENT *
clntvccreate(const int fd, const struct netbuf *svcaddr,
const ulong prognum, const ulong versnum,
const uint sendsz, const uint recvsz);
This routine creates an RPC client for the remote pro-
gram prognum and version versnum; the client uses a
connection-oriented transport. The remote program is
located at address svcaddr. The parameter fd is an
open and bound file descriptor. The user may specify
the size of the send and receive buffers with the
parameters sendsz and recvsz; values of 0 choose suit-
able defaults. This routine returns NULL if it fails.
The address svcaddr should not be NULL and should point
to the actual address of the remote program.
clntvccreate will not consult the remote rpcbind ser-
vice for this information.
SEE ALSO
rpcbind(1M), rpc(3N), rpcclntauth(3N), rpcclntcalls(3N).
Last change: 4