Networking Services Library Functions rpcclntcalls(3NSL)
NAME
rpcclntcalls, clntcall, clntsend, clntfreeres,
clntgeterr, clntperrno, clntperror, clntsperrno,
clntsperror, rpcbroadcast, rpcbroadcastexp, rpccall -
library routines for client side calls
SYNOPSIS
#include
enum clntstat clntcall(CLIENT *clnt, const rpcproct procnum,
const xdrproct inproc, const caddrt in, const xdrproct outproc,
caddrt out, const struct timeval tout);
enum clntstat clntsend (CLIENT *clnt, const ulong
procnum, const xdrproct proc, const caddrt in);
boolt clntfreeres(CLIENT *clnt, const xdrproct outproc,
caddrt out);
void clntgeterr(const CLIENT *clnt, struct rpcerr *errp);
void clntperrno(const enum clntstat stat);
void clntperror(const CLIENT *clnt, const char *s);
char *clntsperrno(const enum clntstat stat);
char *clntsperror(const CLIENT *clnt, const char *s);
enum clntstat rpcbroadcast(const rpcprogt prognum,
const rpcverst versnum, const rpcproct procnum,
const xdrproctinproc, const caddrt in,
const xdrproct outproc, caddrt out,
const resultproct eachresult, const char *nettype);
enum clntstat rpcbroadcastexp(const rpcprogt prognum,
const rpcverst versnum,const rpcproct procnum,
const xdrproctxargs, caddrt argsp, const xdrproctxresults,
caddrt resultsp, const resultproct eachresult, const int inittime,
const int waittime, const char *nettype);
SunOS 5.11 Last change: 1 Aug 2001 1
Networking Services Library Functions rpcclntcalls(3NSL)
enum clntstat rpccall(const char *host, const rpcprogt prognum,
const rpcverst versnum, const rpcproct procnum, const xdrproct inproc,
const char *in, const xdrproct outproc, char *out, const char *nettype);
DESCRIPTION
RPC library routines allow C language programs to make pro-
cedure calls on other machines across the network. First,
the client calls a procedure to send a request to the
server. Upon receipt of the request, the server calls a
dispatch routine to perform the requested service and then
sends back a reply.
The clntcall(), rpccall(), and rpcbroadcast() routines
handle the client side of the procedure call. The remaining
routines deal with error handling.
Some of the routines take a CLIENT handle as one of the
parameters. A CLIENT handle can be created by an RPC crea-
tion routine such as clntcreate(). See
rpcclntcreate(3NSL).
These routines are safe for use in multithreaded applica-
tions. CLIENT handles can be shared between threads; how-
ever, in this implementation requests by different threads
are serialized. In other words, the first request will
receive its results before the second request is sent.
Routines
See rpc(3NSL) for the definition of the CLIENT data struc-
ture.
clntcall() A function macro that calls the
remote procedure procnum associated
with the client handle, clnt, which
is obtained with an RPC client crea-
tion routine such as clntcreate().
See rpcclntcreate(3NSL). The param-
eter inproc is the XDR function used
to encode the procedure's parameters,
and outproc is the XDR function used
to decode the procedure's results. in
is the address of the procedure's
argument(s), and out is the address
of where to place the result(s). tout
is the time allowed for results to be
returned, which is overridden by a
time-out set explicitly through
clntcontrol(). See
SunOS 5.11 Last change: 1 Aug 2001 2
Networking Services Library Functions rpcclntcalls(3NSL)
rpcclntcreate(3NSL).
If the remote call succeeds, the
status returned is RPCSUCES. Oth-
erwise, an appropriate status is
returned.
clntsend() Use the clntsend() function to call
a remote asynchronous function.
The clntsend() function calls the
remote function procnum() associated
with the client handle, clnt, which
is obtained with an RPC client crea-
tion routine such as clntcreate().
See rpcclntcreate(3NSL). The param-
eter proc is the XDR function used to
encode the procedure's parameters.
The parameter in is the address of
the procedure's argument(s).
By default, the blocking I/O mode is
used. See the clntcontrol(3NSL) man
page for more information on I/O
modes.
The clntsend() function does not
check if the program version number
supplied to clntcreate() is
registered with the rpcbind service.
Use clntcreatevers() instead of
clntcreate() to check on incorrect
version number registration.
clntcreatevers() will return a
valid handle to the client only if a
version within the range supplied to
clntcreatevers() is supported by
the server.
RPCSUCES is returned when a
request is successfully delivered to
the transport layer. This does not
mean that the request was received.
If an error is returned, use the
clntgetterr() routine to find the
failure status or the clntperrno()
routine to translate the failure
status into error messages.
SunOS 5.11 Last change: 1 Aug 2001 3
Networking Services Library Functions rpcclntcalls(3NSL)
clntfreeres() A function macro that frees any data
allocated by the RPC/XDR system when
it decoded the results of an RPC
call. The parameter out is the
address of the results, and outproc
is the XDR routine describing the
results. This routine returns 1 if
the results were successfully freed;
otherwise it returns 0.
clntgeterr() A function macro that copies the
error structure out of the client
handle to the structure at address
errp.
clntperrno() Prints a message to standard error
corresponding to the condition indi-
cated by stat. A newline is appended.
It is normally used after a procedure
call fails for a routine for which a
client handle is not needed, for
instance rpccall()
clntperror() Prints a message to the standard
error indicating why an RPC call
failed; clnt is the handle used to do
the call. The message is prepended
with string s and a colon. A newline
is appended. This routine is normally
used after a remote procedure call
fails for a routine that requires a
client handle, for instance
clntcall().
clntsperrno() Takes the same arguments as
clntperrno(), but instead of sending
a message to the standard error indi-
cating why an RPC call failed,
returns a pointer to a string that
contains the message.
clntsperrno() is normally used
instead of clntperrno() when the
program does not have a standard
error, as a program running as a
server quite likely does not.
clntsperrno() is also used if the
programmer does not want the message
SunOS 5.11 Last change: 1 Aug 2001 4
Networking Services Library Functions rpcclntcalls(3NSL)
to be output with printf(), or if a
message format different than that
supported by clntperrno() is to be
used. See printf(3C). Unlike
clntsperror() and
clntspcreaterror(), clntsperrno()
does not return a pointer to static
data. Therefore, the result is not
overwritten on each call. See
rpcclntcreate(3NSL).
clntsperror() Similar to clntperror(), except that
like clntsperrno(), it returns a
string instead of printing to stan-
dard error. However, clntsperror()
does not append a newline at the end
of the message.
clntsperror() returns a pointer to a
buffer that is overwritten on each
call. In multithreaded applications,
this buffer is implemented as
thread-specific data.
rpcbroadcast() Similar to rpccall(), except that
the call message is broadcast to all
the connectionless transports speci-
fied by nettype. If nettype is NUL,
it defaults to netpath. Each time it
receives a response, this routine
calls eachresult(), whose form is:
boolt eachresult(caddrt out, const struct netbuf *addr,
const struct netconfig *netconf);
where out is the same as out passed
to rpcbroadcast(), except that the
remote procedure's output is decoded
there. addr points to the address of
the machine that sent the results,
and netconf is the netconfig struc-
ture of the transport on which the
remote server responded. If
eachresult() returns 0,
rpcbroadcast() waits for more
replies; otherwise, it returns with
appropriate status.
The broadcast file descriptors are
limited in size to the maximum
SunOS 5.11 Last change: 1 Aug 2001 5
Networking Services Library Functions rpcclntcalls(3NSL)
transfer size of that transport. For
Ethernet, this value is 1500 bytes.
rpcbroadcast() uses AUTHSYS creden-
tials by default. See
rpcclntauth(3NSL).
rpcbroadcastexp() Similar to rpcbroadcast(), except
that the initial timeout, inittime
and the maximum timeout, waittime,
are specified in milliseconds.
inittime is the initial time that
rpcbroadcastexp() waits before
resending the request. After the
first resend, the retransmission
interval increases exponentially
until it exceeds waittime.
rpccall() Calls the remote procedure associated
with prognum, versnum, and procnum on
the machine, host. The parameter
inproc is used to encode the
procedure's parameters, and outproc
is used to decode the procedure's
results. in is the address of the
procedure's argument(s), and out is
the address of where to place the
result(s). nettype can be any of the
values listed on rpc(3NSL). This rou-
tine returns RPCSUCES if it
succeeds, or it returns an appropri-
ate status. Use the clntperrno()
routine to translate failure status
into error messages.
The rpccall() function uses the
first available transport belonging
to the class nettype on which it can
create a connection. You do not have
control of timeouts or authentication
using this routine.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
SunOS 5.11 Last change: 1 Aug 2001 6
Networking Services Library Functions rpcclntcalls(3NSL)
ATRIBUTE TYPE ATRIBUTE VALUE
Architecture All
Availability SUNWcsl (32-bit)
SUNWcslx (64-bit)
Interface Stability Evolving
MT-Level MT-Safe
SEE ALSO
printf(3C), rpc(3NSL), rpcclntauth(3NSL),
rpcclntcreate(3NSL), attributes(5)
SunOS 5.11 Last change: 1 Aug 2001 7
|
