RPCCLNTCR(3N-SVR4)RISC/os Reference Manual RPCCLNTCR(3N-SVR4)
NAME
rpc_clnt_create: clnt_control, clnt_create, clnt_destroy,
clnt_dg_create, clnt_pcreateerror, clnt_raw_create,
clnt_spcreateerror, clnt_tli_create, clnt_tp_create,
clnt_vc_create - 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:
CLSET_TIMEOUT struct timevalset total timeout
CLGET_TIMEOUT struct timevalget total timeout
Note: if you set the timeout using clntcontrol, the
timeout parameter passed to clnt_call will be ignored
in all future calls.
CLGET_FD int get the associated file descriptor
CLGET_SVC_ADDR struct netbufget servers address
CLSET_FD_CLOSE intclose the file descriptor when
destroying the client handle
[see clntdestroy]
CLSET_FD_NCLOSE intdo not close the file
descriptor when destroying
the client handle
The following operations are valid for connectionless
transports only:
CLSET_RETRY_TIMEOUT struct timevalset the retry timeout
CLGET_RETRY_TIMEOUT struct timevalget the retry timeout
The retry timeout is the time that RPC waits for the
server to reply before retransmitting the request.
Printed 11/19/92 Page 1
RPCCLNTCR(3N-SVR4)RISC/os Reference Manual RPCCLNTCR(3N-SVR4)
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
CLSET_FD_CLOSE 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 clnt_call in
rpc_clnt_calls(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.
Page 2 Printed 11/19/92
RPCCLNTCR(3N-SVR4)RISC/os Reference Manual RPCCLNTCR(3N-SVR4)
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
svc_raw_create in rpc_clnt_calls(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 svc_raw_create.
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, RPC_UNKNOWNADDR error
is set. fd 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 netconf is NULL, a RPC_UNKNOWNPROTO 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
Printed 11/19/92 Page 3
RPCCLNTCR(3N-SVR4)RISC/os Reference Manual RPCCLNTCR(3N-SVR4)
of the transport (connection-oriented or connection-
less), clnttlicreate calls appropriate client crea-
tion routines. This routine returns The NULL
clntpcreaterror routine can be used to print the rea-
son 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), rpc_clnt_auth(3N), rpc_clnt_calls(3N).
Page 4 Printed 11/19/92