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