Networking Services Library Functions rpcsvccalls(3NSL)
NAME
rpcsvccalls, svcdgenablecache, svcdone, svcexit,
svcfdset, svcfreeargs, svcgetargs, svcgetreqcommon,
svcgetreqpoll, svcgetreqset, svcgetrpccaller,
svcmaxpollfd, svcpollfd, svcrun, svcsendreply,
svcgetcallerucred, svcfdnegotiateucred - library rou-
tines for RPC servers
SYNOPSIS
cc [ flag... ] file... -lnsl [ library...]
#include
int svcdgenablecache(SVCXPRT *xprt, const uintt cachesize);
int svcdone(SVCXPRT *xprt);
void svcexit(void);
void svcfdnegotiateucred(int fd);
boolt svcfreeargs(const SVCXPRT *xprt, const txdrproct inproc,
caddrt in);
boolt svcgetargs(const SVCXPRT *xprt, const xdrproct inproc,
caddrt in);
int svcgetcallerucred(const SVCXPRT *xprt, ucredt **ucred);
void svcgetreqcommon(const int fd);
void svcgetreqset(fdset *rdfds);
void svcgetreqpoll(struct pollfd *pfdp, const int pollretval);
struct netbuf *svcgetrpccaller(const SVCXPRT *xprt);
void svcrun(void);
boolt svcsendreply(const SVCXPRT *xprt, const xdrproct outproc,
caddrt outint svcmaxpollfd;
SunOS 5.11 Last change: 26 Jan 2004 1
Networking Services Library Functions rpcsvccalls(3NSL)
fdset svcfdset;
pollfdt *svcpollfd;
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. Others, such as svcrun(), are called
when the server is initiated.
Because the service transport handle SVCXPRT contains a sin-
gle data area for decoding arguments and encoding results,
the structure cannot freely be shared between threads that
call functions to decode arguments and encode results. When
a server is operating in the Automatic or User MT modes,
however, a copy of this structure is passed to the service
dispatch procedure in order to enable concurrent request
processing. Under these circumstances, some routines which
would otherwise be Unsafe, become Safe. These are marked as
such. Also marked are routines that are Unsafe for mul-
tithreaded applications, and are not to be used by such
applications. See rpc(3NSL) for the definition of the
SVCXPRT data structure.
The svcdgenablecache() function allocates a duplicate
request cache for the service endpoint xprt, large enough to
hold cachesize entries. Once enabled, there is no way to
disable caching. The function returns 1 if space necessary
for a cache of the given size was successfully allocated,
and 0 otherwise. This function is Safe in multithreaded
applications.
The svcdone() function frees resources allocated to service
a client request directed to the service endpoint xprt. This
call pertains only to servers executing in the User MT mode.
In the User MT mode, service procedures must invoke this
call before returning, either after a client request has
been serviced, or after an error or abnormal condition that
prevents a reply from being sent. After svcdone() is
invoked, the service endpoint xprt should not be referenced
by the service procedure. Server multithreading modes and
parameters can be set using the rpccontrol() call. This
function is Safe in multithreaded applications. It will have
no effect if invoked in modes other than the User MT mode.
SunOS 5.11 Last change: 26 Jan 2004 2
Networking Services Library Functions rpcsvccalls(3NSL)
The svcexit() function when called by any of the RPC server
procedures or otherwise, destroys all services registered by
the server and causes svcrun() to return. If RPC server
activity is to be resumed, services must be reregistered
with the RPC library either through one of the
rpcsvccreate(3NSL) functions, or using
xprtregister(3NSL). The svcexit() function has global
scope and ends all RPC server activity.
The svcfreeargs() function macro frees any data allocated
by the RPC/XDR system when it decoded the arguments to a
service procedure using svcgetargs(). This routine returns
TRUE if the results were successfully freed, and FALSE oth-
erwise. This function macro is Safe in multithreaded appli-
cations utilizing the Automatic or User MT modes.
The svcgetargs() function macro 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 TRUE if decoding succeeds,
and FALSE otherwise. This function macro is Safe in mul-
tithreaded applications utilizing the Automatic or User MT
modes.
The svcgetreqcommon() function is called to handle a
request on a file descriptor.
The svcgetreqpoll() function is only of interest if a ser-
vice implementor does not call svcrun(), but instead imple-
ments custom asynchronous event processing. It is called
when poll(2) has determined that an RPC request has arrived
on some RPC file descriptors; pollretval is the return value
from poll(2) and pfdp is the array of pollfd structures on
which the poll(2) was done. It is assumed to be an array
large enough to contain the maximal number of descriptors
allowed. The svcgetreqpoll() function macro is Unsafe in
multithreaded applications.
The svcgetreqset() function is only of interest if a ser-
vice implementor does not call svcrun(), but instead imple-
ments custom asynchronous event processing. It is called
when select(3C) 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. This function macro is Unsafe in
SunOS 5.11 Last change: 26 Jan 2004 3
Networking Services Library Functions rpcsvccalls(3NSL)
multithreaded applications.
The svcgetrpccaller() function is the approved way of get-
ting the network address of the caller of a procedure asso-
ciated with the RPC service transport handle xprt. This
function macro is Safe in multithreaded applications.
The svcrun() function never returns. In single-threaded
mode, the function waits for RPC requests to arrive. When an
RPC request arrives, the svcrun() function calls the
appropriate service procedure. This procedure is usually
waiting for the poll(2) library call to return.
Applications that execute in the Automatic or the User MT
mode should invoke the svcrun() function exactly once. In
the Automatic MT mode, the svcrun() function creates
threads to service client requests. In the User MT mode, the
function provides a framework for service developers to
create and manage their own threads for servicing client
requests.
The svcfdset global variable reflects the RPC server's read
file descriptor bit mask. This is only of interest if ser-
vice implementors do not call svcrun(), but rather do their
own asynchronous event processing. This variable is read-
only may change after calls to svcgetreqset() or after any
creation routine. Do not pass its address to select(3C).
Instead, pass the address of a copy. multithreaded applica-
tions executing in either the Automatic MT mode or the user
MT mode should never read this variable. They should use
auxiliary threads to do asynchronous event processing. The
svcfdset variable is limited to 1024 file descriptors and
is considered obsolete. Use of svcpollfd is recommended
instead.
The svcpollfd global variable points to an array of
pollfdt structures that reflect the RPC server's read file
descriptor array. This is only of interest if service ser-
vice implementors do not call svcrun() but rather do their
own asynchronous event processing. This variable is read-
only, and it may change after calls to svcgetregpoll() or
any creation routines. Do no pass its address to poll(2).
Instead, pass the address of a copy. By default, svcpollfd
is limited to 1024 entries. Use rpccontrol(3NSL) to remove
this limitation. multithreaded applications executing in
either the Automatic MT mode or the user MT mode should
never be read this variable. They should use auxiliary
SunOS 5.11 Last change: 26 Jan 2004 4
Networking Services Library Functions rpcsvccalls(3NSL)
threads to do asynchronous event processing.
The svcmaxpollfd global variable contains the maximum
length of the svcpollfd array. This variable is read-only,
and it may change after calls to svcgetregpoll() or any
creation routines.
The svcsendreply() function is called by an RPC service
dispatch routine to send the results of a remote procedure
call. The xprt parameter is the transport handle of the
request. The outproc parameter is the XDR routine used to
encode the results. The out parameter is the address of the
results. This routine returns TRUE if it succeeds, FALSE
otherwise. The svcsendreply() function macro is Safe in
multithreaded applications that use the Automatic or the
User MT mode.
The svcfdnegotiateucred() function is called by an RPC
server to inform the underlying transport that the function
wishes to receive ucreds for local calls, including those
over IP transports.
The svcgetcallerucred() function attempts to retrieve the
ucredt associated with the caller. The function returns 0
when successful and -1 when not.
When successful, the svcgetcallerucred() function stores
the pointer to a freshly allocated ucredt in the memory
location pointed to by the ucred argument if that memory
location contains the null pointer. If the memory location
is non-null, the function reuses the existing ucredt. When
ucred is no longer needed, a credential allocated by
svcgetcallerucred() should be freed with ucredfree(3C).
ATRIBUTES
See attributes(5) for descriptions of attribute types and
values.
SunOS 5.11 Last change: 26 Jan 2004 5
Networking Services Library Functions rpcsvccalls(3NSL)
ATRIBUTE TYPE ATRIBUTE VALUE
MT-Level See below.
The svcfdnegotiateucred(), svcdgenablecache(),
svcgetrpccaller(), and svcgetcallerucred() functions are
Safe in multithreaded applications. The svcfreeargs(),
svcgetargs(), and svcsendreply() functions are Safe in
multithreaded applications that use the Automatic or the
User MT mode. The svcgetreqcommon(), svcgetreqset(), and
svcgetreqpoll() functions are Unsafe in multithreaded
applications and should be called only from the main thread.
SEE ALSO
rpcgen(1), poll(2), getpeerucred(3C), rpc(3NSL),
rpccontrol(3NSL), rpcsvccreate(3NSL), rpcsvcerr(3NSL),
rpcsvcreg(3NSL), select(3C), ucredfree(3C),
xprtregister(3NSL), attributes(5)
SunOS 5.11 Last change: 26 Jan 2004 6
|
