Print this page
4239 rpc_svc_calls(3nsl): Typo service service
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man3nsl/rpc_svc_calls.3nsl
+++ new/usr/src/man/man3nsl/rpc_svc_calls.3nsl
1 1 '\" te
2 2 .\" Copyright 1989 AT&T
3 3 .\" Copyright (C) 2004 Sun Microsystems, Inc. All Rights Reserved
4 4 .\" 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.
5 5 .\" 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.
6 6 .\" 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]
7 -.TH RPC_SVC_CALLS 3NSL "Jan 26, 2004"
7 +.TH RPC_SVC_CALLS 3NSL "Oct 28, 2013"
8 8 .SH NAME
9 9 rpc_svc_calls, svc_dg_enablecache, svc_done, svc_exit, svc_fdset, svc_freeargs,
10 10 svc_getargs, svc_getreq_common, svc_getreq_poll, svc_getreqset,
11 11 svc_getrpccaller, svc_max_pollfd, svc_pollfd, svc_run, svc_sendreply,
12 12 svc_getcallerucred, svc_fd_negotiate_ucred \- library routines for RPC servers
13 13 .SH SYNOPSIS
14 14 .LP
15 15 .nf
16 16 \fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lnsl\fR [ \fIlibrary\fR...]
17 17 #include <rpc/rpc.h>
18 18
19 19 \fBint\fR \fBsvc_dg_enablecache\fR(\fBSVCXPRT *\fR\fIxprt\fR, \fBconst uint_t\fR \fIcache_size\fR);
20 20 .fi
21 21
22 22 .LP
23 23 .nf
24 24 \fBint\fR \fBsvc_done\fR(\fBSVCXPRT *\fR\fIxprt\fR);
25 25 .fi
26 26
27 27 .LP
28 28 .nf
29 29 \fBvoid\fR \fBsvc_exit\fR(\fBvoid\fR);
30 30 .fi
31 31
32 32 .LP
33 33 .nf
34 34 \fBvoid\fR \fBsvc_fd_negotiate_ucred\fR(\fBint\fR \fIfd\fR);
35 35 .fi
36 36
37 37 .LP
38 38 .nf
39 39 \fBbool_t\fR \fBsvc_freeargs\fR(\fBconst SVCXPRT *\fR\fIxprt\fR, \fBconst txdrproc_t\fR \fIinproc\fR,
40 40 \fBcaddr_t\fR \fIin\fR);
41 41 .fi
42 42
43 43 .LP
44 44 .nf
45 45 \fBbool_t\fR \fBsvc_getargs\fR(\fBconst SVCXPRT *\fR\fIxprt\fR, \fBconst xdrproc_t\fR \fIinproc\fR,
46 46 \fBcaddr_t\fR \fIin\fR);
47 47 .fi
48 48
49 49 .LP
50 50 .nf
51 51 \fBint\fR \fBsvc_getcallerucred\fR(\fBconst SVCXPRT *\fR\fIxprt\fR, \fBucred_t **\fR\fIucred\fR);
52 52 .fi
53 53
54 54 .LP
55 55 .nf
56 56 \fBvoid\fR \fBsvc_getreq_common\fR(\fBconst int\fR \fIfd\fR);
57 57 .fi
58 58
59 59 .LP
60 60 .nf
61 61 \fBvoid\fR \fBsvc_getreqset\fR(\fBfd_set *\fR\fIrdfds\fR);
62 62 .fi
63 63
64 64 .LP
65 65 .nf
66 66 \fBvoid\fR \fBsvc_getreq_poll\fR(\fBstruct pollfd *\fR\fIpfdp\fR, \fBconst int\fR \fIpollretval\fR);
67 67 .fi
68 68
69 69 .LP
70 70 .nf
71 71 \fBstruct netbuf *\fR\fBsvc_getrpccaller\fR(\fBconst SVCXPRT *\fR\fIxprt\fR);
72 72 .fi
73 73
74 74 .LP
75 75 .nf
76 76 \fBvoid\fR \fBsvc_run\fR(\fBvoid\fR);
77 77 .fi
78 78
79 79 .LP
80 80 .nf
81 81 \fBbool_t\fR \fBsvc_sendreply\fR(\fBconst SVCXPRT *\fR\fIxprt\fR, \fBconst xdrproc_t\fR \fIoutproc\fR,
82 82 \fBcaddr_t\fR \fIout\fRint svc_max_pollfd;
83 83 fd_set svc_fdset;
84 84 pollfd_t *svc_pollfd;
85 85 .fi
86 86
87 87 .SH DESCRIPTION
88 88 .sp
89 89 .LP
90 90 These routines are part of the \fBRPC\fR library which allows C language
91 91 programs to make procedure calls on other machines across the network.
92 92 .sp
93 93 .LP
94 94 These routines are associated with the server side of the \fBRPC\fR mechanism.
95 95 Some of them are called by the server side dispatch function. Others, such as
96 96 \fBsvc_run()\fR, are called when the server is initiated.
97 97 .sp
98 98 .LP
99 99 Because the service transport handle \fBSVCXPRT\fR contains a single data area
100 100 for decoding arguments and encoding results, the structure cannot freely be
101 101 shared between threads that call functions to decode arguments and encode
102 102 results. When a server is operating in the Automatic or User MT modes, however,
103 103 a copy of this structure is passed to the service dispatch procedure in order
104 104 to enable concurrent request processing. Under these circumstances, some
105 105 routines which would otherwise be Unsafe, become Safe. These are marked as
106 106 such. Also marked are routines that are Unsafe for multithreaded applications,
107 107 and are not to be used by such applications. See \fBrpc\fR(3NSL) for the
108 108 definition of the \fBSVCXPRT\fR data structure.
109 109 .sp
110 110 .LP
111 111 The \fBsvc_dg_enablecache()\fR function allocates a duplicate request cache for
112 112 the service endpoint \fIxprt\fR, large enough to hold \fIcache_size\fR entries.
113 113 Once enabled, there is no way to disable caching. The function returns \fB1\fR
114 114 if space necessary for a cache of the given size was successfully allocated,
115 115 and \fB0\fR otherwise. This function is Safe in multithreaded applications.
116 116 .sp
117 117 .LP
118 118 The \fBsvc_done()\fR function frees resources allocated to service a client
119 119 request directed to the service endpoint \fIxprt\fR. This call pertains only to
120 120 servers executing in the User MT mode. In the User MT mode, service procedures
121 121 must invoke this call before returning, either after a client request has been
122 122 serviced, or after an error or abnormal condition that prevents a reply from
123 123 being sent. After \fBsvc_done\fR() is invoked, the service endpoint \fIxprt\fR
124 124 should not be referenced by the service procedure. Server multithreading modes
125 125 and parameters can be set using the \fBrpc_control\fR() call. This function is
126 126 Safe in multithreaded applications. It will have no effect if invoked in modes
127 127 other than the User MT mode.
128 128 .sp
129 129 .LP
130 130 The \fBsvc_exit()\fR function when called by any of the RPC server procedures
131 131 or otherwise, destroys all services registered by the server and causes
132 132 \fBsvc_run()\fR to return. If RPC server activity is to be resumed, services
133 133 must be reregistered with the RPC library either through one of the
134 134 \fBrpc_svc_create\fR(3NSL) functions, or using \fBxprt_register\fR(3NSL). The
135 135 \fBsvc_exit()\fR function has global scope and ends all RPC server activity.
136 136 .sp
137 137 .LP
138 138 The \fBsvc_freeargs()\fR function macro frees any data allocated by the
139 139 \fBRPC/XDR\fR system when it decoded the arguments to a service procedure using
140 140 \fBsvc_getargs()\fR. This routine returns \fBTRUE\fR if the results were
141 141 successfully freed, and \fBFALSE\fR otherwise. This function macro is Safe in
142 142 multithreaded applications utilizing the Automatic or User MT modes.
143 143 .sp
144 144 .LP
145 145 The \fBsvc_getargs()\fR function macro decodes the arguments of an \fBRPC\fR
146 146 request associated with the \fBRPC\fR service transport handle \fIxprt\fR. The
147 147 parameter \fIin\fR is the address where the arguments will be placed;
148 148 \fIinproc\fR is the \fBXDR\fR routine used to decode the arguments. This
149 149 routine returns \fBTRUE\fR if decoding succeeds, and \fBFALSE\fR otherwise.
150 150 This function macro is Safe in multithreaded applications utilizing the
151 151 Automatic or User MT modes.
152 152 .sp
153 153 .LP
154 154 The \fBsvc_getreq_common()\fR function is called to handle a request on a file
155 155 descriptor.
156 156 .sp
157 157 .LP
158 158 The \fBsvc_getreq_poll()\fR function is only of interest if a service
159 159 implementor does not call \fBsvc_run()\fR, but instead implements custom
160 160 asynchronous event processing. It is called when \fBpoll\fR(2) has determined
161 161 that an RPC request has arrived on some RPC file descriptors; \fIpollretval\fR
162 162 is the return value from \fBpoll\fR(2) and \fIpfdp\fR is the array of
163 163 \fIpollfd\fR structures on which the \fBpoll\fR(2) was done. It is assumed to
164 164 be an array large enough to contain the maximal number of descriptors allowed.
165 165 The \fBsvc_getreq_poll()\fR function macro is Unsafe in multithreaded
166 166 applications.
167 167 .sp
168 168 .LP
169 169 The \fBsvc_getreqset()\fR function is only of interest if a service implementor
170 170 does not call \fBsvc_run()\fR, but instead implements custom asynchronous event
171 171 processing. It is called when \fBselect\fR(3C) has determined that an \fBRPC\fR
172 172 request has arrived on some \fBRPC\fR file descriptors; \fIrdfds\fR is the
173 173 resultant read file descriptor bit mask. The routine returns when all file
174 174 descriptors associated with the value of \fIrdfds\fR have been serviced. This
175 175 function macro is Unsafe in multithreaded applications.
176 176 .sp
177 177 .LP
178 178 The \fBsvc_getrpccaller()\fR function is the approved way of getting the
179 179 network address of the caller of a procedure associated with the \fBRPC\fR
180 180 service transport handle \fIxprt\fR. This function macro is Safe in
181 181 multithreaded applications.
182 182 .sp
183 183 .LP
184 184 The \fBsvc_run()\fR function never returns. In single-threaded mode, the
185 185 function waits for \fBRPC\fR requests to arrive. When an RPC request arrives,
186 186 the \fBsvc_run()\fR function calls the appropriate service procedure. This
187 187 procedure is usually waiting for the \fBpoll\fR(2) library call to return.
188 188 .sp
189 189 .LP
190 190 Applications that execute in the Automatic or the User MT mode should invoke
191 191 the \fBsvc_run()\fR function exactly once. In the Automatic MT mode, the
192 192 \fBsvc_run()\fR function creates threads to service client requests. In the
193 193 User MT mode, the function provides a framework for service developers to
194 194 create and manage their own threads for servicing client requests.
195 195 .sp
196 196 .LP
197 197 The \fBsvc_fdset\fR global variable reflects the \fBRPC\fR server's read file
198 198 descriptor bit mask. This is only of interest if service implementors do not
199 199 call \fBsvc_run()\fR, but rather do their own asynchronous event processing.
200 200 This variable is read-only may change after calls to \fBsvc_getreqset()\fR or
|
↓ open down ↓ |
183 lines elided |
↑ open up ↑ |
201 201 after any creation routine. Do not pass its address to \fBselect\fR(3C).
202 202 Instead, pass the address of a copy. multithreaded applications executing in
203 203 either the Automatic MT mode or the user MT mode should never read this
204 204 variable. They should use auxiliary threads to do asynchronous event
205 205 processing. The \fBsvc_fdset\fR variable is limited to 1024 file descriptors
206 206 and is considered obsolete. Use of \fBsvc_pollfd\fR is recommended instead.
207 207 .sp
208 208 .LP
209 209 The \fBsvc_pollfd\fR global variable points to an array of \fBpollfd_t\fR
210 210 structures that reflect the \fBRPC\fR server's read file descriptor array. This
211 -is only of interest if service service implementors do not call \fBsvc_run()\fR
211 +is only of interest if service implementors do not call \fBsvc_run()\fR
212 212 but rather do their own asynchronous event processing. This variable is
213 213 read-only, and it may change after calls to \fBsvc_getreg_poll()\fR or any
214 214 creation routines. Do no pass its address to \fBpoll\fR(2). Instead, pass the
215 215 address of a copy. By default, \fBsvc_pollfd\fR is limited to 1024 entries. Use
216 216 \fBrpc_control\fR(3NSL) to remove this limitation. multithreaded applications
217 217 executing in either the Automatic MT mode or the user MT mode should never be
218 218 read this variable. They should use auxiliary threads to do asynchronous event
219 219 processing.
220 220 .sp
221 221 .LP
222 222 The \fBsvc_max_pollfd\fR global variable contains the maximum length of the
223 223 \fBsvc_pollfd\fR array. This variable is read-only, and it may change after
224 224 calls to \fBsvc_getreg_poll()\fR or any creation routines.
225 225 .sp
226 226 .LP
227 227 The \fBsvc_sendreply()\fR function is called by an \fBRPC\fR service dispatch
228 228 routine to send the results of a remote procedure call. The \fIxprt\fR
229 229 parameter is the transport handle of the request. The \fIoutproc\fR parameter
230 230 is the \fBXDR\fR routine used to encode the results. The \fIout\fR parameter is
231 231 the address of the results. This routine returns \fBTRUE\fR if it succeeds,
232 232 \fBFALSE\fR otherwise. The \fBsvc_sendreply()\fR function macro is Safe in
233 233 multithreaded applications that use the Automatic or the User MT mode.
234 234 .sp
235 235 .LP
236 236 The \fBsvc_fd_negotiate_ucred()\fR function is called by an RPC server to
237 237 inform the underlying transport that the function wishes to receive
238 238 \fBucreds\fR for local calls, including those over IP transports.
239 239 .sp
240 240 .LP
241 241 The \fBsvc_getcallerucred()\fR function attempts to retrieve the \fBucred_t\fR
242 242 associated with the caller. The function returns \fB\fR0 when successful and
243 243 \fB-1\fR when not.
244 244 .sp
245 245 .LP
246 246 When successful, the \fBsvc_getcallerucred()\fR function stores the pointer to
247 247 a freshly allocated \fBucred_t\fR in the memory location pointed to by the
248 248 \fIucred\fR argument if that memory location contains the null pointer. If the
249 249 memory location is non-null, the function reuses the existing \fBucred_t\fR.
250 250 When \fIucred\fR is no longer needed, a credential allocated by
251 251 \fBsvc_getcallerucred()\fR should be freed with \fBucred_free\fR(3C).
252 252 .SH ATTRIBUTES
253 253 .sp
254 254 .LP
255 255 See \fBattributes\fR(5) for descriptions of attribute types and values.
256 256 .sp
257 257
258 258 .sp
259 259 .TS
260 260 box;
261 261 c | c
262 262 l | l .
263 263 ATTRIBUTE TYPE ATTRIBUTE VALUE
264 264 _
265 265 MT-Level See below.
266 266 .TE
267 267
268 268 .sp
269 269 .LP
270 270 The \fBsvc_fd_negotiate_ucred()\fR, \fBsvc_dg_enablecache()\fR,
271 271 \fBsvc_getrpccaller()\fR, and \fBsvc_getcallerucred()\fR functions are Safe in
272 272 multithreaded applications. The \fBsvc_freeargs()\fR, \fBsvc_getargs()\fR, and
273 273 \fBsvc_sendreply()\fR functions are Safe in multithreaded applications that use
274 274 the Automatic or the User MT mode. The \fBsvc_getreq_common()\fR,
275 275 \fBsvc_getreqset()\fR, and \fBsvc_getreq_poll()\fR functions are Unsafe in
276 276 multithreaded applications and should be called only from the main thread.
277 277 .SH SEE ALSO
278 278 .sp
279 279 .LP
280 280 \fBrpcgen\fR(1), \fBpoll\fR(2), \fBgetpeerucred\fR(3C), \fBrpc\fR(3NSL),
281 281 \fBrpc_control\fR(3NSL), \fBrpc_svc_create\fR(3NSL), \fBrpc_svc_err\fR(3NSL),
282 282 \fBrpc_svc_reg\fR(3NSL), \fBselect\fR(3C), \fBucred_free\fR(3C),
283 283 \fBxprt_register\fR(3NSL), \fBattributes\fR(5)
|
↓ open down ↓ |
62 lines elided |
↑ open up ↑ |
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX