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