reactos/dll/3rdparty/libtirpc/man/rpc_clnt_create.3t

   1 .\" @(#)rpc_clnt_create.3n 1.36 93/08/31 SMI; from SVr4
   2 .\" Copyright 1989 AT&T
   3 .\" @(#)rpc_clnt_create 1.5 89/07/24 SMI;
   4 .\" Copyright (c) 1988 Sun Microsystems, Inc. - All Rights Reserved.
   5 .\" $NetBSD: rpc_clnt_create.3,v 1.2 2000/06/20 00:53:08 fvdl Exp $
   6 .\" $FreeBSD: src/lib/libc/rpc/rpc_clnt_create.3,v 1.12 2003/09/14 13:41:56 ru Exp $
   7 .Dd May 7, 1993
   8 .Dt RPC_CLNT_CREATE 3
   9 .Os
  10 .Sh NAME
  11 .Nm rpc_clnt_create ,
  12 .Nm clnt_control ,
  13 .Nm clnt_create ,
  14 .Nm clnt_create_timed ,
  15 .Nm clnt_create_vers ,
  16 .Nm clnt_create_vers_timed ,
  17 .Nm clnt_destroy ,
  18 .Nm clnt_dg_create ,
  19 .Nm clnt_pcreateerror ,
  20 .Nm clnt_raw_create ,
  21 .Nm clnt_spcreateerror ,
  22 .Nm clnt_tli_create ,
  23 .Nm clnt_tp_create ,
  24 .Nm clnt_tp_create_timed ,
  25 .Nm clnt_vc_create ,
  26 .Nm rpc_createerr
  27 .Nd "library routines for dealing with creation and manipulation of"
  28 .Vt CLIENT
  29 handles
  30 .Sh LIBRARY
  31 .Lb libc
  32 .Sh SYNOPSIS
  33 .In rpc/rpc.h
  34 .Ft bool_t
  35 .Fn clnt_control "CLIENT *clnt" "const u_int req" "char *info"
  36 .Ft "CLIENT *"
  37 .Fn clnt_create "const char * host" "const rpcprog_t prognum" "const rpcvers_t versnum" "const char *nettype"
  38 .Ft "CLIENT *"
  39 .Fn clnt_create_timed "const char * host" "const rpcprog_t prognum" "const rpcvers_t versnum" "const char *nettype" "const struct timeval *timeout"
  40 .Ft "CLIENT *"
  41 .Fn clnt_create_vers "const char * host" "const rpcprog_t prognum" "rpcvers_t *vers_outp" "const rpcvers_t vers_low" "const rpcvers_t vers_high" "const char *nettype"
  42 .Ft "CLIENT *"
  43 .Fn clnt_create_vers_timed "const char * host" "const rpcprog_t prognum" "rpcvers_t *vers_outp" "const rpcvers_t vers_low" "const rpcvers_t vers_high" "char *nettype" "const struct timeval *timeout"
  44 .Ft void
  45 .Fn clnt_destroy "CLIENT *clnt"
  46 .Ft "CLIENT *"
  47 .Fn clnt_dg_create "const int fildes" "const struct netbuf *svcaddr" "const rpcprog_t prognum" "const rpcvers_t versnum" "const u_int sendsz" "const u_int recvsz"
  48 .Ft void
  49 .Fn clnt_pcreateerror "const char *s"
  50 .Ft "char *"
  51 .Fn clnt_spcreateerror "const char *s"
  52 .Ft "CLIENT *"
  53 .Fn clnt_raw_create "const rpcprog_t prognum" "const rpcvers_t versnum"
  54 .Ft "CLIENT *"
  55 .Fn clnt_tli_create "const int fildes" "const struct netconfig *netconf" "const struct netbuf *svcaddr" "const rpcprog_t prognum" "const rpcvers_t versnum" "const u_int sendsz" "const u_int recvsz"
  56 .Ft "CLIENT *"
  57 .Fn clnt_tp_create "const char * host" "const rpcprog_t prognum" "const rpcvers_t versnum" "const struct netconfig *netconf"
  58 .Ft "CLIENT *"
  59 .Fn clnt_tp_create_timed "const char * host" "const rpcprog_t prognum" "const rpcvers_t versnum" "const struct netconfig *netconf" "const struct timeval *timeout"
  60 .Ft "CLIENT *"
  61 .Fn clnt_vc_create "const int fildes" "const struct netbuf *svcaddr" "const rpcprog_t prognum" "const rpcvers_t versnum" "u_int sendsz" "u_int recvsz"
  62 .Sh DESCRIPTION
  63 RPC library routines allow C language programs to make procedure
  64 calls on other machines across the network.
  65 First a
  66 .Vt CLIENT
  67 handle is created and then the client calls a procedure to send a
  68 request to the server.
  69 On receipt of the request, the server calls a dispatch routine
  70 to perform the requested service, and then sends a reply.
  71 .Sh Routines
  72 .Bl -tag -width YYYYYYY
  73 .It Fn clnt_control
  74 A function macro to change or retrieve various information
  75 about a client object.
  76 The
  77 .Fa req
  78 argument
  79 indicates the type of operation, and
  80 .Fa info
  81 is a pointer to the information.
  82 For both connectionless and connection-oriented transports,
  83 the supported values of
  84 .Fa req
  85 and their argument types and what they do are:
  86 .Bl -column "CLSET_FD_NCLOSE" "struct timeval *" "set total timeout"
  87 .It Dv CLSET_TIMEOUT Ta "struct timeval *" Ta "set total timeout"
  88 .It Dv CLGET_TIMEOUT Ta "struct timeval *" Ta "get total timeout"
  89 .El
  90 .Pp
  91 Note:
  92 if you set the timeout using
  93 .Fn clnt_control ,
  94 the timeout argument passed by
  95 .Fn clnt_call
  96 is ignored in all subsequent calls.
  97 .Pp
  98 Note:
  99 If you set the timeout value to 0,
 100 .Fn clnt_control
 101 immediately returns an error
 102 .Pq Dv RPC_TIMEDOUT .
 103 Set the timeout argument to 0 for batching calls.
 104 .Bl -column CLSET_FD_NCLOSE "struct timeval *" "do not close fd on destroy"
 105 .It Dv CLGET_SVC_ADDR Ta "struct netbuf *" Ta "get servers address"
 106 .It Dv CLGET_FD Ta "int *" Ta "get fd from handle"
 107 .It Dv CLSET_FD_CLOSE Ta "void" Ta "close fd on destroy"
 108 .It Dv CLSET_FD_NCLOSE Ta void Ta "don't close fd on destroy"
 109 .It Dv CLGET_VERS Ta "u_int32_t *" Ta "get RPC program version"
 110 .It Dv CLSET_VERS Ta "u_int32_t *" Ta "set RPC program version"
 111 .It Dv CLGET_XID Ta "u_int32_t *" Ta "get XID of previous call"
 112 .It Dv CLSET_XID Ta "u_int32_t *" Ta "set XID of next call"
 113 .El
 114 .Pp
 115 The following operations are valid for connectionless transports only:
 116 .Bl -column CLSET_RETRY_TIMEOUT "struct timeval *" "set total timeout"
 117 .It Dv CLSET_RETRY_TIMEOUT Ta "struct timeval *" Ta "set the retry timeout"
 118 .It Dv CLGET_RETRY_TIMEOUT Ta "struct timeval *" Ta "get the retry timeout"
 119 .It Dv CLSET_CONNECT Ta Vt "int *" Ta use Xr connect 2
 120 .El
 121 .Pp
 122 The retry timeout is the time that RPC
 123 waits for the server to reply before retransmitting the request.
 124 The
 125 .Fn clnt_control
 126 function
 127 returns
 128 .Dv TRUE
 129 on success and
 130 .Dv FALSE
 131 on failure.
 132 .It Fn clnt_create
 133 Generic client creation routine for program
 134 .Fa prognum
 135 and version
 136 .Fa versnum .
 137 The
 138 .Fa host
 139 argument
 140 identifies the name of the remote host where the server
 141 is located.
 142 The
 143 .Fa nettype
 144 argument
 145 indicates the class of transport protocol to use.
 146 The transports are tried in left to right order in
 147 .Ev NETPATH
 148 environment variable or in top to bottom order in
 149 the netconfig database.
 150 The
 151 .Fn clnt_create
 152 function
 153 tries all the transports of the
 154 .Fa nettype
 155 class available from the
 156 .Ev NETPATH
 157 environment variable and the netconfig database,
 158 and chooses the first successful one.
 159 A default timeout is set and can be modified using
 160 .Fn clnt_control .
 161 This routine returns
 162 .Dv NULL
 163 if it fails.
 164 The
 165 .Fn clnt_pcreateerror
 166 routine can be used to print the reason for failure.
 167 .Pp
 168 Note:
 169 .Fn clnt_create
 170 returns a valid client handle even
 171 if the particular version number supplied to
 172 .Fn clnt_create
 173 is not registered with the
 174 .Xr rpcbind 8
 175 service.
 176 This mismatch will be discovered by a
 177 .Fn clnt_call
 178 later (see
 179 .Xr rpc_clnt_calls 3 ) .
 180 .It Fn clnt_create_timed
 181 Generic client creation routine which is similar to
 182 .Fn clnt_create
 183 but which also has the additional argument
 184 .Fa timeout
 185 that specifies the maximum amount of time allowed for
 186 each transport class tried.
 187 In all other respects, the
 188 .Fn clnt_create_timed
 189 call behaves exactly like the
 190 .Fn clnt_create
 191 call.
 192 .It Fn clnt_create_vers
 193 Generic client creation routine which is similar to
 194 .Fn clnt_create
 195 but which also checks for the
 196 version availability.
 197 The
 198 .Fa host
 199 argument
 200 identifies the name of the remote host where the server
 201 is located.
 202 The
 203 .Fa nettype
 204 argument
 205 indicates the class transport protocols to be used.
 206 If the routine is successful it returns a client handle created for
 207 the highest version between
 208 .Fa vers_low
 209 and
 210 .Fa vers_high
 211 that is supported by the server.
 212 The
 213 .Fa vers_outp
 214 argument
 215 is set to this value.
 216 That is, after a successful return
 217 .Fa vers_low
 218 <=
 219 .Fa *vers_outp
 220 <=
 221 .Fa vers_high .
 222 If no version between
 223 .Fa vers_low
 224 and
 225 .Fa vers_high
 226 is supported by the server then the routine fails and returns
 227 .Dv NULL .
 228 A default timeout is set and can be modified using
 229 .Fn clnt_control .
 230 This routine returns
 231 .Dv NULL
 232 if it fails.
 233 The
 234 .Fn clnt_pcreateerror
 235 routine can be used to print the reason for failure.
 236 Note:
 237 .Fn clnt_create
 238 returns a valid client handle even
 239 if the particular version number supplied to
 240 .Fn clnt_create
 241 is not registered with the
 242 .Xr rpcbind 8
 243 service.
 244 This mismatch will be discovered by a
 245 .Fn clnt_call
 246 later (see
 247 .Xr rpc_clnt_calls 3 ) .
 248 However,
 249 .Fn clnt_create_vers
 250 does this for you and returns a valid handle
 251 only if a version within
 252 the range supplied is supported by the server.
 253 .It Fn clnt_create_vers_timed
 254 Generic client creation routine which is similar to
 255 .Fn clnt_create_vers
 256 but which also has the additional argument
 257 .Fa timeout
 258 that specifies the maximum amount of time allowed for
 259 each transport class tried.
 260 In all other respects, the
 261 .Fn clnt_create_vers_timed
 262 call behaves exactly like the
 263 .Fn clnt_create_vers
 264 call.
 265 .It Fn clnt_destroy
 266 A function macro that destroys the client's RPC handle.
 267 Destruction usually involves deallocation
 268 of private data structures, including
 269 .Fa clnt
 270 itself.
 271 Use of
 272 .Fa clnt
 273 is undefined after calling
 274 .Fn clnt_destroy .
 275 If the RPC library opened the associated file descriptor, or
 276 .Dv CLSET_FD_CLOSE
 277 was set using
 278 .Fn clnt_control ,
 279 the file descriptor will be closed.
 280 The caller should call
 281 .Fn auth_destroy "clnt->cl_auth"
 282 (before calling
 283 .Fn clnt_destroy )
 284 to destroy the associated
 285 .Vt AUTH
 286 structure (see
 287 .Xr rpc_clnt_auth 3 ) .
 288 .It Fn clnt_dg_create
 289 This routine creates an RPC client for the remote program
 290 .Fa prognum
 291 and version
 292 .Fa versnum ;
 293 the client uses a connectionless transport.
 294 The remote program is located at address
 295 .Fa svcaddr .
 296 The
 297 .Fa fildes
 298 argument
 299 is an open and bound file descriptor.
 300 This routine will resend the call message in intervals of
 301 15 seconds until a response is received or until the
 302 call times out.
 303 The total time for the call to time out is specified by
 304 .Fn clnt_call
 305 (see
 306 .Fn clnt_call
 307 in
 308 .Xr rpc_clnt_calls 3 ) .
 309 The retry time out and the total time out periods can
 310 be changed using
 311 .Fn clnt_control .
 312 The user may set the size of the send and receive
 313 buffers with the
 314 .Fa sendsz
 315 and
 316 .Fa recvsz
 317 arguments;
 318 values of 0 choose suitable defaults.
 319 This routine returns
 320 .Dv NULL
 321 if it fails.
 322 .It Fn clnt_pcreateerror
 323 Print a message to standard error indicating
 324 why a client RPC handle could not be created.
 325 The message is prepended with the string
 326 .Fa s
 327 and a colon, and appended with a newline.
 328 .It Fn clnt_spcreateerror
 329 Like
 330 .Fn clnt_pcreateerror ,
 331 except that it returns a string
 332 instead of printing to the standard error.
 333 A newline is not appended to the message in this case.
 334 Warning:
 335 returns a pointer to a buffer that is overwritten
 336 on each call.
 337 .It Fn clnt_raw_create
 338 This routine creates an RPC
 339 client handle for the remote program
 340 .Fa prognum
 341 and version
 342 .Fa versnum .
 343 The transport used to pass messages to the service is
 344 a buffer within the process's address space,
 345 so the corresponding RPC
 346 server should live in the same address space;
 347 (see
 348 .Fn svc_raw_create
 349 in
 350 .Xr rpc_svc_create 3 ) .
 351 This allows simulation of RPC and measurement of
 352 RPC overheads, such as round trip times,
 353 without any kernel or networking interference.
 354 This routine returns
 355 .Dv NULL
 356 if it fails.
 357 The
 358 .Fn clnt_raw_create
 359 function
 360 should be called after
 361 .Fn svc_raw_create .
 362 .It Fn clnt_tli_create
 363 This routine creates an RPC
 364 client handle for the remote program
 365 .Fa prognum
 366 and version
 367 .Fa versnum .
 368 The remote program is located at address
 369 .Fa svcaddr .
 370 If
 371 .Fa svcaddr
 372 is
 373 .Dv NULL
 374 and it is connection-oriented, it is assumed that the file descriptor
 375 is connected.
 376 For connectionless transports, if
 377 .Fa svcaddr
 378 is
 379 .Dv NULL ,
 380 .Dv RPC_UNKNOWNADDR
 381 error is set.
 382 The
 383 .Fa fildes
 384 argument
 385 is a file descriptor which may be open, bound and connected.
 386 If it is
 387 .Dv RPC_ANYFD ,
 388 it opens a file descriptor on the transport specified by
 389 .Fa netconf .
 390 If
 391 .Fa fildes
 392 is
 393 .Dv RPC_ANYFD
 394 and
 395 .Fa netconf
 396 is
 397 .Dv NULL ,
 398 a
 399 .Dv RPC_UNKNOWNPROTO
 400 error is set.
 401 If
 402 .Fa fildes
 403 is unbound, then it will attempt to bind the descriptor.
 404 The user may specify the size of the buffers with the
 405 .Fa sendsz
 406 and
 407 .Fa recvsz
 408 arguments;
 409 values of 0 choose suitable defaults.
 410 Depending upon the type of the transport (connection-oriented
 411 or connectionless),
 412 .Fn clnt_tli_create
 413 calls appropriate client creation routines.
 414 This routine returns
 415 .Dv NULL
 416 if it fails.
 417 The
 418 .Fn clnt_pcreateerror
 419 routine can be used to print the reason for failure.
 420 The remote rpcbind
 421 service (see
 422 .Xr rpcbind 8 )
 423 is not consulted for the address of the remote
 424 service.
 425 .It Fn clnt_tp_create
 426 Like
 427 .Fn clnt_create
 428 except
 429 .Fn clnt_tp_create
 430 tries only one transport specified through
 431 .Fa netconf .
 432 The
 433 .Fn clnt_tp_create
 434 function
 435 creates a client handle for the program
 436 .Fa prognum ,
 437 the version
 438 .Fa versnum ,
 439 and for the transport specified by
 440 .Fa netconf .
 441 Default options are set,
 442 which can be changed using
 443 .Fn clnt_control
 444 calls.
 445 The remote rpcbind service on the host
 446 .Fa host
 447 is consulted for the address of the remote service.
 448 This routine returns
 449 .Dv NULL
 450 if it fails.
 451 The
 452 .Fn clnt_pcreateerror
 453 routine can be used to print the reason for failure.
 454 .It Fn clnt_tp_create_timed
 455 Like
 456 .Fn clnt_tp_create
 457 except
 458 .Fn clnt_tp_create_timed
 459 has the extra argument
 460 .Fa timeout
 461 which specifies the maximum time allowed for
 462 the creation attempt to succeed.
 463 In all other respects, the
 464 .Fn clnt_tp_create_timed
 465 call behaves exactly like the
 466 .Fn clnt_tp_create
 467 call.
 468 .It Fn clnt_vc_create
 469 This routine creates an RPC
 470 client for the remote program
 471 .Fa prognum
 472 and version
 473 .Fa versnum ;
 474 the client uses a connection-oriented transport.
 475 The remote program is located at address
 476 .Fa svcaddr .
 477 The
 478 .Fa fildes
 479 argument
 480 is an open and bound file descriptor.
 481 The user may specify the size of the send and receive buffers
 482 with the
 483 .Fa sendsz
 484 and
 485 .Fa recvsz
 486 arguments;
 487 values of 0 choose suitable defaults.
 488 This routine returns
 489 .Dv NULL
 490 if it fails.
 491 The address
 492 .Fa svcaddr
 493 should not be
 494 .Dv NULL
 495 and should point to the actual address of the remote program.
 496 The
 497 .Fn clnt_vc_create
 498 function
 499 does not consult the remote rpcbind service for this information.
 500 .It Xo
 501 .Vt "struct rpc_createerr" Va rpc_createerr ;
 502 .Xc
 503 A global variable whose value is set by any RPC
 504 client handle creation routine
 505 that fails.
 506 It is used by the routine
 507 .Fn clnt_pcreateerror
 508 to print the reason for the failure.
 509 .El
 510 .Sh SEE ALSO
 511 .Xr rpc 3 ,
 512 .Xr rpc_clnt_auth 3 ,
 513 .Xr rpc_clnt_calls 3 ,
 514 .Xr rpcbind 8