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