lib/libc/rpc/rpc_clnt_create.3

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