Tribblix: manual page: rpc_svc

RPC_SVC_CREATE(3NSL) Networking Services Library Functions

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_tp_create_addr, 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_info, 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_tp_create_addr(const void (*dispatch)
(const struct svc_req *, const SVCXPRT *), const rpcprog_t prognum,
const rpcvers_t versnum, const struct netconfig *netconf,
const struct netbuf *bind_addr)
);

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
programs to make procedure calls on servers across the network. These
routines 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
number 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 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 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 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
transport service calls. The transaction ID
assists in uniquely identifying client
requests for a given RPC version, program
number, procedure, 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 handle 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
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
previously 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
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 completion of the
SVCGET_RECVERRHANDLER request, *info
contains the address of the handler 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-connection
oriented transports. 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 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(8)). 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_calls(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 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 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(8).

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 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 netconf. If the file descriptor is
unbound and bind_info is non-null fildes is bound to
the address specified by bind_info, 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(8) 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_tp_create_addr()
svc_tp_create_addr() creates a server handle for the
network specified by netconf, and registers itself
with the rpcbind service. If bind_addr is non-NULL,
that address is used for the listener binding. If
bind_addr is NULL, this call is the same as
svc_tp_create(). dispatch is called when there is a
remote procedure call for the given prognum and
versnum; this requires calling svc_run().
svc_tp_create_addr() 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(8) service.

svc_door_create()
This routine creates an RPC server handle over doors
for the given program prognum and version versnum and
returns a pointer to it. Doors is a transport
mechanism that facilitates fast data transfer between
processes on the same machine. 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(8). The SVCSET_CONNMAXREC and
SVCGET_CONNMAXREC svc_control() requests can be used
to set and change the maximum allowed request size for
the doors transport.

ATTRIBUTES

NAME

SYNOPSIS

DESCRIPTION

Routines

ATTRIBUTES

SEE ALSO