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 33 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 . 402 ATTRIBUTE TYPE ATTRIBUTE VALUE 403 _ 404 Architecture All 405 _ 406 Interface Stability Evolving 407 _ 408 MT-Level MT-Safe 409 .TE 410 411 .SH SEE ALSO 412 .LP 413 \fBrpcbind\fR(1M), \fBrpc\fR(3NSL), \fBrpc_clnt_create\fR(3NSL), 414 \fBrpc_svc_calls\fR(3NSL), \fBrpc_svc_err\fR(3NSL), \fBrpc_svc_reg\fR(3NSL), 415 \fBattributes\fR(5)