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 32 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 . 376 ATTRIBUTE TYPE ATTRIBUTE VALUE 377 _ 378 Architecture All 379 _ 380 Interface Stability Evolving 381 _ 382 MT-Level MT-Safe 383 .TE 384 385 .SH SEE ALSO 386 .LP 387 \fBrpcbind\fR(1M), \fBrpc\fR(3NSL), \fBrpc_clnt_create\fR(3NSL), 388 \fBrpc_svc_calls\fR(3NSL), \fBrpc_svc_err\fR(3NSL), \fBrpc_svc_reg\fR(3NSL), 389 \fBattributes\fR(5)