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