rpc_clnt_create(3N) UNIX System V 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:
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);
10/89 Page 1
rpc_clnt_create(3N) UNIX System V rpc_clnt_create(3N)
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 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);
Page 2 10/89
rpc_clnt_create(3N) UNIX System V rpc_clnt_create(3N)
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.
Note: 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 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
10/89 Page 3
rpc_clnt_create(3N) UNIX System V rpc_clnt_create(3N)
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 10/89