Networking Services Library Functions rpc_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
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
SunOS 5.11 Last change: 22 Mar 2005 1
Networking Services Library Functions rpc_svc_create(3NSL)
These routines are part of the RPC library which allows C language programs to make procedure calls on servers acrossthe network. These routines deal with the creation of ser-
vice handles. Once the handle is created, the server can beinvoked by calling svc_run().
RoutinesSee rpc(3NSL) for the definition of the SVCXPRT data struc-
ture.svc_control() 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:SVCGET_VERSQUIET If a request
is received for a program number served by this serverbut the ver-
sion number is outside the range registered with the server, anRPC_PROGVERSMISMATCH
error will normally be returned. info should be a pointer to an integer.Upon success-
ful completion of theSVCGET_VERSQUIET
request, *info contains an integer which describes the server's current behavior: 0indicates nor-
mal server behavior, that is, anSunOS 5.11 Last change: 22 Mar 2005 2
Networking Services Library Functions rpc_svc_create(3NSL)
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 serverbut the ver-
sion number is outside the range registered with the server, anRPC_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 behavior and anRPC_PROGVERSMISMATCH
error will be returned, or 1, indicating that the out of range request should be silently ignored.SVCGET_XID Returns the
transactionSunOS 5.11 Last change: 22 Mar 2005 3
Networking Services Library Functions rpc_svc_create(3NSL)
ID ofconnection-oriented
and connec-
tionless tran-
sport service calls. The transaction ID assists inuniquely iden-
tifying client requests for agiven RPC ver-
sion, programnumber, pro-
cedure, and client. The transaction ID is extracted from the servicetransport han-
dle svc. info must be a pointer to an unsigned long.Upon success-
ful completion of theSVCGET_XID
request, *info containsthe transac-
tion ID. Notethat rendez-
vous and rawservice han-
dles do notdefine a tran-
saction ID. Thus, if the service handleis of rendez-
vous or raw type, and the request is of typeSVCGET_XID,
svc_control()
will return FALSE. Note also that the transactionSunOS 5.11 Last change: 22 Mar 2005 4
Networking Services Library Functions rpc_svc_create(3NSL)
ID read by the server can be set by the client through the suboptionCLSET_XID in
clnt_control().
Seeclnt_create(3NSL)
SVCSET_RECVERRHANDLER Attaches or
detaches a disconnection handler to theservice han-
dle, svc, that will be calledwhen 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 usefulfor a connec-
tion orientedservice han-
dle. *info contains the address of the error handler to attach, or NULL to detach a previously defined one. The error handler has two arguments. It has a pointer to theerroneous ser-
vice handle. It also has anSunOS 5.11 Last change: 22 Mar 2005 5
Networking Services Library Functions rpc_svc_create(3NSL)
integer that indicates ifthe full ser-
vice is closed (when equal to zero), or thatonly one con-
nection on this service is closed (when not equal to zero).void handler (const SVCXPRT *svc, const bool_t isAConnection);
With the ser-
vice handle address, svc, the error handler is able to detectwhich connec-
tion has failed and to begin an errorrecovery pro-
cess. The error handler can be called by multiple threads and should be implemented inan MT-safe
way.SVCGET_RECVERRHANDLER Upon success-
ful completion of theSVCGET_RECVERRHANDLER
request, *info contains the address of the handler for receiving errors. Upon failure, *info contains NULL.SunOS 5.11 Last change: 22 Mar 2005 6
Networking Services Library Functions rpc_svc_create(3NSL)
SVCSET_CONNMAXREC Set the max-
imum record size (in bytes) andenable non-
blocking modefor this ser-
vice handle. Value can be set and readfor both con-
nection andnon-connection
oriented tran-
sports, but is silently ignored forthe non-
connection oriented case.The info argu-
ment should be a pointer to an int.SVCGET_CONNMAXREC Get the max-
imum record size for thisservice han-
dle. Zeromeans no max-
imum in effectand the con-
nection is in blocking mode. The result isnot signifi-
cant for non-
connectionoriented 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 rpc_svc_create(3NSL)
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 triedin 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 netpath.svc_create() registers itself with the
rpcbind service (see rpcbind(1M)). dispatch is called when there is a remote procedure call for the givenprognum and versnum; this requires cal-
ling 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 usu-
ally involves deallocation 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 messageis logged. sendsz and recvsz are param-
eters used to specify the size of the buffers. If they are 0, suitabledefaults 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 rpc_svc_create(3NSL)
svc_fd_create() 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 connectedfile 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 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; (seeclnt_raw_create() in
rpc_clnt_create(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 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 han-
dle, and returns a pointer to it. fildes is the file descriptor on which the service is listening. If fildes isRPC_ANYFD, it opens a file descriptor
on the transport specified by netconf. If the file descriptor is unbound andbindaddr 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 ischosen, the number of outstanding con-
nect requests is set to 8 forconnection-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 messageSunOS 5.11 Last change: 22 Mar 2005 9
Networking Services Library Functions rpc_svc_create(3NSL)
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; thisrequires 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 notregistered with the rpcbind(1M) ser-
vice.svc_door_create() 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 parametersendsz. If sendsz is 0, the correspond-
ing default buffer size is 16 Kbyte. Ifsuccessful, the svc_door_create() rou-
tine returns the service handle. Other-
wise it returns NULL and sets a valuefor rpc_createerr. The server is not
registered with rpcbind(1M). TheSVCSET_CONNMAXREC and SVCGET_CONNMAXREC
svc_control() 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 rpc_svc_create(3NSL)
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Architecture | All ||_____________________________|_____________________________|
| Availability | system/library (32-bit) |
|_____________________________|_____________________________|
| | SUNWcslx (64-bit) |
|_____________________________|_____________________________|
| Interface Stability | Committed ||_____________________________|_____________________________|
| MT-Level | MT-Safe |
|_____________________________|_____________________________|
SEE ALSO
rpcbind(1M), rpc(3NSL), rpc_clnt_create(3NSL),
rpc_svc_calls(3NSL), rpc_svc_err(3NSL), rpc_svc_reg(3NSL),
attributes(5)SunOS 5.11 Last change: 22 Mar 2005 11