rpc_svc(3)rpc_svc(3)NAME
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
SYNOPSIS
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 );
DESCRIPTION
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 multi‐
threaded environment). Routines that are not thread safe are flagged as
such.
[Not Thread Safe] A macro that destroys the RPC service transport han‐
dle, xprt. Destruction usually involves deallocation of private data
structures, including xprt itself. Use of xprt is undefined after call‐
ing 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 imple‐
mentor 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 descrip‐
tors. 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 deter‐
mined 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 non-zero, a mapping
of the triple [prognum, versnum, protocol] to xprt->xp_port is estab‐
lished 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 proce‐
dure using svc_getreq() when one arrives. This procedure is usu‐
ally 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 rou‐
tine 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 usu‐
ally 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 dis‐
patch 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. Typi‐
cally, this descriptor is a connected socket for a stream proto‐
col 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 trans‐
port 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/IP-based RPC service
transport, to which it returns a pointer. The transport is asso‐
ciated 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/IP-
based 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 trans‐
port'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 proce‐
dures that take large arguments or return huge results.
SEE ALSOrpc-clnt(3), rpc-misc(3), rpc-xdr(3), xdr(3)
Remote Procedure Calls: Protocol Specification - RFC 1050
rpc_svc(3)
