rpc_clnt_create(3N) 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 procedure calls
on other machines across the network. First a CLIENT handle is created
and then the client calls a procedure to send a data packet to the
server. Upon receipt of the packet, the server calls a dispatch rou-
tine to perform the requested service, and then sends back a reply.
If you use one of the RPC functions, you must link the libnsl library
at compilation (cc -lnsl).
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 information. For both connectionless and
connection-oriented transports, the supported values of req and
their argument types and what they do are:
CLSETTIMEOUT struct timeval
set total timeout
CLGETTIMEOUT struct timeval
get 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 netbuf
get servers address
CLSETFDCLOSE int
close the file descriptor when destroying the client handle
[see clntdestroy]
CLSETFDNCLOSE int
do not close the file descriptor when destroying the client
handle
Page 1 Reliant UNIX 5.44 Printed 11/98
rpc_clnt_create(3N) rpc_clnt_create(3N)
The following operations are valid for connectionless transports
only:
CLSETRETRYTIMEOUT struct timeval
set the retry timeout
CLGETRETRYTIMEOUT struct timeval
get 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 indicates the class of transport pro-
tocol 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 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. Destruc-
tion 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 program 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 specified 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
Page 2 Reliant UNIX 5.44 Printed 11/98
rpc_clnt_create(3N) rpc_clnt_create(3N)
receive buffers with 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' 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 interference.
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, const ulong 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
of 0 choose suitable defaults. Depending upon the type of the
Page 3 Reliant UNIX 5.44 Printed 11/98
rpc_clnt_create(3N) rpc_clnt_create(3N)
transport (connection-oriented or connectionless),
clnttlicreate calls appropriate client creation 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 transport speci-
fied 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 program prognum
and version versnum; the client uses a connection-oriented trans-
port. 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 parame-
ters sendsz and recvsz; values of 0 choose suitable 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 service for this information.
SEE ALSO
rpcbind(1M), rpc(3N), rpcclntauth(3N), rpcclntcalls(3N).
Page 4 Reliant UNIX 5.44 Printed 11/98