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 multithreaded environment). Routines that are not thread safe are flagged as such. 

svc_destroy()
[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. 

fd_set svc_fdset;
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. 

int svc_fds;
Similar to svc_fdset(), but limited to 32 descriptors. This interface is obsoleted by svc_fdset(). 

svc_freeargs()
[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. 

svc_getargs()
[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. 

struct sockaddr_in ∗svc_getcaller()
[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. 

svc_getreq()
[Not Thread Safe]   Similar to svc_getreqset(), but limited to 32 descriptors. This interface is obsoleted by svc_getreqset(). 

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. 

svc_register()
[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 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. 

svc_run()
[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. 

svc_sendreply()
[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. 

void svc_unregister()
[Not Thread Safe]   Removes all mapping of the double [prognum,versnum] to dispatch routines, and of the triple [prognum,versnum,∗] to port number. 

void svcerr_auth()
[Not Thread Safe]   Called by a service dispatch routine that refuses to perform a remote procedure call due to an authentication error.

void svcerr_decode()
[Not Thread Safe]  Called by a service dispatch routine that cannot successfully decode its parameters. See also svc_getargs(). 

void svcerr_noproc()
[Not Thread Safe]  Called by a service dispatch routine that does not implement the procedure number that the caller requests.

void svcerr_noprog()
[Not Thread Safe]  Called when the desired program is not registered with the RPC package. Service implementors usually do not need this routine.

void svcerr_progvers()
[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.

void svcerr_systemerr()
[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.

void svcerr_weakauth()
[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). 

voidsvcfd_create()
[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. 

SVCXPRT ∗ svcraw_create()
[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. 

SVCXPRT ∗ svctcp_create()
[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 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. 

SVCXPRT ∗ svcudp_create()
[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 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. 

SEE ALSO

rpc-clnt(3), rpc-misc(3), rpc-xdr(3), xdr(3)

Remote Procedure Calls: Protocol Specification − RFC 1050