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