1 '\" te
   2 .\"  Copyright 1989 AT&T
   3 .\" Copyright (C) 2009, 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. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
   5 .\"  See the License for the specific language governing permissions and limitations under the License. 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
   6 .\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   7 .TH RPC_CLNT_CREATE 3NSL "Jul 23, 2009"
   8 .SH NAME
   9 rpc_clnt_create, clnt_control, clnt_create, clnt_create_timed,
  10 clnt_create_vers, clnt_create_vers_timed, clnt_destroy, clnt_dg_create,
  11 clnt_pcreateerror, clnt_raw_create, clnt_spcreateerror, clnt_tli_create,
  12 clnt_tp_create, clnt_tp_create_timed, clnt_vc_create, rpc_createerr,
  13 clnt_door_create \- library routines for dealing with creation and manipulation
  14 of CLIENT handles
  15 .SH SYNOPSIS
  16 .LP
  17 .nf
  18 #include <rpc/rpc.h>
  19 
  20 \fBbool_t\fR \fBclnt_control\fR(\fBCLIENT *\fR\fIclnt\fR, \fBconst uint_t\fR \fIreq\fR, \fBchar *\fR\fIinfo\fR);
  21 .fi
  22 
  23 .LP
  24 .nf
  25 \fBCLIENT *\fR\fBclnt_create\fR(\fBconst char *\fR\fIhost\fR, \fBconst rpcprog_t\fR \fIprognum\fR,
  26      \fBconst rpcvers_t\fR \fIversnum\fR, \fBconst char *\fR\fInettype\fR);
  27 .fi
  28 
  29 .LP
  30 .nf
  31 \fBCLIENT *\fR\fBclnt_create_timed\fR(\fBconst char *\fR\fIhost\fR, \fBconst rpcprog_t\fR \fIprognum\fR,
  32      \fBconst rpcvers_t\fR \fIversnum\fR, \fBconst\fR \fInettype\fR,
  33      \fBconst struct timeval *\fR\fItimetout\fR);
  34 .fi
  35 
  36 .LP
  37 .nf
  38 \fBCLIENT *\fR\fBclnt_create_vers\fR (\fBconst char *\fR\fIhost\fR,
  39      \fBconst rpcprog_t\fR \fIprognum\fR, \fBrpcvers_t *\fR\fIvers_outp\fR,
  40      \fBconst rpcvers_t\fR \fIvers_low\fR, \fBconst rpcvers_t\fR \fIvers_high\fR,
  41      \fBconst char *\fR\fInettype\fR);
  42 .fi
  43 
  44 .LP
  45 .nf
  46 \fBCLIENT *\fR\fBclnt_create_vers_timed\fR(\fBconst char *\fR\fIhost\fR,
  47      \fBconst rpcprog_t\fR \fIprognum\fR, \fBrpcvers_t *\fR\fIvers_outp\fR,
  48      \fBconst rpcvers_t\fR \fIvers_low\fR, \fBconst rpcvers_t\fR \fIvers_high\fR,
  49      \fBchar *\fR\fInettype\fR, \fBconst struct timeval *\fR\fItimeout\fR);
  50 .fi
  51 
  52 .LP
  53 .nf
  54 \fBvoid\fR \fBclnt_destroy\fR(\fBCLIENT *\fR\fIclnt\fR);
  55 .fi
  56 
  57 .LP
  58 .nf
  59 \fBCLIENT *\fR\fBclnt_dg_create\fR(\fBconst int\fR \fIfildes\fR,
  60      \fBconst struct netbuf *\fR\fIsvcaddr\fR, \fBconst rpcprog_t\fR \fIprognum\fR,
  61      \fBconst rpcvers_t\fR \fIversnum\fR, \fBconst uint_t\fR \fIsendsz\fR,
  62      \fBconst uint_t\fR \fIrecsz\fR);
  63 .fi
  64 
  65 .LP
  66 .nf
  67 \fBvoid\fR \fBclnt_pcreateerror\fR(\fBconst char *\fR\fIs\fR);
  68 .fi
  69 
  70 .LP
  71 .nf
  72 \fBCLIENT *\fR\fBclnt_raw_create\fR(\fBconst rpcprog_t\fR \fIprognum\fR,
  73      \fBconst rpcvers_t\fR \fIversnum\fR);
  74 .fi
  75 
  76 .LP
  77 .nf
  78 \fBchar *\fR\fBclnt_spcreateerror\fR(\fBconst char *\fR\fIs\fR);
  79 .fi
  80 
  81 .LP
  82 .nf
  83 \fBCLIENT *\fR\fBclnt_tli_create\fR(\fBconst int\fR \fIfildes\fR,
  84      \fBconst struct netconfig *\fR\fInetconf\fR, \fBconst struct netbuf *\fR\fIsvcaddr\fR,
  85      \fBconst rpcprog_t\fR \fIprognum\fR, \fBconst rpcvers_t\fR \fIversnum\fR,
  86      \fBconst uint_t\fR \fIsendsz\fR, \fBconst uint_t\fR \fIrecsz\fR);
  87 .fi
  88 
  89 .LP
  90 .nf
  91 \fBCLIENT *\fR\fBclnt_tp_create\fR(\fBconst char *\fR\fIhost\fR,
  92      \fBconst rpcprog_t\fR \fIprognum\fR, \fBconst rpcvers_t\fR \fIversnum\fR,
  93      \fBconst struct netconfig *\fR\fInetconf\fR);
  94 .fi
  95 
  96 .LP
  97 .nf
  98 \fBCLIENT *\fR\fBclnt_tp_create_timed\fR(\fBconst char *\fR\fIhost\fR,
  99      \fBconst rpcprog_t\fR \fIprognum\fR, \fBconst rpcvers_t\fR \fIversnum\fR,
 100      \fBconst struct netconfig *\fR\fInetconf\fR, \fBconst struct timeval *\fR\fItimeout\fR);
 101 .fi
 102 
 103 .LP
 104 .nf
 105 \fBCLIENT *\fR\fBclnt_vc_create\fR(\fBconst int\fR \fIfildes\fR,
 106      \fBconst struct netbuf *\fR\fIsvcaddr\fR, \fBconst rpcprog_t\fR \fIprognum\fR,
 107      \fBconst rpcvers_t\fR \fIversnum\fR, \fBconst uint_t\fR \fIsendsz\fR,
 108      \fBconst uint_t\fR \fIrecsz\fR);
 109 .fi
 110 
 111 .LP
 112 .nf
 113 \fBstruct rpc_createerr\fR \fBrpc_createerr\fR
 114 .fi
 115 
 116 .LP
 117 .nf
 118 \fBCLIENT *\fR\fBclnt_door_create\fR(\fBconst rpcprog_t\fR \fIprognum\fR,
 119      \fBconst rpcvers_t\fR \fIversnum\fR, \fBconst uint_t\fR \fIsendsz\fR);
 120 .fi
 121 
 122 .SH DESCRIPTION
 123 .sp
 124 .LP
 125 \fBRPC\fR library routines allow  \fBC\fR language programs to make procedure
 126 calls on other machines across the network. First a \fBCLIENT\fR handle is
 127 created and then the client calls a procedure to send a request to the server.
 128 On receipt of the request, the server calls a dispatch routine to perform the
 129 requested service, and then sends a reply.
 130 .sp
 131 .LP
 132 These routines are MT-Safe. In the case of multithreaded applications, the
 133 \fB-mt\fR option must be specified on the command line at compilation time.
 134 When the \fB-mt\fR option is specified, \fBrpc_createerr()\fR becomes a macro
 135 that enables each thread to have its own \fBrpc_createerr()\fR. See
 136 \fBthreads\fR(5).
 137 .SS "Routines"
 138 .sp
 139 .LP
 140 See \fBrpc\fR(3NSL) for the definition of the \fBCLIENT\fR data structure.
 141 .sp
 142 .ne 2
 143 .na
 144 \fB\fBclnt_control()\fR\fR
 145 .ad
 146 .sp .6
 147 .RS 4n
 148 A function macro to change or retrieve various information about a client
 149 object. \fIreq\fR indicates the type of operation, and \fIinfo\fR is a pointer
 150 to the information. For both connectionless and connection-oriented transports,
 151 the supported values of \fIreq\fR and their argument types and what they do
 152 are:
 153 .sp
 154 .in +2
 155 .nf
 156 CLSET_TIMEOUT struct timeval * set total timeout
 157 CLGET_TIMEOUT   struct timeval *        get total timeout
 158 .fi
 159 .in -2
 160 
 161 If the timeout is set using \fBclnt_control()\fR, the timeout argument passed
 162 by \fBclnt_call()\fR is ignored in all subsequent calls. If the timeout value
 163 is set to  \fB0\fR, \fBclnt_control()\fR immediately returns
 164 \fBRPC_TIMEDOUT\fR. Set the timeout parameter to  \fB0\fR for batching calls.
 165 .sp
 166 .in +2
 167 .nf
 168 CLGET_SERVER_ADDR struct netbuf * get server's address
 169 CLGET_SVC_ADDR  struct netbuf * get server's address
 170 CLGET_FD        int *   get associated file descriptor
 171 CLSET_FD_CLOSE  void    close the file descriptor when
 172                 destroying the client handle
 173                 (see \fBclnt_destroy()\fR)
 174 CLSET_FD_NCLOSE void    do not close the file
 175                 descriptor when destroying the client handle
 176 CLGET_VERS   rpcvers_t get the RPC program's version
 177                 number associated with the
 178                 client handle
 179 CLSET_VERS      rpcvers_t set the RPC program's version
 180                 number associated with the
 181                 client handle.  This assumes
 182                 that the RPC server for this
 183                 new version is still listening
 184                 at the address of the previous
 185                 version.
 186 CLGET_XID       uint32_t        get the XID of the previous
 187                 remote procedure call
 188 CLSET_XID       uint32_t        set the XID of the next
 189                 remote procedure call
 190 CLGET_PROG      rpcprog_t       get program number
 191 CLSET_PROG      rpcprog_t       set program number
 192 .fi
 193 .in -2
 194 
 195 The following operations are valid for connection-oriented transports only:
 196 .sp
 197 .in +2
 198 .nf
 199 CLSET_IO_MODE rpciomode_t*    set the IO mode used
 200                 to send one-way requests. The argument for this operation
 201                 can be either:
 202    - RPC_CL_BLOCKING    all sending operations block
 203                 until the underlying transport protocol has
 204                 accepted requests. If you specify this argument
 205                 you cannot use flush and getting and setting buffer
 206                 size is meaningless.
 207    - RPC_CL_NONBLOCKING   sending operations do not
 208                 block and return as soon as requests enter the buffer.
 209                 You can now use non-blocking I/O. The requests in the
 210                 buffer are pending. The requests are sent to
 211                 the server as soon as a two-way request is sent
 212                 or a flush is done. You are responsible for flushing
 213                 the buffer. When you choose RPC_CL_NONBLOCKING argument
 214                 you have a choice of flush modes as specified by
 215                 CLSET_FLUSH_MODE.
 216 CLGET_IO_MODE rpciomode_t*              get the current IO mode
 217 CLSET_FLUSH_MODE rpcflushmode_t*                set the flush mode.
 218                 The flush mode can only be used in non-blocking I/O mode.
 219                 The argument can be either of the following:    
 220         - RPC_CL_BESTEFFORT_FLUSH: All flushes send requests
 221                 in the buffer until the transport end-point blocks.
 222                 If the transport connection is congested, the call
 223                 returns directly.       
 224         - RPC_CL_BLOCKING_FLUSH: Flush blocks until the
 225                 underlying transport protocol accepts all pending
 226                 requests into the queue.
 227 CLGET_FLUSH_MODE rpcflushmode_t*        get the current flush mode.
 228 CLFLUSH rpcflushmode_t                  flush the pending requests.
 229                 This command can only be used in non-blocking I/O mode.
 230                 The flush policy depends on which of the following
 231                 parameters is specified:
 232         - RPC_CL_DEFAULT_FLUSH, or NULL:        The flush is done
 233            according to the current flush mode policy
 234                 (see CLSET_FLUSH_MODE option).
 235         - RPC_CL_BESTEFFORT_FLUSH:              The flush tries
 236                 to send pending requests without blocking; the call
 237                 returns directly. If the transport connection is
 238                 congested, this call could return without the request
 239                 being sent.
 240         - RPC_CL_BLOCKING_FLUSH:                The flush sends all pending
 241                 requests. This call will block until all the requests
 242                 have been accepted by the transport layer.
 243 CLSET_CONNMAXREC_SIZE int*    set the buffer size.
 244                 It is not possible to dynamically
 245                 resize the buffer if it contains data.
 246                 The default size of the buffer is 16 kilobytes.
 247 CLGET_CONNMAXREC_SIZE int*              get the current size of the
 248                 buffer
 249 CLGET_CURRENT_REC_SIZE int*             get the size of
 250                 the pending requests stored in the buffer. Use of this
 251                 command is only recommended when you are in non-blocking
 252                 I/O mode. The current size of the buffer is always zero
 253                 when the handle is in blocking mode as the buffer is not
 254                 used in this mode.
 255 .fi
 256 .in -2
 257 
 258 The following operations are valid for connectionless transports only:
 259 .sp
 260 .in +2
 261 .nf
 262 CLSET_RETRY_TIMEOUT  struct timeval *    set the retry timeout
 263 CLGET_RETRY_TIMEOUT  struct timeval *    get the retry timeout
 264 .fi
 265 .in -2
 266 
 267 The retry timeout is the time that \fBRPC\fR waits for the server to reply
 268 before retransmitting the request.
 269 .sp
 270 \fBclnt_control()\fR returns \fBTRUE\fR on success and \fBFALSE\fR on failure.
 271 .RE
 272 
 273 .sp
 274 .ne 2
 275 .na
 276 \fB\fBclnt_create()\fR\fR
 277 .ad
 278 .sp .6
 279 .RS 4n
 280 Generic client creation routine for program \fIprognum\fR and version
 281 \fIversnum\fR. \fIhost\fR identifies the name of the remote host where the
 282 server is located. \fInettype\fR indicates the class of transport protocol to
 283 use. The transports are tried in left to right order in \fBNETPATH\fR variable
 284 or in top to bottom order in the netconfig database.
 285 .sp
 286 \fBclnt_create()\fR tries all the transports of the \fInettype\fR class
 287 available from the \fBNETPATH\fR environment variable and the netconfig
 288 database, and chooses the first successful one. A default timeout is set and
 289 can be modified using \fBclnt_control()\fR. This routine returns \fINULL\fR if
 290 it fails. The \fBclnt_pcreateerror()\fR routine can be used to print the reason
 291 for failure.
 292 .sp
 293 Note that \fBclnt_create()\fR returns a valid client handle even if the
 294 particular version number supplied to \fBclnt_create()\fR is not registered
 295 with the \fBrpcbind\fR service. This mismatch will be discovered by a
 296 \fBclnt_call\fR later (see \fBrpc_clnt_calls\fR(3NSL)).
 297 .RE
 298 
 299 .sp
 300 .ne 2
 301 .na
 302 \fB\fBclnt_create_timed()\fR\fR
 303 .ad
 304 .sp .6
 305 .RS 4n
 306 Generic client creation routine which is similar to \fBclnt_create()\fR but
 307 which also has the additional parameter \fItimeout\fR that specifies the
 308 maximum amount of time allowed for each transport class tried. In all other
 309 respects, the \fBclnt_create_timed()\fR call behaves exactly like the
 310 \fBclnt_create()\fR call.
 311 .RE
 312 
 313 .sp
 314 .ne 2
 315 .na
 316 \fB\fBclnt_create_vers()\fR\fR
 317 .ad
 318 .sp .6
 319 .RS 4n
 320 Generic client creation routine which is similar to \fBclnt_create()\fR but
 321 which also checks for the version availability. \fIhost\fR identifies the name
 322 of the remote host where the server is located. \fInettype\fR indicates the
 323 class transport protocols to be used. If the routine is successful it returns a
 324 client handle created for the highest version between \fIvers_low\fR and
 325 \fIvers_high\fR that is supported by the server. \fIvers_outp\fR is set to this
 326 value. That is, after a successful return \fIvers_low\fR <= \fI*vers_outp\fR <=
 327 \fIvers_high\fR. If no version between \fIvers_low\fR and \fIvers_high\fR is
 328 supported by the server then the routine fails and returns \fBNULL.\fR A
 329 default timeout is set and can be modified using \fBclnt_control()\fR. This
 330 routine returns \fINULL\fR if it fails. The \fBclnt_pcreateerror()\fR routine
 331 can be used to print the reason for failure.
 332 .sp
 333 Note: \fBclnt_create()\fR returns a valid client handle even if the particular
 334 version number supplied to \fBclnt_create()\fR is not registered with the
 335 \fBrpcbind\fR service. This mismatch will be discovered by a \fBclnt_call\fR
 336 later (see \fBrpc_clnt_calls\fR(3NSL)). However, \fBclnt_create_vers()\fR does
 337 this for you and returns a valid handle only if a version within the range
 338 supplied is supported by the server.
 339 .RE
 340 
 341 .sp
 342 .ne 2
 343 .na
 344 \fB\fBclnt_create_vers_timed()\fR\fR
 345 .ad
 346 .sp .6
 347 .RS 4n
 348 Generic client creation routine similar to \fBclnt_create_vers()\fR but with
 349 the additional parameter  \fItimeout\fR, which specifies the maximum amount of
 350 time allowed for each transport class tried.   In all other respects, the
 351 \fBclnt_create_vers_timed()\fR call behaves exactly like the
 352 \fBclnt_create_vers()\fR call.
 353 .RE
 354 
 355 .sp
 356 .ne 2
 357 .na
 358 \fB\fBclnt_destroy()\fR\fR
 359 .ad
 360 .sp .6
 361 .RS 4n
 362 A function macro that destroys the client's \fBRPC\fR handle. Destruction
 363 usually involves deallocation of private data structures, including \fIclnt\fR
 364 itself. Use of \fIclnt\fR is undefined after calling \fBclnt_destroy()\fR. If
 365 the \fBRPC\fR library opened the associated file descriptor, or
 366 \fBCLSET_FD_CLOSE\fR was set using \fBclnt_control()\fR, the file descriptor
 367 will be closed.
 368 .sp
 369 The caller should call \fBauth_destroy(\fR\fIclnt\fR->\fBcl_auth)\fR (before
 370 calling \fBclnt_destroy()\fR) to destroy the associated \fBAUTH\fR structure
 371 (see \fBrpc_clnt_auth\fR(3NSL)).
 372 .RE
 373 
 374 .sp
 375 .ne 2
 376 .na
 377 \fB\fBclnt_dg_create()\fR\fR
 378 .ad
 379 .sp .6
 380 .RS 4n
 381 This routine creates an \fBRPC\fR client for the remote program \fIprognum\fR
 382 and version \fIversnum\fR; the client uses a connectionless transport. The
 383 remote program is located at address \fIsvcaddr\fR. The parameter \fIfildes\fR
 384 is an open and bound file descriptor. This routine will resend the call message
 385 in intervals of 15 seconds until a response is received or until the call times
 386 out. The total time for the call to time out is specified by \fBclnt_call()\fR
 387 (see \fBclnt_call()\fR in \fBrpc_clnt_calls\fR(3NSL)). The retry time out and
 388 the total time out periods can be changed using \fBclnt_control()\fR. The user
 389 may set the size of the send and receive buffers with the parameters
 390 \fIsendsz\fR and \fIrecvsz\fR; values of \fB0\fR choose suitable defaults. This
 391 routine returns \fINULL\fR if it fails.
 392 .RE
 393 
 394 .sp
 395 .ne 2
 396 .na
 397 \fB\fBclnt_pcreateerror()\fR\fR
 398 .ad
 399 .sp .6
 400 .RS 4n
 401 Print a message to standard error indicating why a client \fBRPC\fR handle
 402 could not be created. The message is prepended with the string \fIs\fR and a
 403 colon, and appended with a newline.
 404 .RE
 405 
 406 .sp
 407 .ne 2
 408 .na
 409 \fB\fBclnt_raw_create()\fR\fR
 410 .ad
 411 .sp .6
 412 .RS 4n
 413 This routine creates an \fBRPC\fR client handle for the remote program
 414 \fIprognum\fR and version \fIversnum\fR. The transport used to pass messages to
 415 the service is a buffer within the process's address space, so the
 416 corresponding \fBRPC\fR server should live in the same address space; (see
 417 \fBsvc_raw_create()\fR in \fBrpc_svc_create\fR(3NSL)). This allows simulation
 418 of \fBRPC\fR and measurement of \fBRPC\fR overheads, such as round trip times,
 419 without any kernel or networking interference. This routine returns \fINULL\fR
 420 if it fails. \fBclnt_raw_create()\fR should be called after
 421 \fBsvc_raw_create()\fR.
 422 .RE
 423 
 424 .sp
 425 .ne 2
 426 .na
 427 \fB\fBclnt_spcreateerror()\fR\fR
 428 .ad
 429 .sp .6
 430 .RS 4n
 431 Like \fBclnt_pcreateerror()\fR, except that it returns a string instead of
 432 printing to the standard error. A newline is not appended to the message in
 433 this case.
 434 .sp
 435 Warning: returns a pointer to a buffer that is overwritten on each call. In
 436 multithread applications, this buffer is implemented as thread-specific data.
 437 .RE
 438 
 439 .sp
 440 .ne 2
 441 .na
 442 \fB\fBclnt_tli_create()\fR\fR
 443 .ad
 444 .sp .6
 445 .RS 4n
 446 This routine creates an \fBRPC\fR client handle for the remote program
 447 \fIprognum\fR and version \fIversnum\fR. The remote program is located at
 448 address \fIsvcaddr\fR. If \fIsvcaddr\fR is \fINULL\fR and it is
 449 connection-oriented, it is assumed that the file descriptor is connected. For
 450 connectionless transports, if \fIsvcaddr\fR is \fINULL\fR,
 451 \fBRPC_UNKNOWNADDR\fR error is set. \fIfildes\fR is a file descriptor which may
 452 be open, bound and connected. If it is \fBRPC_ANYFD\fR, it opens a file
 453 descriptor on the transport specified by \fInetconf\fR. If \fIfildes\fR is
 454 \fBRPC_ANYFD\fR and \fInetconf\fR is \fINULL\fR, a \fBRPC_UNKNOWNPROTO\fR error
 455 is set. If \fIfildes\fR is unbound, then it will attempt to bind the
 456 descriptor. The user may specify the size of the buffers with the parameters
 457 \fIsendsz\fR and \fIrecvsz\fR; values of \fB0\fR choose suitable defaults.
 458 Depending upon the type of the transport (connection-oriented or
 459 connectionless), \fBclnt_tli_create()\fR calls appropriate client creation
 460 routines. This routine returns \fINULL\fR if it fails. The
 461 \fBclnt_pcreateerror()\fR routine can be used to print the reason for failure.
 462 The remote \fBrpcbind\fR service (see \fBrpcbind\fR(1M)) is not consulted for
 463 the address of the remote service.
 464 .RE
 465 
 466 .sp
 467 .ne 2
 468 .na
 469 \fB\fBclnt_tp_create()\fR\fR
 470 .ad
 471 .sp .6
 472 .RS 4n
 473 Like \fBclnt_create()\fR except \fBclnt_tp_create()\fR tries only one transport
 474 specified through \fInetconf\fR.
 475 .sp
 476 \fBclnt_tp_create()\fR creates a client handle for the program \fIprognum\fR,
 477 the version \fIversnum\fR, and for the transport specified by \fInetconf\fR.
 478 Default options are set, which can be changed using \fBclnt_control()\fR calls.
 479 The remote \fBrpcbind\fR service on the host \fIhost\fR is consulted for the
 480 address of the remote service. This routine returns \fINULL\fR if it fails. The
 481 \fBclnt_pcreateerror()\fR routine can be used to print the reason for failure.
 482 .RE
 483 
 484 .sp
 485 .ne 2
 486 .na
 487 \fB\fBclnt_tp_create_timed()\fR\fR
 488 .ad
 489 .sp .6
 490 .RS 4n
 491 Like \fBclnt_tp_create()\fR except \fBclnt_tp_create_timed()\fR has the extra
 492 parameter \fItimeout\fR which specifies the maximum time allowed for the
 493 creation attempt to succeed. In all other respects, the
 494 \fBclnt_tp_create_timed()\fR call behaves exactly like the
 495 \fBclnt_tp_create()\fR call.
 496 .RE
 497 
 498 .sp
 499 .ne 2
 500 .na
 501 \fB\fBclnt_vc_create()\fR\fR
 502 .ad
 503 .sp .6
 504 .RS 4n
 505 This routine creates an \fBRPC\fR client for the remote program \fIprognum\fR
 506 and version \fIversnum\fR; the client uses a connection-oriented transport. The
 507 remote program is located at address \fIsvcaddr\fR. The parameter \fIfildes\fR
 508 is an open and bound file descriptor. The user may specify the size of the send
 509 and receive buffers with the parameters \fIsendsz\fR and \fIrecvsz\fR; values
 510 of \fB0\fR choose suitable defaults. This routine returns \fINULL\fR if it
 511 fails.
 512 .sp
 513 The address \fIsvcaddr\fR should not be \fINULL\fR and should point to the
 514 actual address of the remote program. \fBclnt_vc_create()\fR does not consult
 515 the remote \fBrpcbind\fR service for this information.
 516 .RE
 517 
 518 .sp
 519 .ne 2
 520 .na
 521 \fB\fBrpc_createerr()\fR\fR
 522 .ad
 523 .sp .6
 524 .RS 4n
 525 A global variable whose value is set by any \fBRPC\fR client handle creation
 526 routine that fails.  It is used by the routine \fBclnt_pcreateerror()\fR to
 527 print the reason for the failure.
 528 .sp
 529 In multithreaded applications, \fBrpc_createerr\fR becomes a macro which
 530 enables each thread to have its own \fBrpc_createerr\fR.
 531 .RE
 532 
 533 .sp
 534 .ne 2
 535 .na
 536 \fB\fBclnt_door_create()\fR\fR
 537 .ad
 538 .sp .6
 539 .RS 4n
 540 This routine creates an RPC client handle over doors for the given program
 541 \fIprognum\fR and version \fIversnum\fR. Doors is a transport mechanism that
 542 facilitates fast data transfer between processes on the same machine. The user
 543 may set the size of the send buffer with the parameter \fIsendsz\fR. If
 544 \fIsendsz\fR is 0, the corresponding default buffer size is 16 Kbyte. The
 545 \fBclnt_door_create()\fR routine returns \fINULL\fR if it fails and sets a
 546 value for \fBrpc_createerr\fR.
 547 .RE
 548 
 549 .SH ATTRIBUTES
 550 .sp
 551 .LP
 552 See \fBattributes\fR(5)  for descriptions of the following attributes:
 553 .sp
 554 
 555 .sp
 556 .TS
 557 box;
 558 c | c
 559 l | l .
 560 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 561 _
 562 Architecture    All
 563 _
 564 Interface Stability     Committed
 565 _
 566 MT-Level        MT-Safe
 567 .TE
 568 
 569 .SH SEE ALSO
 570 .sp
 571 .LP
 572 \fBrpcbind\fR(1M), \fBrpc\fR(3NSL), \fBrpc_clnt_auth\fR(3NSL),
 573 \fBrpc_clnt_calls\fR(3NSL), \fBrpc_svc_create\fR(3NSL),
 574 \fBsvc_raw_create\fR(3NSL), \fBthreads\fR(5), \fBattributes\fR(5)