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 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 information. 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:
7/91 Page 1
rpc_clnt_create(3N) rpc_clnt_create(3N)
CLSETRETRYTIMEOUT struct timevalset the retry timeout
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 indicates 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 database.
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 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
Page 2 7/91
rpc_clnt_create(3N) rpc_clnt_create(3N)
the size of the send and 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'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 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, 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 of 0 choose suitable defaults. Depending
7/91 Page 3
rpc_clnt_create(3N) rpc_clnt_create(3N)
upon the type of the 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
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 program
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 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 7/91