usr/src/man/man3nsl/rpc_clnt_create.3nsl

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