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