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 - library routines for the creation of
server handles
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 *net‐
conf, 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 operation 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 num‐
ber served by this server but the version
number is outside the range registered with
the server, an RPC_PROGVERSMISMATCH error
will normally be returned. info should be
a pointer to an integer. Upon successful
completion of the SVCGET_VERSQUIET request,
*info contains an integer which describes
the server's current behavior: 0 indi‐
cates 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 num‐
ber served by this server but the version
number is outside the range registered with
the server, an RPC_PROGVERSMISMATCH 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 behav‐
ior 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 connec‐
tion−oriented and connectionless transport
service calls. The transaction ID assists
in uniquely identifying client requests for
a given RPC version, program number, pro‐
cedure, and client. The transaction ID is
extracted from the service transport handle
svc. info must be a pointer to an
unsigned long. Upon successful completion
of the SVCGET_XID request, *info contains
the transaction ID. Note that rendezvous
and raw service 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_con‐
trol() 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 han‐
dler 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
connection shuts down. This handler is only
useful for a connection oriented service
handle.
*info contains the address of the error
handler to attach, or NULL to detach a pre‐
viously defined one. The error handler has
two arguments. 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 service 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 con‐
nection 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 completion of the
SVCGET_RECVERRHANDLER request, *info con‐
tains the address of the handler for
receiving errors. Upon failure, *info con‐
tains NULL.
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 variable or in top to bottom order in
the netconfig database. If nettype is NULL, it
defaults to netpath.
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 call‐
ing svc_run() (see svc_run() in
rpc_svc_reg(3NSL)). If svc_create() succeeds,
it returns the number of server handles it cre‐
ated, otherwise it returns 0 and an error mes‐
sage is logged.
svc_destroy() A function macro that destroys the RPC service
handle xprt. Destruction usually involves deal‐
location 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 ser‐
vice handle, and returns a pointer to it. This
routine returns NULL 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 descriptor fildes should be open and
bound. The server is not registered with
rpcbind(1M).
Warning: since connectionless-based RPC mes‐
sages can only hold limited amount of encoded
data, this transport cannot be used for proce‐
dures 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-ori‐
ented transport. sendsz and recvsz indicate
sizes for the send and receive buffers. If they
are 0, reasonable 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 simulation 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 net‐
conf. 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 outstanding
connect 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
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, oth‐
erwise 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 rou‐
tine 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 buf‐
fer 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 reg‐
istered with rpcbind(1M).
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
┌─────────────────────────────┬─────────────────────────────┐
│ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
├─────────────────────────────┼─────────────────────────────┤
│Architecture │All │
├─────────────────────────────┼─────────────────────────────┤
│Availability │SUNWcsl (32-bit) │
├─────────────────────────────┼─────────────────────────────┤
│ │SUNWcslx (64-bit) │
├─────────────────────────────┼─────────────────────────────┤
│Interface Stability │Evolving │
├─────────────────────────────┼─────────────────────────────┤
│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.10 Aug 2001 rpc_svc_create(3NSL)
