Print this page
4344 Minor typos in the 3nsl man pages
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man3nsl/rpc_svc_create.3nsl
+++ new/usr/src/man/man3nsl/rpc_svc_create.3nsl
1 1 '\" te
2 2 .\" Copyright 1989 AT&T
3 3 .\" Copyright (C) 2005, 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_CREATE 3NSL "Mar 22, 2005"
7 +.TH RPC_SVC_CREATE 3NSL "Dec 27, 2013"
8 8 .SH NAME
9 9 rpc_svc_create, svc_control, svc_create, svc_destroy, svc_dg_create,
10 10 svc_fd_create, svc_raw_create, svc_tli_create, svc_tp_create, svc_vc_create,
11 11 svc_door_create \- server handle creation routines
12 12 .SH SYNOPSIS
13 13 .LP
14 14 .nf
15 15 #include <rpc/rpc.h>
16 16
17 17 \fBbool_t\fR \fBsvc_control\fR(\fBSVCXPRT *\fR\fIsvc\fR, \fBconst uint_t\fR \fIreq\fR, \fBvoid *\fR\fIinfo\fR);
18 18 .fi
19 19
20 20 .LP
21 21 .nf
22 -\fBint\fR \fBsvc_create\fR(\fBconst void (*\fR\fIdispatch\fR)const struct svc_req *,
23 - const SVCXPRT *, \fBconst rpcprog_t\fR \fIprognum\fR, \fBconst rpcvers_t\fR \fIversnum\fR,
22 +\fBint\fR \fBsvc_create\fR(\fBconst void (*\fR\fIdispatch\fR)(const struct svc_req *,
23 + const SVCXPRT *), \fBconst rpcprog_t\fR \fIprognum\fR, \fBconst rpcvers_t\fR \fIversnum\fR,
24 24 \fBconst char *\fR\fInettype\fR);
25 25 .fi
26 26
27 27 .LP
28 28 .nf
29 29 \fBvoid\fR \fBsvc_destroy\fR(\fBSVCXPRT *\fR\fIxprt\fR);
30 30 .fi
31 31
32 32 .LP
33 33 .nf
34 34 \fBSVCXPRT *\fR\fBsvc_dg_create\fR(\fBconst int\fR \fIfildes\fR, \fBconst uint_t\fR \fIsendsz\fR,
35 35 \fBconst uint_t\fR \fIrecvsz\fR);
36 36 .fi
37 37
38 38 .LP
39 39 .nf
40 40 \fBSVCXPRT *\fR\fBsvc_fd_create\fR(\fBconst int\fR \fIfildes\fR, \fBconst uint_t\fR \fIsendsz\fR,
41 41 \fBconst uint_t\fR \fIrecvsz\fR);
42 42 .fi
43 43
44 44 .LP
45 45 .nf
46 46 \fBSVCXPRT *\fR\fBsvc_raw_create\fR(void)
47 47 .fi
48 48
|
↓ open down ↓ |
15 lines elided |
↑ open up ↑ |
49 49 .LP
50 50 .nf
51 51 \fBSVCXPRT *\fR\fBsvc_tli_create\fR(\fBconst int\fR \fIfildes\fR, \fBconst struct netconfig *\fR\fInetconf\fR,
52 52 \fBconst struct t_bind *\fR\fIbind_addr\fR, \fBconst uint_t\fR \fIsendsz\fR,
53 53 \fBconst uint_t\fR \fIrecvsz\fR);
54 54 .fi
55 55
56 56 .LP
57 57 .nf
58 58 \fBSVCXPRT *\fR\fBsvc_tp_create\fR(\fBconst void (*\fR\fIdispatch\fR)
59 - const struct svc_req *, const SVCXPRT *), \fBconst rpcprog_t\fR \fIprognum\fR,
59 + (const struct svc_req *, const SVCXPRT *), \fBconst rpcprog_t\fR \fIprognum\fR,
60 60 \fBconst rpcvers_t\fR \fIversnum\fR, \fBconst struct netconfig *\fR\fInetconf\fR);
61 61 .fi
62 62
63 63 .LP
64 64 .nf
65 65 \fBSVCXPRT *\fR\fBsvc_vc_create\fR(\fBconst int\fR \fIfildes\fR, \fBconst uint_t\fR \fIsendsz\fR,
66 66 \fBconst uint_t\fR \fIrecvsz\fR);
67 67 .fi
68 68
69 69 .LP
70 70 .nf
71 71 \fBSVCXPRT *\fR\fBsvc_door_create\fR(\fBvoid (*\fR\fIdispatch\fR)(struct svc_req *, SVCXPRT *),
72 72 \fBconst rpcprog_t\fR \fIprognum\fR, \fBconst rpcvers_t\fR \fIversnum\fR,
73 73 \fBconst uint_t\fR \fIsendsz\fR);
74 74 .fi
75 75
76 76 .SH DESCRIPTION
77 77 .sp
78 78 .LP
79 79 These routines are part of the \fBRPC\fR library which allows C language
80 80 programs to make procedure calls on servers across the network. These routines
81 81 deal with the creation of service handles. Once the handle is created, the
82 82 server can be invoked by calling \fBsvc_run()\fR.
83 83 .SS "Routines"
84 84 .sp
85 85 .LP
86 86 See \fBrpc\fR(3NSL) for the definition of the \fBSVCXPRT\fR data structure.
87 87 .sp
88 88 .ne 2
89 89 .na
90 90 \fB\fBsvc_control()\fR\fR
91 91 .ad
92 92 .RS 21n
93 93 A function to change or retrieve information about a service object. \fIreq\fR
94 94 indicates the type of operation and \fIinfo\fR is a pointer to the information.
95 95 The supported values of \fIreq\fR, their argument types, and what they do are:
96 96 .sp
97 97 .ne 2
98 98 .na
99 99 \fB\fBSVCGET_VERSQUIET\fR\fR
100 100 .ad
101 101 .RS 25n
102 102 If a request is received for a program number served by this server but the
103 103 version number is outside the range registered with the server, an
104 104 \fBRPC_PROGVERSMISMATCH\fR error will normally be returned. \fIinfo\fR should
105 105 be a pointer to an integer. Upon successful completion of the
106 106 \fBSVCGET_VERSQUIET\fR request, *\fIinfo\fR contains an integer which
107 107 describes the server's current behavior: \fB0\fR indicates normal server
108 108 behavior, that is, an \fBRPC_PROGVERSMISMATCH\fR error will be returned.
109 109 \fB1\fR indicates that the out of range request will be silently ignored.
110 110 .RE
111 111
112 112 .sp
113 113 .ne 2
114 114 .na
115 115 \fB\fBSVCSET_VERSQUIET\fR\fR
116 116 .ad
117 117 .RS 25n
118 118 If a request is received for a program number served by this server but the
119 119 version number is outside the range registered with the server, an
120 120 \fBRPC_PROGVERSMISMATCH\fR error will normally be returned. It is sometimes
121 121 desirable to change this behavior. \fIinfo\fR should be a pointer to an integer
122 122 which is either \fB0\fR, indicating normal server behavior and an
123 123 \fBRPC_PROGVERSMISMATCH\fR error will be returned, or \fB1\fR, indicating that
124 124 the out of range request should be silently ignored.
125 125 .RE
126 126
127 127 .sp
128 128 .ne 2
129 129 .na
130 130 \fB\fBSVCGET_XID\fR\fR
131 131 .ad
132 132 .RS 25n
133 133 Returns the transaction \fBID\fR of connection\(mioriented and connectionless
134 134 transport service calls. The transaction \fBID\fR assists in uniquely
135 135 identifying client requests for a given \fBRPC\fR version, program number,
136 136 procedure, and client. The transaction \fBID\fR is extracted from the service
137 137 transport handle \fIsvc\fR. \fIinfo\fR must be a pointer to an unsigned long.
138 138 Upon successful completion of the \fBSVCGET_XID\fR request, *\fIinfo\fR
139 139 contains the transaction \fBID\fR. Note that rendezvous and raw service
140 140 handles do not define a transaction \fBID\fR. Thus, if the service handle is
141 141 of rendezvous or raw type, and the request is of type \fBSVCGET_XID,\fR
142 142 \fBsvc_control()\fR will return \fBFALSE\fR. Note also that the transaction
143 143 \fBID\fR read by the server can be set by the client through the suboption
144 144 \fBCLSET_XID\fR in \fBclnt_control()\fR. See \fBclnt_create\fR(3NSL)
145 145 .RE
146 146
147 147 .sp
148 148 .ne 2
149 149 .na
150 150 \fB\fBSVCSET_RECVERRHANDLER\fR\fR
151 151 .ad
152 152 .RS 25n
153 153 Attaches or detaches a disconnection handler to the service handle, \fIsvc\fR,
154 154 that will be called when a transport error arrives during the reception of a
155 155 request or when the server is waiting for a request and the connection shuts
156 156 down. This handler is only useful for a connection oriented service handle.
157 157 .sp
158 158 \fI*info\fR contains the address of the error handler to attach, or \fINULL\fR
159 159 to detach a previously defined one. The error handler has two arguments. It has
160 160 a pointer to the erroneous service handle. It also has an integer that
161 161 indicates if the full service is closed (when equal to zero), or that only one
162 162 connection on this service is closed (when not equal to zero).
163 163 .sp
164 164 .in +2
165 165 .nf
166 166 void handler (const SVCXPRT *svc, const bool_t isAConnection);
167 167 .fi
168 168 .in -2
169 169
170 170 With the service handle address, \fIsvc\fR, the error handler is able to detect
171 171 which connection has failed and to begin an error recovery process. The error
172 172 handler can be called by multiple threads and should be implemented in an
173 173 MT-safe way.
174 174 .RE
175 175
176 176 .sp
177 177 .ne 2
178 178 .na
179 179 \fB\fBSVCGET_RECVERRHANDLER\fR\fR
180 180 .ad
181 181 .RS 25n
182 182 Upon successful completion of the \fBSVCGET_RECVERRHANDLER\fR request,
183 183 \fI*info\fR contains the address of the handler for receiving errors. Upon
184 184 failure, \fI*info\fR contains \fINULL\fR.
185 185 .RE
186 186
187 187 .sp
188 188 .ne 2
189 189 .na
190 190 \fB\fBSVCSET_CONNMAXREC\fR\fR
191 191 .ad
192 192 .RS 25n
193 193 Set the maximum record size (in bytes) and enable non-blocking mode for this
194 194 service handle. Value can be set and read for both connection and
195 195 non-connection oriented transports, but is silently ignored for the
196 196 non-connection oriented case. The \fIinfo\fR argument should be a pointer to an
197 197 \fBint\fR.
198 198 .RE
199 199
200 200 .sp
201 201 .ne 2
202 202 .na
203 203 \fB\fBSVCGET_CONNMAXREC\fR\fR
204 204 .ad
205 205 .RS 25n
206 206 Get the maximum record size for this service handle. Zero means no maximum in
207 207 effect and the connection is in blocking mode. The result is not significant
208 208 for non-connection oriented transports. The \fIinfo\fR argument should be a
209 209 pointer to an \fBint\fR.
210 210 .RE
211 211
212 212 This routine returns TRUE if the operation was successful. Otherwise, it
213 213 returns false.
214 214 .RE
215 215
216 216 .sp
217 217 .ne 2
218 218 .na
219 219 \fB\fBsvc_create()\fR\fR
220 220 .ad
221 221 .RS 21n
222 222 \fBsvc_create()\fR creates server handles for all the transports belonging to
223 223 the class \fInettype\fR.
224 224 .sp
225 225 \fInettype\fR defines a class of transports which can be used for a particular
226 226 application. The transports are tried in left to right order in \fBNETPATH\fR
227 227 variable or in top to bottom order in the netconfig database. If \fInettype\fR
228 228 is \fINULL,\fR it defaults to \fBnetpath\fR.
229 229 .sp
230 230 \fBsvc_create()\fR registers itself with the \fBrpcbind\fR service (see
231 231 \fBrpcbind\fR(1M)). \fIdispatch\fR is called when there is a remote procedure
232 232 call for the given \fIprognum\fR and \fIversnum\fR; this requires calling
233 233 \fBsvc_run()\fR (see \fBsvc_run()\fR in \fBrpc_svc_reg\fR(3NSL)). If
234 234 \fBsvc_create()\fR succeeds, it returns the number of server handles it
235 235 created, otherwise it returns \fB0\fR and an error message is logged.
236 236 .RE
237 237
238 238 .sp
239 239 .ne 2
240 240 .na
241 241 \fB\fBsvc_destroy()\fR\fR
242 242 .ad
243 243 .RS 21n
244 244 A function macro that destroys the \fBRPC\fR service handle \fIxprt\fR.
245 245 Destruction usually involves deallocation of private data structures, including
246 246 \fIxprt\fR itself. Use of \fIxprt\fR is undefined after calling this routine.
247 247 .RE
248 248
249 249 .sp
250 250 .ne 2
251 251 .na
252 252 \fB\fBsvc_dg_create()\fR\fR
253 253 .ad
254 254 .RS 21n
255 255 This routine creates a connectionless \fBRPC\fR service handle, and returns a
256 256 pointer to it. This routine returns \fINULL\fR if it fails, and an error
257 257 message is logged. \fIsendsz\fR and \fIrecvsz\fR are parameters used to specify
258 258 the size of the buffers. If they are \fB0\fR, suitable defaults are chosen. The
259 259 file descriptor \fIfildes\fR should be open and bound. The server is not
260 260 registered with \fBrpcbind\fR(1M).
261 261 .sp
262 262 Warning: since connectionless-based \fBRPC\fR messages can only hold limited
263 263 amount of encoded data, this transport cannot be used for procedures that take
264 264 large arguments or return huge results.
265 265 .RE
266 266
267 267 .sp
268 268 .ne 2
269 269 .na
270 270 \fB\fBsvc_fd_create()\fR\fR
271 271 .ad
272 272 .RS 21n
273 273 This routine creates a service on top of an open and bound file descriptor, and
274 274 returns the handle to it. Typically, this descriptor is a connected file
275 275 descriptor for a connection-oriented transport. \fIsendsz\fR and \fIrecvsz\fR
276 276 indicate sizes for the send and receive buffers. If they are \fB0\fR,
277 277 reasonable defaults are chosen. This routine returns \fINULL\fR if it fails,
278 278 and an error message is logged.
279 279 .RE
280 280
281 281 .sp
282 282 .ne 2
283 283 .na
284 284 \fB\fBsvc_raw_create()\fR\fR
285 285 .ad
286 286 .RS 21n
287 287 This routine creates an \fBRPC\fR service handle and returns a pointer to it.
288 288 The transport is really a buffer within the process's address space, so the
289 289 corresponding \fBRPC\fR client should live in the same address space; (see
290 290 \fBclnt_raw_create()\fR in \fBrpc_clnt_create\fR(3NSL)). This routine allows
291 291 simulation of \fBRPC\fR and acquisition of \fBRPC\fR overheads (such as round
292 292 trip times), without any kernel and networking interference. This routine
293 293 returns \fINULL\fR if it fails, and an error message is logged.
294 294 .sp
295 295 Note: \fBsvc_run()\fR should not be called when the raw interface is being
296 296 used.
297 297 .RE
298 298
299 299 .sp
300 300 .ne 2
301 301 .na
302 302 \fB\fBsvc_tli_create()\fR\fR
303 303 .ad
304 304 .RS 21n
305 305 This routine creates an \fBRPC\fR server handle, and returns a pointer to it.
306 306 \fIfildes\fR is the file descriptor on which the service is listening. If
307 307 \fIfildes\fR is \fBRPC_ANYFD\fR, it opens a file descriptor on the transport
308 308 specified by \fInetconf\fR. If the file descriptor is unbound and
309 309 \fIbindaddr\fR is non-null \fIfildes\fR is bound to the address specified by
310 310 \fIbindaddr\fR, otherwise \fIfildes\fR is bound to a default address chosen by
311 311 the transport. In the case where the default address is chosen, the number of
312 312 outstanding connect requests is set to 8 for connection-oriented transports.
313 313 The user may specify the size of the send and receive buffers with the
314 314 parameters \fIsendsz\fR and \fIrecvsz\fR \fI;\fR values of \fB0\fR choose
315 315 suitable defaults. This routine returns \fINULL\fR if it fails, and an error
316 316 message is logged. The server is not registered with the \fBrpcbind\fR(1M)
317 317 service.
318 318 .RE
319 319
320 320 .sp
321 321 .ne 2
322 322 .na
323 323 \fB\fBsvc_tp_create()\fR\fR
324 324 .ad
325 325 .RS 21n
326 326 \fBsvc_tp_create()\fR creates a server handle for the network specified by
327 327 \fInetconf\fR, and registers itself with the \fBrpcbind\fR service.
328 328 \fIdispatch\fR is called when there is a remote procedure call for the given
329 329 \fIprognum\fR and \fIversnum\fR; this requires calling \fBsvc_run()\fR.
330 330 \fBsvc_tp_create()\fR returns the service handle if it succeeds, otherwise a
331 331 \fINULL\fR is returned and an error message is logged.
332 332 .RE
333 333
334 334 .sp
335 335 .ne 2
336 336 .na
337 337 \fB\fBsvc_vc_create()\fR\fR
338 338 .ad
339 339 .RS 21n
340 340 This routine creates a connection-oriented \fBRPC\fR service and returns a
341 341 pointer to it. This routine returns \fINULL\fR if it fails, and an error
342 342 message is logged. The users may specify the size of the send and receive
343 343 buffers with the parameters \fIsendsz\fR and \fIrecvsz\fR; values of \fB0\fR
344 344 choose suitable defaults. The file descriptor \fIfildes\fR should be open and
345 345 bound. The server is not registered with the \fBrpcbind\fR(1M) service.
346 346 .RE
347 347
348 348 .sp
349 349 .ne 2
350 350 .na
351 351 \fB\fBsvc_door_create()\fR\fR
352 352 .ad
353 353 .RS 21n
354 354 This routine creates an RPC server handle over doors and returns a pointer to
355 355 it. Doors is a transport mechanism that facilitates fast data transfer between
356 356 processes on the same machine. for the given program The user may set the size
357 357 of the send buffer with the parameter \fIsendsz\fR. If \fIsendsz\fR is 0, the
358 358 corresponding default buffer size is 16 Kbyte. If successful, the
359 359 \fBsvc_door_create()\fR routine returns the service handle. Otherwise it
360 360 returns \fINULL\fR and sets a value for \fBrpc_createerr\fR. The server is not
361 361 registered with \fBrpcbind\fR(1M). The \fBSVCSET_CONNMAXREC\fR and
362 362 \fBSVCGET_CONNMAXREC\fR \fBsvc_control()\fR requests can be used to set and
363 363 change the maximum allowed request size for the doors transport.
364 364 .RE
365 365
366 366 .SH ATTRIBUTES
367 367 .sp
368 368 .LP
369 369 See \fBattributes\fR(5) for descriptions of the following attributes:
370 370 .sp
371 371
372 372 .sp
373 373 .TS
374 374 box;
375 375 c | c
376 376 l | l .
377 377 ATTRIBUTE TYPE ATTRIBUTE VALUE
378 378 _
379 379 Architecture All
380 380 _
381 381 Interface Stability Evolving
382 382 _
383 383 MT-Level MT-Safe
384 384 .TE
385 385
386 386 .SH SEE ALSO
387 387 .sp
388 388 .LP
389 389 \fBrpcbind\fR(1M), \fBrpc\fR(3NSL), \fBrpc_clnt_create\fR(3NSL),
390 390 \fBrpc_svc_calls\fR(3NSL), \fBrpc_svc_err\fR(3NSL), \fBrpc_svc_reg\fR(3NSL),
391 391 \fBattributes\fR(5)
|
↓ open down ↓ |
322 lines elided |
↑ open up ↑ |
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX