RPC_CONTROL(3NSL) Networking Services Library Functions RPC_CONTROL(3NSL)

NAME

rpc_control - library routine for manipulating global RPC attributes
for client and server applications

SYNOPSIS

bool_t rpc_control(int op, void *info);

DESCRIPTION

This RPC library routine allows applications to set and modify global
RPC attributes that apply to clients as well as servers. At present,
it supports only server side operations. This function allows
applications to set and modify global attributes that apply to client
as well as server functions. op indicates the type of operation, and
info is a pointer to the operation specific information. The
supported values of op and their argument types, and what they do
are:

RPC_SVC_MTMODE_SET int * set multithread mode
RPC_SVC_MTMODE_GET int * get multithread mode
RPC_SVC_THRMAX_SET int * set maximum number of threads
RPC_SVC_THRMAX_GET int * get maximum number of threads
RPC_SVC_THRTOTAL_GET int * get number of active threads
RPC_SVC_THRCREATES_GET int * get number of threads created
RPC_SVC_THRERRORS_GET int * get number of thread create errors
RPC_SVC_USE_POLLFD int * set number of file descriptors to unlimited
RPC_SVC_CONNMAXREC_SET int * set non-blocking max rec size
RPC_SVC_CONNMAXREC_GET int * get non-blocking max rec size


There are three multithread (MT) modes. These are:

RPC_SVC_MT_NONE Single threaded mode (default)
RPC_SVC_MT_AUTO Automatic MT mode
RPC_SVC_MT_USER User MT mode


Unless the application sets the Automatic or User MT modes, it will
stay in the default (single threaded) mode. See the Network
Interfaces Programmer's Guide for the meanings of these modes and
programming examples. Once a mode is set, it cannot be changed.


By default, the maximum number of threads that the server will create
at any time is 16. This allows the service developer to put a bound
on thread resources consumed by a server. If a server needs to
process more than 16 client requests concurrently, the maximum number
of threads must be set to the desired number. This parameter may be
set at any time by the server.


Set and get operations will succeed even in modes where the
operations don't apply. For example, you can set the maximum number
of threads in any mode, even though it makes sense only for the
Automatic MT mode. All of the get operations except
RPC_SVC_MTMODE_GET apply only to the Automatic MT mode, so values
returned in other modes may be undefined.


By default, RPC servers are limited to a maximum of 1024 file
descriptors or connections due to limitations in the historical
interfaces svc_fdset(3NSL) and svc_getreqset(3NSL). Applications
written to use the preferred interfaces of svc_pollfd(3NSL) and
svc_getreq_poll(3NSL) can use an unlimited number of file
descriptors. Setting info to point to a non-zero integer and op to
RPC_SVC_USE_POLLFD removes the limitation.


Connection oriented RPC transports read RPC requests in blocking mode
by default. Thus, they may be adversely affected by network delays
and broken clients. RPC_SVC_CONNMAXREC_SET enables non-blocking mode
and establishes the maximum record size (in bytes) for RPC requests;
RPC responses are not affected. Buffer space is allocated as needed
up to the specified maximum, starting at the maximum or
RPC_MAXDATASIZE, whichever is smaller.


The value established by RPC_SVC_CONNMAXREC_SET is used when a
connection is created, and it remains in effect for that connection
until it is closed. To change the value for existing connections on a
per-connection basis, see svc_control(3NSL).


RPC_SVC_CONNMAXREC_GET retrieves the current maximum record size. A
zero value means that no maximum is in effect, and that the
connections are in blocking mode.


info is a pointer to an argument of type int. Non-connection RPC
transports ignore RPC_SVC_CONNMAXREC_SET and RPC_SVC_CONNMAXREC_GET.

RETURN VALUES

This routine returns TRUE if the operation was successful and returns
FALSE otherwise.

ATTRIBUTES

See attributes(7) for descriptions of the following attributes:


+---------------+-----------------+
|ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+---------------+-----------------+
|MT-Level | MT-Safe |
+---------------+-----------------+

SEE ALSO

rpc(3NSL), rpc_svc_calls(3NSL), attributes(7), rpcbind(8)


Network Interfaces Programmer's Guide

February 18, 2015 RPC_CONTROL(3NSL)