rpc_rac(3RAC) Remote Asynchronous Calls Library Functions rpc_rac(3RAC)NAME
rpc_rac, rac_drop, rac_poll, rac_recv, rac_send - remote asynchronous
calls
SYNOPSIS
cc [ flag ... ] file ... -lrac -lnsl [ library ... ]
#include <rpc/rpc.h>
#include <rpc/rac.h>
void rac_drop(CLIENT *cl, void *h);
enum clnt_stat rac_poll(CLIENT *cl, void *h);
enum clnt_stat rac_recv(CLIENT *cl, void *h);
void *rac_send(CLIENT *cl, rpcproc_t proc, xdrproc_t xargs, void
*argsp, xdrproc_t xresults, void *resultsp, struct timeval timeout);
DESCRIPTION
The remote asynchronous calls (RAC) package is a special interface to
the RPC library that allows messages to be sent using the RPC protocol
without blocking during the time between when the message is sent and
the reply is received. To RPC servers, RAC messages are indistinguish‐
able from RPC messages.
A client establishes an RPC session in the usual way (see rpc_clnt_cre‐
ate(3NSL)). A RAC message is sent using rac_send(). This routine
returns immediately, allowing the client to conduct other processing.
When the client wants to determine whether the returned value from the
call has been received, rac_poll() is used. rac_recv() is used to col‐
lect the returned value; it can also be used to block while waiting for
the returned value to arrive. rac_drop() is used to inform the RPC
library that the client is no longer interested in the results of a
particular RAC message.
rac_drop()rac_drop() should be called when the user is no longer
interested in the result of a rac_send() currently in
progress. No message to the server is generated by
this call, but any subsequent reply received for this
handle will be silently dropped. It also frees any
space occupied by the asynchronous call handle h.
After a call to rac_drop() the handle referred to by h
is invalid. It may no longer be used in any asynchro‐
nous operation.
rac_poll()rac_poll() returns the status of the call currently in
progress on the <CLIENT, asynchronous handle> tuple
referred to by cl and h.
rac_poll() return values are:
RPC_SUCCESS A reply has been received and
is available for reading by
rac_recv().
RPC_INPROGRESS No reply has been received.
The call referred to by the
given handle has not yet timed
out.
RPC_TIMEDOUT No reply has been received.
The call referred to by the
given handle has exceeded the
maximum timeout value specified
in rac_send().
RPC_STALERACHANDLE Either the handle referred to
by h is invalid or no call is
currently in progress for the
given <CLIENT, asynchronous
handle> tuple.
RPC_CANTRECV Either the file descriptor
associated with the given
CLIENT handle is bad, or an
error occurred while attempting
to receive a packet.
RPC_SYSTEMERROR Space could not be allocated to
receive a packet.
On unreliable transports, a call to rac_poll() will
trigger a retransmission when necessary (that is, if a
rac_send() is in progress, no reply has been received,
the per-call timeout has expired, and the total timeout
has not yet expired).
The return value for rac_poll() is independent of the
RPC return value in the reply packet. Although a combi‐
nation of clnt_control()'s CLGET_FD request and poll(2)
may be used to extract the proper file descriptor and
poll for packets, rac_poll() is still useful since it
will determine whether a reply is available for a spe‐
cific <CLIENT, asynchronous handle> tuple.
rac_recv()rac_recv() retrieves the results of a previous asyn‐
chronous RPC call, placing them in the buffer indicated
in the rac_send() call and using the XDR decode func‐
tion supplied there. It depends on the application to
have ensured that a reply is present (using
rac_poll()). If rac_recv() is called before a reply has
been received, it will block awaiting a reply.
All errors normally returned by the RPC client call
functions may be returned here. In addition:
RPC_STALERACHANDLE Either the handle referred to
by h is invalid or no call is
currently in progress for the
given <CLIENT, asynchronous
handle> tuple.
Additionally, if a packet is
present and its status is not
RPC_SUCCESS, it is possible
that the client credentials
need refreshing. In this case,
RPC_AUTHERROR is returned and
the client should attempt to
resend the call.
When a reply has been received, rac_recv() will invoke
the XDR decode procedure specified in the rac_send()
call. After a call to rac_recv(), the handle referred
to by h is invalid. It may no longer be used in any
asynchronous operation.
rac_send()rac_send() initiates (sends to the server) an RPC call
to the specified procedure.
It does not await a reply from the server. argsp is
the address of the procedure's arguments, resultsp is
the address in which to place the results, xargs and
xresults are XDR functions used to encode and decode
respectively. Note: resultsp must be a valid pointer
when rac_recv() is called. timeout should contain the
total amount of time the application is willing to wait
for a reply.
Upon success, an opaque handle, known as the asynchro‐
nous handle, is returned. This handle is to be used in
subsequent asynchronous calls to poll for the status of
the call (rac_poll()), receive the returned results of
the call (rac_recv()), or cancel the call (rac_drop()).
On failure, (void *) 0 is returned.
In case of failure, the application may retrieve the
RPC failure code by calling clnt_geterr() immediately
after a rac_send() failure (see rpc(3NSL)). Possible
errors include both transient problems (such as trans‐
port failures) and permanent ones (such as XDR encoding
failures).
Multiple rac_sends on the same client handle are per‐
mitted, but may introduce unpredictable perturbations
to the current timeout and retry model used by the RPC
library.
The interface imposes a limit on the amount of time a
call may be in progress before it is considered to have
failed. This method was chosen over limitations on the
number of retries because of a desire for transport
independence.
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
┌─────────────────────────────┬─────────────────────────────┐
│ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
├─────────────────────────────┼─────────────────────────────┤
│MT-Level │Unsafe │
└─────────────────────────────┴─────────────────────────────┘
SEE ALSOpoll(2), rpc(3NSL), rpc_clnt_create(3NSL), rpc_clnt_calls(3NSL),
xdr(3NSL), attributes(5)WARNINGS
The RAC interface is not the recommended interface for having multiple
RPC requests outstanding. The preferred method of accomplishing this in
the Solaris environment is to use synchronous RPC calls with threads.
The RAC interface is provided as a service to developers interested in
porting RPC applications to Solaris 2.0. Use of this interface will
degrade the performance of normal synchronous RPC calls (see
rpc_clnt_calls(3NSL)). For these reasons, use of this interface is dis‐
paraged.
The library librac must be linked before libnsl to use RAC. If the
libraries are not linked in the correct order, then the results are
indeterminate.
NOTES
These interfaces are unsafe in multithreaded applications. Unsafe
interfaces should be called only from the main thread.
SunOS 5.10 21 Jul 1998 rpc_rac(3RAC)
