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