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