rpc_svc_reg(3rpc)


rpc_svc_reg: svc_auth_reg, svc_freeargs, svc_getargs, svc_getreqset, svc_getreq_common, svc_getreq_poll, svc_getreq_poll_parallel, svc_getrpccaller, svc_run, svc_run_parallel, svc_sendreply -- library routines for RPC servers

Synopsis

cc [options] file -lnsl
#include <rpc/rpc.h>

int svc_auth_reg(int cred_flavor, enum auth_stat *handler);

int svc_freeargs(const SVCXPRT *xprt, const xdrproc_t inproc, char *in);

int svc_getargs(const SVCXPRT *xprt, const xdrproc_t inproc, caddr_t in);

struct netbuf *svc_getrpccaller(const SVCXPRT *xprt);

void svc_run(void);

int svc_run_parallel(int timeout, int minthreads, int maxthreads, size_t stacksize);

int svc_sendreply(const SVCXPRT *xprt, const xdrproc_t outproc, const caddr_t out);

#include <rpc/rpc.h>

#include <sys/poll.h>

void svc_getreqset(fd_set *rdfds);

void svc_getreq_common(int fd)

void svc_getreq_poll(struct pollfd *pfdp, int retval);

void svc_getreq_poll_parallel(struct pollfd *pfdp, int retval);

Description

These routines are part of the RPC library which allows C language programs to make procedure calls on other machines across the network.

These routines are associated with the server side of the RPC mechanism. Some of them are called by the server side dispatch function, while others (such as svc_run) are called when the server is initiated.

Routines

int
svc_auth_reg(int cred_flavor, enum auth_stat *handler);
This routine allows users to register a new authentication type with a flavor specified by cred_flavor. When requests are authenticated, the routine specified by handler is called with the following parameters:
(*handler)(struct svc_req *, struct rpc_msg *);
The svc_auth_reg routine returns 0 if registration is successful, 1 if the flavor is already registered, or -1 if the call fails.
int
svc_freeargs(const SVCXPRT *xprt, const xdrproc_t inproc, char *in);
A function macro that frees data allocated by the RPC/XDR system. The system allocates data when it uses svc_getargs to decode arguments to a service procedure. This routine returns 1 if the results were successfully freed, and 0 otherwise.
int
svc_getargs(const SVCXPRT *xprt, const xdrproc_t inproc, caddr_t in);
A function macro that decodes the arguments of an RPC request associated with the RPC service transport handle xprt. The parameter in is the address where the arguments will be placed; inproc is the XDR routine used to decode the arguments. This routine returns 1 if decoding succeeds, and 0 otherwise.
void
svc_getreqset(fd_set *rdfds);
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 poll has determined that an RPC request has arrived on some RPC file descriptors; rdfds is the resultant read file descriptor bit mask. The routine returns when all file descriptors associated with the value of rdfds have been serviced.
void
svc_getreq_common(int fd)
This routine processes incoming RPC requests on a file descriptor specified by fd. All higher level service implementations like svc_run, svc_getreqset, and svc_getreq_poll use this routine to process RPC requests.

This routine authenticates incoming RPC requests on the file descriptor fd and calls the appropriate dispatch routine registered with rpcbind. If the transport provider is connection-oriented, the succeeding requests, if any, are processed repeatedly. This is called batched Remote Procedure Calls.

Note that this routine is thread-safe. However, a different file descriptor must be specified in each concurrent call to svc_getreq_common.

void
svc_getreq_poll(struct pollfd *pfdp, int retval);
Like svc_getreqset, this routine is only of interest if a service implementor does not call svc_run, but instead implements custom asynchronous event processing. The svc_run routine provided in the RPC library is currently implemented using this routine.

It should be called when poll has determined that an RPC request has arrived on some RPC file descriptors; pfdp is the poll data used during poll, and retval is the number of file descriptors to service, typically the return value from poll. The routine returns when all file descriptors specified by pfdp have been serviced.

Note that this routine is not thread-safe. Hence the service implementor must use appropriate synchronization to avoid calls to this routine from multiple threads at the same time.

void
svc_getreq_poll_parallel(struct pollfd *pfdp, int retval);
This routine is the thread-safe version of svc_getreq_poll and provides exactly the same functionality. It should be called only if the application will be polling on more than one file descriptor.
struct netbuf *
svc_getrpccaller(const SVCXPRT *xprt);
The approved way of getting the network address of the caller of a procedure associated with the RPC service transport handle xprt.
void
svc_run(void);
This routine never returns. It waits for RPC requests to arrive, and calls the appropriate service procedure using svc_getreqset when one arrives. This procedure is usually waiting for a poll library call to return.

Note that this routine is not thread-safe. Concurrent calls to this routine from multiple threads will cause undetermined behavior.

int
svc_run_parallel(int timeout, int minthreads, int maxthreads,
	size_t stacksize);
This is the multithreaded version of svc_run. This routine waits for RPC requests to arrive, and calls the appropriate service procedure via a call to svc_getreq_poll_parallel. Depending on the rate of incoming RPC requests, this routine will dynamically create or delete threads from the process. Each created thread services an RPC request and then waits for more to arrive. This function should be called only if the application is polling on more than one file descriptor.

The timeout argument specifies the number of milliseconds to wait for and RPC request to arrive. After waiting for this time, any thread created by svc_run_parallel will exit, provided the total number of threads is above minthreads. The maximum number of threads created by this routine is always less than maxthreads.

Note that this routine provides a performance gain for server processes which service a sustained rate of incoming RPC requests. Also, the service procedure may be called concurrently from many server threads, so it must be thread-safe. Currently, it is only supported for connectionless transports.

This routine returns -1 if either of minthreads or maxthreads is less than or equal to zero. It also returns -1 if maxthreads is less than or equal to minthreads.

It returns zero if there are no file server file descriptors to wait on.

int
svc_sendreply(const SVCXPRT *xprt, const xdrproc_t outproc,
	const caddr_t out);
Called by an RPC service's dispatch routine to send the results of a remote procedure call. The parameter xprt 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 1 if it succeeds, 0 otherwise.

Files

/usr/lib/locale/locale/LC_MESSAGES/uxnsl

References

poll(2), rpc(3rpc), rpc_svc_calls(3rpc), rpc_svc_create(3rpc), rpc_svc_err(3rpc), thr_create(3thread)
© 2004 The SCO Group, Inc. All rights reserved.
UnixWare 7 Release 7.1.4 - 25 April 2004