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