rpc_svc(3) Library Functions Manual 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()
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()
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 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_getre-
qset(), but limited to 32 descriptors. This interface is obsoleted by svc_getreqset(). [Not Thread Safe] This routine is only of inter-
est 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 non-zero, a mapping of the triple [prognum, versnum, protocol] to xprt->xp_port is established with the local portmap ser-
vice (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] Cre-
ates 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/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 TCP port, this routine binds it to an arbitrary port. Upon completion, xprt->xp_sock is the trans-
port'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] Cre-
ates 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 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.
RELATED INFORMATION
rpc-clnt(3), rpc-misc(3), rpc-xdr(3), xdr(3)
Remote Procedure Calls: Protocol Specification - RFC 1050 delim off
rpc_svc(3)