svc_destroy, svc_fdset, svc_freeargs, svc_getargs,
svc_getcaller, svc_getreq, svc_getreqset, svc_register,
svc_run, svc_sendreply, svc_unregister, svcerr_auth,
svcerr_decode, svcerr_noproc, svcerr_noprog,
svcerr_progvers, svcerr_systemerr, svcerr_weakauth,
svcfd_create, svcraw_create, svctcp_create, svcudp_create
- library routines for ONC server remote procedure calls
svc_destroy(
SVCXPRT *xprt ); fd_set svc_fdset; int svc_fds;
svc_freeargs(
SVCXPRT *xprt,
xdrproc_t inproc,
char *in ); svc_getargs(
SVCXPRT *xprt,
xdrproc_t inproc,
char *in ); struct sockaddr_in *svc_getcaller(
SVCXPRT *xprt ); svc_getreq(
int rdfds ); svc_getreqset(
fd_set *rdfds ); svc_register(
SVCXPRT *xprt,
u_int prognum,
u_int versnum,
void (*dispatch) (),
int protocol ); svc_run(
void ); svc_sendreply(
SVCXPRT *xprt,
xdrproc_t outproc,
char *out ); void svc_unregister
u_int prognum,
u_int versnum ); void svcerr_auth(
SVCXPRT *xprt,
num auth_stat why ); void svcerr_decode(
SVCXPRT *xprt ); void svcerr_noproc(
SVCXPRT *xprt ); void svcerr_noprog(
SVCXPRT *xprt ); void svcerr_progvers(
SVCXPRT *xprt ); void svcerr_systemerr(
SVCXPRT *xprt ); void svcerr_weakauth(
SVCXPRT *xprt ); voidsvcfd_create(
int fd,
u_int sendsize,
u_int recvsize ); SVCXPRT * svcraw_create(
void ); SVCXPRT * svctcp_create(
int sock,
u_int send_buf_size,
u_int recv_buf_size ); SVCXPRT * svcudp_create(
int sock );
These routines allow C programs to make procedure calls on
other machines across the network. First, 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. Finally, the procedure call returns to the client.
Unless otherwise indicated, the routines described in this
reference page are thread safe (that is, they can be used
safely in a multithreaded environment). Routines that are
not thread safe are flagged as such.
[Not Thread Safe] A macro that destroys the RPC service
transport handle, xprt. Destruction usually involves deallocation
of private data structures, including xprt
itself. Use of xprt is undefined after calling this routine.
A global variable that reflects the RPC service
side's read file descriptor bit mask; it is suitable as a
parameter to the select system call. This is only of
interest if a service implementor does not call svc_run(),
but rather does his own asynchronous event processing.
This variable is read-only (do not pass its address to
select), yet it may change after calls to svc_getreqset()
or any creation routines. Similar to svc_fdset(), but
limited to 32 descriptors. This interface is obsoleted by
svc_fdset(). [Not Thread Safe] A macro that frees any
data allocated by the RPC/XDR system when it decoded the
arguments to a service procedure using svc_getargs(). This
routine returns 1 if the results were successfully freed,
and zero (0) otherwise. [Not Thread Safe] A macro that
decodes the arguments of an RPC request associated with
the RPC service transport handle, xprt. The in parameter
is the address where the arguments will be placed; inproc
is the XDR routine used to decode the arguments. This routine
returns one (1) if decoding succeeds, and zero (0)
otherwise. [Not Thread Safe] The approved way of getting
the network address of the caller of a procedure associated
with the RPC service transport handle, xprt. [Not
Thread Safe] Similar to svc_getreqset(), but limited to
32 descriptors. This interface is obsoleted by svc_getreqset().
[Not Thread Safe] This routine is only of interest
if a service implementor does not call svc_run(), but
instead implements custom asynchronous event processing.
It is called when the select system call has determined
that an RPC request has arrived on some RPC socket(s);
rdfds is the resultant read file descriptor bit mask. The
routine returns when all sockets associated with the value
of rdfds have been serviced. [Not Thread Safe] Associates
prognum and versnum with the service dispatch procedure,
dispatch. If protocol is zero, the service is not
registered with the portmap service. If protocol is nonzero,
a mapping of the triple [prognum, versnum, protocol]
to xprt->xp_port is established with the local portmap
service (generally protocol is zero, IPPROTO_UDP or
IPPROTO_TCP). The dispatch procedure has the following
form:
dispatch(
struct svc_req *request,
SVCXPRT *xprt);
The svc_register() routine returns one (1) if it
succeeds, and zero (0) otherwise. [Not Thread
Safe] This routine waits for RPC requests to
arrive, and calls the appropriate service procedure
using svc_getreq() when one arrives. This procedure
is usually waiting for a select() system call to
return. [Not Thread Safe] Called by an RPC service's
dispatch routine to send the results of a
remote procedure call. The xprt parameter is the
request's associated transport handle; outproc is
the XDR routine which is used to encode the
results; and out is the address of the results.
This routine returns one (1) if it succeeds, zero
(0) otherwise. [Not Thread Safe] Removes all
mapping of the double [prognum,versnum] to dispatch
routines, and of the triple [prognum,versnum,*] to
port number. [Not Thread Safe] Called by a service
dispatch routine that refuses to perform a
remote procedure call due to an authentication
error. [Not Thread Safe] Called by a service dispatch
routine that cannot successfully decode its
parameters. See also svc_getargs(). [Not Thread
Safe] Called by a service dispatch routine that
does not implement the procedure number that the
caller requests. [Not Thread Safe] Called when
the desired program is not registered with the RPC
package. Service implementors usually do not need
this routine. [Not Thread Safe] Called when the
desired version of a program is not registered with
the RPC package. Service implementors usually do
not need this routine. [Not Thread Safe] Called
by a service dispatch routine when it detects a
system error not covered by any particular protocol.
For example, if a service can no longer allocate
storage, it may call this routine. [Not
Thread Safe] Called by a service dispatch routine
that refuses to perform a remote procedure call due
to insufficient (but correct) authentication parameters.
The routine calls
svcerr_auth(xprt,AUTH_TOOWEAK). [Not Thread
Safe] Creates a service on top of any open
descriptor. Typically, this descriptor is a connected
socket for a stream protocol such as TCP.
The sendsize and recvsize parameters indicate sizes
for the send and receive buffers. If they are zero
(0), a reasonable default is chosen. [Not Thread
Safe] Creates a toy RPC service transport, to
which it returns a pointer. The transport is really
a buffer within the process's address space, so the
corresponding RPC client should live in the same
address space; see clntraw_create(). This routine
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. [Not Thread Safe] Creates a TCP/IPbased
RPC service transport, to which it returns a
pointer. The transport is associated with the sock
socket, which may be RPC_ANYSOCK, in which case a
new socket is created. If the socket is not bound
to a local TCP port, this routine binds it to an
arbitrary port. Upon completion, xprt->xp_sock is
the transport's socket descriptor, and
xprt->xp_port is the transport's port number. This
routine returns NULL if it fails. Since TCP-based
RPC uses buffered I/O , users may specify the size
of buffers; values of zero (0) choose suitable
defaults. [Not Thread Safe] Creates a UDP/IPbased
RPC service transport, to which it returns a
pointer. The transport is associated with the sock
socket, which may be RPC_ANYSOCK, in which case a
new socket is created. If the socket is not bound
to a local UDP port, then this routine binds it to
an arbitrary port. Upon completion, xprt->xp_sock
is the transport's socket descriptor, and
xprt->xp_port is the transport's port number. This
routine returns NULL if it fails.
Warning: Since UDP-based RPC messages can only hold
up to 8 Kbytes of encoded data, this transport cannot
be used for procedures that take large
arguments or return huge results.
rpc-clnt(3), rpc-misc(3), rpc-xdr(3), xdr(3)
Remote Procedure Calls: Protocol Specification - RFC 1050
rpc_svc(3)
[ Back ] |
