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.12 2011/05/17 03:35:39 enami Exp $ 6.Dd May 23, 2009 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.In rpc/rpc.h 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.Pq 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 290This routine creates an RPC 291client handle for the remote program 292.Fa prognum 293and version 294.Fa versnum . 295The transport used to pass messages to the service is 296a buffer within the process's address space, 297so the corresponding RPC 298server should live in the same address space; 299(see 300.Fn svc_raw_create 301in 302.Xr rpc_svc_create 3 ) . 303This allows simulation of RPC and measurement of 304RPC overheads, such as round trip times, 305without any kernel or networking interference. 306This routine returns 307.Dv NULL 308if it fails. 309.Fn clnt_raw_create 310should be called after 311.Fn svc_raw_create . 312.Pp 313.It Fn clnt_tli_create 314This routine creates an RPC 315client handle for the remote program 316.Fa prognum 317and version 318.Fa versnum . 319The remote program is located at address 320.Fa svcaddr . 321If 322.Fa svcaddr 323is 324.Dv NULL 325and it is connection-oriented, it is assumed that the file descriptor 326is connected. 327For connectionless transports, if 328.Fa svcaddr 329is 330.Dv NULL , 331.Dv RPC_UNKNOWNADDR 332error is set. 333.Fa fildes 334is a file descriptor which may be open, bound and connected. 335If it is 336.Dv RPC_ANYFD , 337it opens a file descriptor on the transport specified by 338.Fa netconf . 339If 340.Fa fildes 341is 342.Dv RPC_ANYFD 343and 344.Fa netconf 345is 346.Dv NULL , 347a 348.Dv RPC_UNKNOWNPROTO 349error is set. 350If 351.Fa fildes 352is unbound, then it will attempt to bind the descriptor. 353The user may specify the size of the buffers with the parameters 354.Fa sendsz 355and 356.Fa recvsz ; 357values of 0 choose suitable defaults. 358Depending upon the type of the transport (connection-oriented 359or connectionless), 360.Fn clnt_tli_create 361calls appropriate client creation routines. 362This routine returns 363.Dv NULL 364if it fails. 365The 366.Fn clnt_pcreateerror 367routine can be used to print the reason for failure. 368The remote rpcbind 369service (see 370.Xr rpcbind 8 ) 371is not consulted for the address of the remote 372service. 373.Pp 374.It Fn clnt_tp_create 375Like 376.Fn clnt_create 377except 378.Fn clnt_tp_create 379tries only one transport specified through 380.Fa netconf . 381.Fn clnt_tp_create 382creates a client handle for the program 383.Fa prognum , 384the version 385.Fa versnum , 386and for the transport specified by 387.Fa netconf . 388Default options are set, 389which can be changed using 390.Fn clnt_control 391calls. 392The remote rpcbind service on the host 393.Fa host 394is consulted for the address of the remote service. 395This routine returns 396.Dv NULL 397if it fails. 398The 399.Fn clnt_pcreateerror 400routine can be used to print the reason for failure. 401.Pp 402.It Fn clnt_vc_create 403This routine creates an RPC 404client for the remote program 405.Fa prognum 406and version 407.Fa versnum ; 408the client uses a connection-oriented transport. 409The remote program is located at address 410.Fa svcaddr . 411The parameter 412.Fa fildes 413is an open and bound file descriptor. 414The user may specify the size of the send and receive buffers 415with the parameters 416.Fa sendsz 417and 418.Fa recvsz ; 419values of 0 choose suitable defaults. 420This routine returns 421.Dv NULL 422if it fails. 423The address 424.Fa svcaddr 425should not be 426.Dv NULL 427and should point to the actual address of the remote program. 428.Fn clnt_vc_create 429does not consult the remote rpcbind service for this information. 430.Pp 431.It struct rpc_createerr rpc_createerr; 432A global variable whose value is set by any RPC 433client handle creation routine 434that fails. 435It is used by the routine 436.Fn clnt_pcreateerror 437to print the reason for the failure. 438.El 439.Sh SEE ALSO 440.Xr rpc 3 , 441.Xr rpc_clnt_auth 3 , 442.Xr rpc_clnt_calls 3 , 443.Xr rpcbind 8 444