| blob | ce905004abee71cb67ae453a19b710d4ec4e414b |
1 '\" te
2 .\" Copyright 2015 Nexenta Systems, Inc. All rights reserved.
3 .\" Copyright 1989 AT&T
4 .\" Copyright (C) 1999, Sun Microsystems, Inc. All Rights Reserved
5 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
6 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
7 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
8 .TH RPC_CONTROL 3NSL "Feb 18, 2015"
9 .SH NAME
10 rpc_control \- library routine for manipulating global RPC attributes for
11 client and server applications
12 .SH SYNOPSIS
13 .LP
14 .nf
15 \fBbool_t\fR \fBrpc_control\fR(\fBint\fR \fIop\fR, \fBvoid *\fR\fIinfo\fR);
16 .fi
18 .SH DESCRIPTION
19 .LP
20 This \fBRPC\fR library routine allows applications to set and modify global
21 \fBRPC\fR attributes that apply to clients as well as servers. At present, it
22 supports only server side operations. This function allows applications to set
23 and modify global attributes that apply to client as well as server functions.
24 \fIop\fR indicates the type of operation, and \fIinfo\fR is a pointer to the
25 operation specific information. The supported values of \fIop\fR and their
26 argument types, and what they do are:
27 .sp
28 .in +2
29 .nf
30 RPC_SVC_MTMODE_SET int * set multithread mode
31 RPC_SVC_MTMODE_GET int * get multithread mode
32 RPC_SVC_THRMAX_SET int * set maximum number of threads
33 RPC_SVC_THRMAX_GET int * get maximum number of threads
34 RPC_SVC_THRTOTAL_GET int * get number of active threads
35 RPC_SVC_THRCREATES_GET int * get number of threads created
36 RPC_SVC_THRERRORS_GET int * get number of thread create errors
37 RPC_SVC_USE_POLLFD int * set number of file descriptors to unlimited
38 RPC_SVC_CONNMAXREC_SET int * set non-blocking max rec size
39 RPC_SVC_CONNMAXREC_GET int * get non-blocking max rec size
40 .fi
41 .in -2
43 .sp
44 .LP
45 There are three multithread (MT) modes. These are:
46 .sp
47 .in +2
48 .nf
49 RPC_SVC_MT_NONE Single threaded mode (default)
50 RPC_SVC_MT_AUTO Automatic MT mode
51 RPC_SVC_MT_USER User MT mode
52 .fi
53 .in -2
55 .sp
56 .LP
57 Unless the application sets the Automatic or User MT modes, it will stay in the
58 default (single threaded) mode. See the \fINetwork Interfaces Programmer's
59 Guide\fR for the meanings of these modes and programming examples. Once a mode
60 is set, it cannot be changed.
61 .sp
62 .LP
63 By default, the maximum number of threads that the server will create at any
64 time is 16. This allows the service developer to put a bound on thread
65 resources consumed by a server. If a server needs to process more than 16
66 client requests concurrently, the maximum number of threads must be set to the
67 desired number. This parameter may be set at any time by the server.
68 .sp
69 .LP
70 Set and get operations will succeed even in modes where the operations don't
71 apply. For example, you can set the maximum number of threads in any mode,
72 even though it makes sense only for the Automatic MT mode. All of the get
73 operations except \fBRPC_SVC_MTMODE_GET\fR apply only to the Automatic MT mode,
74 so values returned in other modes may be undefined.
75 .sp
76 .LP
77 By default, \fBRPC\fR servers are limited to a maximum of 1024 file descriptors
78 or connections due to limitations in the historical interfaces
79 \fBsvc_fdset\fR(3NSL) and \fBsvc_getreqset\fR(3NSL). Applications written to
80 use the preferred interfaces of \fBsvc_pollfd\fR(3NSL) and
81 \fBsvc_getreq_poll\fR(3NSL) can use an unlimited number of file descriptors.
82 Setting \fIinfo\fR to point to a non-zero integer and \fIop\fR to
83 \fBRPC_SVC_USE_POLLFD\fR removes the limitation.
84 .sp
85 .LP
86 Connection oriented \fBRPC\fR transports read \fBRPC\fR requests in blocking
87 mode by default. Thus, they may be adversely affected by network delays and
88 broken clients. \fBRPC_SVC_CONNMAXREC_SET\fR enables non-blocking mode and
89 establishes the maximum record size (in bytes) for \fBRPC\fR requests;
90 \fBRPC\fR responses are not affected. Buffer space is allocated as needed up to
91 the specified maximum, starting at the maximum or \fBRPC_MAXDATASIZE\fR,
92 whichever is smaller.
93 .sp
94 .LP
95 The value established by \fBRPC_SVC_CONNMAXREC_SET\fR is used when a connection
96 is created, and it remains in effect for that connection until it is closed. To
97 change the value for existing connections on a per-connection basis, see
98 \fBsvc_control\fR(3NSL).
99 .sp
100 .LP
101 \fBRPC_SVC_CONNMAXREC_GET\fR retrieves the current maximum record size. A zero
102 value means that no maximum is in effect, and that the connections are in
103 blocking mode.
104 .sp
105 .LP
106 \fIinfo\fR is a pointer to an argument of type \fBint\fR. Non-connection RPC
107 transports ignore \fBRPC_SVC_CONNMAXREC_SET\fR and
108 \fBRPC_SVC_CONNMAXREC_GET\fR.
109 .SH RETURN VALUES
110 .LP
111 This routine returns \fBTRUE\fR if the operation was successful and
112 returns \fBFALSE\fR otherwise.
113 .SH ATTRIBUTES
114 .LP
115 See \fBattributes\fR(5) for descriptions of the following attributes:
116 .sp
118 .sp
119 .TS
120 box;
121 c | c
122 l | l .
123 ATTRIBUTE TYPE ATTRIBUTE VALUE
124 _
125 MT-Level MT-Safe
126 .TE
128 .SH SEE ALSO
129 .LP
130 \fBrpcbind\fR(1M), \fBrpc\fR(3NSL), \fBrpc_svc_calls\fR(3NSL),
131 \fBattributes\fR(5)
132 .sp
133 .LP
134 \fINetwork Interfaces Programmer's Guide\fR