rpc_svc_create(3NSL) Networking Services Library Functionsrpc_svc_create(3NSL)NAME
rpc_svc_create, svc_control, svc_create, svc_destroy, svc_dg_create,
svc_fd_create, svc_raw_create, svc_tli_create, svc_tp_create,
svc_vc_create, svc_door_create - server handle creation routines
SYNOPSIS
#include <rpc/rpc.h>
bool_t svc_control(SVCXPRT *svc, const uint_t req, void *info);
int svc_create(const void (*dispatch)const struct svc_req *,
const SVCXPRT *, const rpcprog_t prognum, const rpcvers_t versnum,
const char *nettype);
void svc_destroy(SVCXPRT *xprt);
SVCXPRT *svc_dg_create(const int fildes, const uint_t sendsz,
const uint_t recvsz);
SVCXPRT *svc_fd_create(const int fildes, const uint_t sendsz,
const uint_t recvsz);
SVCXPRT *svc_raw_create(void)
SVCXPRT *svc_tli_create(const int fildes, const struct netconfig *netconf,
const struct t_bind *bind_addr, const uint_t sendsz,
const uint_t recvsz);
SVCXPRT *svc_tp_create(const void (*dispatch)
const struct svc_req *, const SVCXPRT *), const rpcprog_t prognum,
const rpcvers_t versnum, const struct netconfig *netconf);
SVCXPRT *svc_vc_create(const int fildes, const uint_t sendsz,
const uint_t recvsz);
SVCXPRT *svc_door_create(void (*dispatch)(struct svc_req *, SVCXPRT *),
const rpcprog_t prognum, const rpcvers_t versnum,
const uint_t sendsz);
DESCRIPTION
These routines are part of the RPC library which allows C language pro‐
grams to make procedure calls on servers across the network. These rou‐
tines deal with the creation of service handles. Once the handle is
created, the server can be invoked by calling svc_run().
Routines
See rpc(3NSL) for the definition of the SVCXPRT data structure.
svc_control() A function to change or retrieve information about
a service object. req indicates the type of opera‐
tion and info is a pointer to the information. The
supported values of req, their argument types,
and what they do are:
SVCGET_VERSQUIET If a request is received
for a program number
served by this server but
the version number is
outside the range regis‐
tered with the server, an
RPC_PROGVERSMISMATCH
error will normally be
returned. info should be
a pointer to an integer.
Upon successful comple‐
tion of the SVCGET_VER‐
SQUIET request, *info
contains an integer which
describes the server's
current behavior: 0
indicates normal server
behavior, that is, an
RPC_PROGVERSMISMATCH
error will be returned. 1
indicates that the out of
range request will be
silently ignored.
SVCSET_VERSQUIET If a request is received
for a program number
served by this server but
the version number is
outside the range regis‐
tered with the server, an
RPC_PROGVERSMISMATCH
error will normally be
returned. It is some‐
times desirable to change
this behavior. info
should be a pointer to an
integer which is either
0, indicating normal
server behavior and an
RPC_PROGVERSMISMATCH
error will be returned,
or 1, indicating that
the out of range request
should be silently
ignored.
SVCGET_XID Returns the transaction
ID of connection−oriented
and connectionless trans‐
port service calls. The
transaction ID assists
in uniquely identifying
client requests for a
given RPC version, pro‐
gram number, procedure,
and client. The transac‐
tion ID is extracted
from the service trans‐
port handle svc. info
must be a pointer to an
unsigned long. Upon suc‐
cessful completion of the
SVCGET_XID request,
*info contains the trans‐
action ID. Note that
rendezvous and raw ser‐
vice handles do not
define a transaction ID.
Thus, if the service han‐
dle is of rendezvous or
raw type, and the request
is of type SVCGET_XID,
svc_control() will return
FALSE. Note also that the
transaction ID read by
the server can be set by
the client through the
suboption CLSET_XID in
clnt_control(). See
clnt_create(3NSL)
SVCSET_RECVERRHANDLER Attaches or detaches a
disconnection handler to
the service handle, svc,
that will be called when
a transport error arrives
during the reception of a
request or when the
server is waiting for a
request and the connec‐
tion shuts down. This
handler is only useful
for a connection oriented
service handle.
*info contains the
address of the error han‐
dler to attach, or NULL
to detach a previously
defined one. The error
handler has two argu‐
ments. It has a pointer
to the erroneous service
handle. It also has an
integer that indicates if
the full service is
closed (when equal to
zero), or that only one
connection on this ser‐
vice is closed (when not
equal to zero).
void handler (const SVCXPRT *svc, const bool_t isAConnection);
With the service handle
address, svc, the error
handler is able to detect
which connection has
failed and to begin an
error recovery process.
The error handler can be
called by multiple
threads and should be
implemented in an MT-safe
way.
SVCGET_RECVERRHANDLER Upon successful comple‐
tion of the
SVCGET_RECVERRHANDLER
request, *info contains
the address of the han‐
dler for receiving
errors. Upon failure,
*info contains NULL.
SVCSET_CONNMAXREC Set the maximum record
size (in bytes) and
enable non-blocking mode
for this service handle.
Value can be set and read
for both connection and
non-connection oriented
transports, but is
silently ignored for the
non-connection oriented
case. The info argument
should be a pointer to an
int.
SVCGET_CONNMAXREC Get the maximum record
size for this service
handle. Zero means no
maximum in effect and the
connection is in blocking
mode. The result is not
significant for non-con‐
nection oriented trans‐
ports. The info argument
should be a pointer to an
int.
This routine returns TRUE if the operation was
successful. Otherwise, it returns false.
svc_create()svc_create() 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 NULL, it defaults to net‐
path.
svc_create() 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 calling
svc_run() (see svc_run() in rpc_svc_reg(3NSL)). If
svc_create() succeeds, it returns the number of
server handles it created, otherwise it returns 0
and an error message is logged.
svc_destroy() A function macro that destroys the RPC service
handle xprt. Destruction usually involves deallo‐
cation of private data structures, including xprt
itself. Use of xprt is undefined after calling
this routine.
svc_dg_create() This routine creates a connectionless RPC service
handle, and returns a pointer to it. This routine
returns NULL if it fails, and an error message is
logged. sendsz and recvsz are parameters used to
specify the size of the buffers. If they are 0,
suitable defaults are chosen. The file descriptor
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.
svc_fd_create() This routine creates a service on top of an open
and bound file descriptor, and returns the handle
to it. Typically, this descriptor is a connected
file descriptor for a connection-oriented trans‐
port. sendsz and recvsz indicate sizes for the
send and receive buffers. If they are 0, reason‐
able defaults are chosen. This routine returns
NULL if it fails, and an error message is logged.
svc_raw_create() 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 clnt_raw_create() in
rpc_clnt_create(3NSL)). This routine allows simu‐
lation of RPC and acquisition of RPC overheads
(such as round trip times), without any kernel and
networking interference. This routine returns NULL
if it fails, and an error message is logged.
Note: svc_run() should not be called when the raw
interface is being used.
svc_tli_create() This routine creates an RPC server handle, and
returns a pointer to it. fildes is the file
descriptor on which the service is listening. If
fildes is RPC_ANYFD, 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, otherwise fildes is bound to a default
address chosen by the transport. In the case where
the default address is chosen, the number of out‐
standing connect requests is set to 8 for connec‐
tion-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 NULL if it
fails, and an error message is logged. The server
is not registered with the rpcbind(1M) service.
svc_tp_create()svc_tp_create() 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
svc_run(). svc_tp_create() returns the service
handle if it succeeds, otherwise a NULL is
returned and an error message is logged.
svc_vc_create() This routine creates a connection-oriented RPC
service and returns a pointer to it. This routine
returns NULL 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)
service.
svc_door_create() This routine creates an RPC server handle 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 corresponding default buffer size
is 16 Kbyte. If successful, the svc_door_create()
routine returns the service handle. Otherwise it
returns NULL and sets a value for rpc_createerr.
The server is not registered with rpcbind(1M). The
SVCSET_CONNMAXREC and SVCGET_CONNMAXREC svc_con‐
trol() requests can be used to set and change the
maximum allowed request size for the doors trans‐
port.
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
┌─────────────────────────────┬─────────────────────────────┐
│ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
├─────────────────────────────┼─────────────────────────────┤
│Architecture │All │
├─────────────────────────────┼─────────────────────────────┤
│Availability │system/library (32-bit) │
├─────────────────────────────┼─────────────────────────────┤
│ │SUNWcslx (64-bit) │
├─────────────────────────────┼─────────────────────────────┤
│Interface Stability │Committed │
├─────────────────────────────┼─────────────────────────────┤
│MT-Level │MT-Safe │
└─────────────────────────────┴─────────────────────────────┘
SEE ALSOrpcbind(1M), rpc(3NSL), rpc_clnt_create(3NSL), rpc_svc_calls(3NSL),
rpc_svc_err(3NSL), rpc_svc_reg(3NSL), attributes(5)SunOS 5.11 22 Mar 2005 rpc_svc_create(3NSL)