Networking Services Library Functions rpcsvccreate(3NSL)
NAME
rpcsvccreate, svccontrol, svccreate, svcdestroy,
svcdgcreate, svcfdcreate, svcrawcreate,
svctlicreate, svctpcreate, svcvccreate,
svcdoorcreate - server handle creation routines
SYNOPSIS
#include
boolt svccontrol(SVCXPRT *svc, const uintt req, void *info);
int svccreate(const void (*dispatch)const struct svcreq *,
const SVCXPRT *, const rpcprogt prognum, const rpcverst versnum,
const char *nettype);
void svcdestroy(SVCXPRT *xprt);
SVCXPRT *svcdgcreate(const int fildes, const uintt sendsz,
const uintt recvsz);
SVCXPRT *svcfdcreate(const int fildes, const uintt sendsz,
const uintt recvsz);
SVCXPRT *svcrawcreate(void)
SVCXPRT *svctlicreate(const int fildes, const struct netconfig *netconf,
const struct tbind *bindaddr, const uintt sendsz,
const uintt recvsz);
SVCXPRT *svctpcreate(const void (*dispatch)
const struct svcreq *, const SVCXPRT *), const rpcprogt prognum,
const rpcverst versnum, const struct netconfig *netconf);
SVCXPRT *svcvccreate(const int fildes, const uintt sendsz,
const uintt recvsz);
SVCXPRT *svcdoorcreate(void (*dispatch)(struct svcreq *, SVCXPRT *),
const rpcprogt prognum, const rpcverst versnum,
const uintt sendsz);
DESCRIPTION
SunOS 5.11 Last change: 22 Mar 2005 1
Networking Services Library Functions rpcsvccreate(3NSL)
These routines are part of the RPC library which allows C
language programs to make procedure calls on servers across
the network. These routines deal with the creation of ser-
vice handles. Once the handle is created, the server can be
invoked by calling svcrun().
Routines
See rpc(3NSL) for the definition of the SVCXPRT data struc-
ture.
svccontrol() A function to change or retrieve infor-
mation about a service object. req
indicates the type of operation and
info is a pointer to the information.
The supported values of req, their
argument types, and what they do are:
SVCGETVERSQUIET If a request
is received
for a program
number served
by this server
but the ver-
sion number is
outside the
range
registered
with the
server, an
RPCPROGVERSMISMATCH
error will
normally be
returned.
info should be
a pointer to
an integer.
Upon success-
ful completion
of the
SVCGETVERSQUIET
request,
*info contains
an integer
which
describes the
server's
current
behavior: 0
indicates nor-
mal server
behavior, that
is, an
SunOS 5.11 Last change: 22 Mar 2005 2
Networking Services Library Functions rpcsvccreate(3NSL)
RPCPROGVERSMISMATCH
error will be
returned. 1
indicates that
the out of
range request
will be
silently
ignored.
SVCSETVERSQUIET If a request
is received
for a program
number served
by this server
but the ver-
sion number is
outside the
range
registered
with the
server, an
RPCPROGVERSMISMATCH
error will
normally be
returned. It
is sometimes
desirable to
change this
behavior. info
should be a
pointer to an
integer which
is either 0,
indicating
normal server
behavior and
an
RPCPROGVERSMISMATCH
error will be
returned, or
1, indicating
that the out
of range
request should
be silently
ignored.
SVCGETXID Returns the
transaction
SunOS 5.11 Last change: 22 Mar 2005 3
Networking Services Library Functions rpcsvccreate(3NSL)
ID of
connection-oriented
and connec-
tionless tran-
sport service
calls. The
transaction
ID assists in
uniquely iden-
tifying client
requests for a
given RPC ver-
sion, program
number, pro-
cedure, and
client. The
transaction
ID is
extracted from
the service
transport han-
dle svc. info
must be a
pointer to an
unsigned long.
Upon success-
ful completion
of the
SVCGETXID
request,
*info contains
the transac-
tion ID. Note
that rendez-
vous and raw
service han-
dles do not
define a tran-
saction ID.
Thus, if the
service handle
is of rendez-
vous or raw
type, and the
request is of
type
SVCGETXID,
svccontrol()
will return
FALSE. Note
also that the
transaction
SunOS 5.11 Last change: 22 Mar 2005 4
Networking Services Library Functions rpcsvccreate(3NSL)
ID read by the
server can be
set by the
client through
the suboption
CLSETXID in
clntcontrol().
See
clntcreate(3NSL)
SVCSETRECVERHANDLER Attaches or
detaches a
disconnection
handler to the
service han-
dle, svc, that
will be called
when a tran-
sport error
arrives during
the reception
of a request
or when the
server is
waiting for a
request and
the connection
shuts down.
This handler
is only useful
for a connec-
tion oriented
service han-
dle.
*info contains
the address of
the error
handler to
attach, or
NUL to detach
a previously
defined one.
The error
handler has
two arguments.
It has a
pointer to the
erroneous ser-
vice handle.
It also has an
SunOS 5.11 Last change: 22 Mar 2005 5
Networking Services Library Functions rpcsvccreate(3NSL)
integer that
indicates if
the full ser-
vice is closed
(when equal to
zero), or that
only one con-
nection on
this service
is closed
(when not
equal to
zero).
void handler (const SVCXPRT *svc, const boolt isAConnection);
With the ser-
vice handle
address, svc,
the error
handler is
able to detect
which connec-
tion has
failed and to
begin an error
recovery pro-
cess. The
error handler
can be called
by multiple
threads and
should be
implemented in
an MT-safe
way.
SVCGETRECVERHANDLER Upon success-
ful completion
of the
SVCGETRECVERHANDLER
request, *info
contains the
address of the
handler for
receiving
errors. Upon
failure, *info
contains NUL.
SunOS 5.11 Last change: 22 Mar 2005 6
Networking Services Library Functions rpcsvccreate(3NSL)
SVCSETCONMAXREC Set the max-
imum record
size (in
bytes) and
enable non-
blocking mode
for this ser-
vice handle.
Value can be
set and read
for both con-
nection and
non-connection
oriented tran-
sports, but is
silently
ignored for
the non-
connection
oriented case.
The info argu-
ment should be
a pointer to
an int.
SVCGETCONMAXREC Get the max-
imum record
size for this
service han-
dle. Zero
means no max-
imum in effect
and the con-
nection is in
blocking mode.
The result is
not signifi-
cant for non-
connection
oriented tran-
sports. The
info argument
should be a
pointer to an
int.
This routine returns TRUE if the opera-
tion was successful. Otherwise, it
returns false.
SunOS 5.11 Last change: 22 Mar 2005 7
Networking Services Library Functions rpcsvccreate(3NSL)
svccreate() svccreate() creates server handles for
all the transports belonging to the
class nettype.
nettype defines a class of transports
which can be used for a particular
application. The transports are tried
in left to right order in NETPATH vari-
able or in top to bottom order in the
netconfig database. If nettype is NUL,
it defaults to netpath.
svccreate() registers itself with the
rpcbind service (see rpcbind(1M)).
dispatch is called when there is a
remote procedure call for the given
prognum and versnum; this requires cal-
ling svcrun() (see svcrun() in
rpcsvcreg(3NSL)). If svccreate()
succeeds, it returns the number of
server handles it created, otherwise it
returns 0 and an error message is
logged.
svcdestroy() A function macro that destroys the RPC
service handle xprt. Destruction usu-
ally involves deallocation of private
data structures, including xprt itself.
Use of xprt is undefined after calling
this routine.
svcdgcreate() This routine creates a connectionless
RPC service handle, and returns a
pointer to it. This routine returns
NUL if it fails, and an error message
is logged. sendsz and recvsz are param-
eters used to specify the size of the
buffers. If they are 0, suitable
defaults are chosen. The file descrip-
tor fildes should be open and bound.
The server is not registered with
rpcbind(1M).
Warning: since connectionless-based RPC
messages can only hold limited amount
of encoded data, this transport cannot
be used for procedures that take large
arguments or return huge results.
SunOS 5.11 Last change: 22 Mar 2005 8
Networking Services Library Functions rpcsvccreate(3NSL)
svcfdcreate() This routine creates a service on top
of an open and bound file descriptor,
and returns the handle to it. Typi-
cally, this descriptor is a connected
file descriptor for a connection-
oriented transport. sendsz and recvsz
indicate sizes for the send and receive
buffers. If they are 0, reasonable
defaults are chosen. This routine
returns NUL if it fails, and an error
message is logged.
svcrawcreate() This routine creates an RPC service
handle and returns a pointer to it. 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
clntrawcreate() in
rpcclntcreate(3NSL)). This routine
allows simulation of RPC and acquisi-
tion of RPC overheads (such as round
trip times), without any kernel and
networking interference. This routine
returns NUL if it fails, and an error
message is logged.
Note: svcrun() should not be called
when the raw interface is being used.
svctlicreate() This routine creates an RPC server han-
dle, and returns a pointer to it.
fildes is the file descriptor on which
the service is listening. If fildes is
RPCANYFD, it opens a file descriptor
on the transport specified by netconf.
If the file descriptor is unbound and
bindaddr is non-null fildes is bound to
the address specified by bindaddr, oth-
erwise fildes is bound to a default
address chosen by the transport. In the
case where the default address is
chosen, the number of outstanding con-
nect requests is set to 8 for
connection-oriented transports. The
user may specify the size of the send
and receive buffers with the parameters
sendsz and recvsz ; values of 0 choose
suitable defaults. This routine returns
NUL if it fails, and an error message
SunOS 5.11 Last change: 22 Mar 2005 9
Networking Services Library Functions rpcsvccreate(3NSL)
is logged. The server is not registered
with the rpcbind(1M) service.
svctpcreate() svctpcreate() creates a server handle
for the network specified by netconf,
and registers itself with the rpcbind
service. dispatch is called when there
is a remote procedure call for the
given prognum and versnum; this
requires calling svcrun().
svctpcreate() returns the service
handle if it succeeds, otherwise a NUL
is returned and an error message is
logged.
svcvccreate() This routine creates a connection-
oriented RPC service and returns a
pointer to it. This routine returns
NUL if it fails, and an error message
is logged. The users may specify the
size of the send and receive buffers
with the parameters sendsz and recvsz;
values of 0 choose suitable defaults.
The file descriptor fildes should be
open and bound. The server is not
registered with the rpcbind(1M) ser-
vice.
svcdoorcreate() This routine creates an RPC server han-
dle over doors and returns a pointer to
it. Doors is a transport mechanism that
facilitates fast data transfer between
processes on the same machine. for the
given program The user may set the size
of the send buffer with the parameter
sendsz. If sendsz is 0, the correspond-
ing default buffer size is 16 Kbyte. If
successful, the svcdoorcreate() rou-
tine returns the service handle. Other-
wise it returns NUL and sets a value
for rpccreateerr. The server is not
registered with rpcbind(1M). The
SVCSETCONMAXREC and SVCGETCONMAXREC
svccontrol() requests can be used to
set and change the maximum allowed
request size for the doors transport.
SunOS 5.11 Last change: 22 Mar 2005 10
Networking Services Library Functions rpcsvccreate(3NSL)
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Architecture All
Availability SUNWcsl (32-bit)
SUNWcslx (64-bit)
Interface Stability Evolving
MT-Level MT-Safe
SEE ALSO
rpcbind(1M), rpc(3NSL), rpcclntcreate(3NSL),
rpcsvccalls(3NSL), rpcsvcerr(3NSL), rpcsvcreg(3NSL),
attributes(5)
SunOS 5.11 Last change: 22 Mar 2005 11
|
