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.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 <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.Pp 60.Sh Routines 61.Bl -tag -width YYYYYYY 62.It Fn clnt_control 63A function macro to change or retrieve various information 64about a client object. 65.Fa req 66indicates the type of operation, and 67.Fa info 68is a pointer to the information. 69For both connectionless and connection-oriented transports, 70the supported values of 71.Fa req 72and their argument types and what they do are: 73.Bl -column "CLSET_FD_NCLOSE" "struct timeval *" "set total timeout" 74.It Dv CLSET_TIMEOUT Ta "struct timeval *" Ta "set total timeout" 75.It Dv CLGET_TIMEOUT Ta "struct timeval *" Ta "get total timeout" 76.El 77.Pp 78Note: 79if you set the timeout using 80.Fn clnt_control , 81the timeout argument passed by 82.Fn clnt_call 83is ignored in all subsequent calls. 84 85Note: 86If you set the timeout value to 0 87.Fn clnt_control 88immediately returns an error 89( 90.Dv RPC_TIMEDOUT ). 91Set the timeout parameter to 0 for batching calls. 92.Bl -column CLSET_FD_NCLOSE "struct timeval *" "do not close fd on destroy" 93.It Dv CLGET_SVC_ADDR Ta "struct netbuf *" Ta "get servers address" 94.It Dv CLGET_FD Ta "int *" Ta "get fd from handle" 95.It Dv CLSET_FD_CLOSE Ta "void" Ta "close fd on destroy" 96.It Dv CLSET_FD_NCLOSE Ta void Ta "don't close fd on destroy" 97.It Dv CLGET_VERS Ta "unsigned long *" Ta "get RPC program version" 98.It Dv CLSET_VERS Ta "unsigned long *" Ta "set RPC program version" 99.It Dv CLGET_XID Ta "unsigned long *" Ta "get XID of previous call" 100.It Dv CLSET_XID Ta "unsigned long *" Ta "set XID of next call" 101.El 102.Pp 103The following operations are valid for connectionless transports only: 104.Bl -column CLSET_RETRY_TIMEOUT "struct timeval *" "set total timeout" 105.It Dv CLSET_RETRY_TIMEOUT Ta "struct timeval *" Ta "set the retry timeout" 106.It Dv CLGET_RETRY_TIMEOUT Ta "struct timeval *" Ta "get the retry timeout" 107.El 108.Pp 109The retry timeout is the time that RPC 110waits for the server to reply before retransmitting the request. 111.Fn clnt_control 112returns 113.Dv TRUE 114on success and 115.Dv FALSE 116on failure. 117.Pp 118.It Fn clnt_create 119Generic client creation routine for program 120.Fa prognum 121and version 122.Fa versnum . 123.Fa host 124identifies the name of the remote host where the server 125is located. 126.Fa nettype 127indicates the class of transport protocol to use. 128The transports are tried in left to right order in 129.Ev NETPATH 130environment variable or in top to bottom order in 131the netconfig database. 132.Fn clnt_create 133tries all the transports of the 134.Fa nettype 135class available from the 136.Ev NETPATH 137environment variable and the netconfig database, 138and chooses the first successful one. 139A default timeout is set and can be modified using 140.Fn clnt_control . 141This routine returns 142.Dv NULL 143if it fails. 144The 145.Fn clnt_pcreateerror 146routine can be used to print the reason for failure. 147.Pp 148Note: 149.Fn clnt_create 150returns a valid client handle even 151if the particular version number supplied to 152.Fn clnt_create 153is not registered with the 154.Xr rpcbind 8 155service. 156This mismatch will be discovered by a 157.Fn clnt_call 158later (see 159.Xr rpc_clnt_calls 3 ). 160.Pp 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 3N ). 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.Pp 217.It Fn clnt_destroy 218A function macro that destroys the client's RPC handle. 219Destruction usually involves deallocation 220of private data structures, including 221.Fa clnt 222itself. 223Use of 224.Fa clnt 225is undefined after calling 226.Fn clnt_destroy . 227If the RPC library opened the associated file descriptor, or 228.Dv CLSET_FD_CLOSE 229was set using 230.Fn clnt_control , 231the file descriptor will be closed. 232The caller should call 233.Fn auth_destroy "clnt->cl_auth" 234(before calling 235.Fn clnt_destroy ) 236to destroy the associated 237.Dv AUTH 238structure (see 239.Xr rpc_clnt_auth 3 ). 240.Pp 241.It Fn clnt_dg_create 242This routine creates an RPC client for the remote program 243.Fa prognum 244and version 245.Fa versnum ; 246the client uses a connectionless transport. 247The remote program is located at address 248.Fa svcaddr . 249The parameter 250.Fa fildes 251is an open and bound file descriptor. 252This routine will resend the call message in intervals of 25315 seconds until a response is received or until the 254call times out. 255The total time for the call to time out is specified by 256.Fn clnt_call 257(see 258.Fn clnt_call 259in 260.Xr rpc_clnt_calls 3 ). 261The retry time out and the total time out periods can 262be changed using 263.Fn clnt_control . 264The user may set the size of the send and receive 265buffers with the parameters 266.Fa sendsz 267and 268.Fa recvsz ; 269values of 0 choose suitable defaults. 270This routine returns 271.Dv NULL 272if it fails. 273.Pp 274.It Fn clnt_pcreateerror 275Print a message to standard error indicating 276why a client RPC handle could not be created. 277The message is prepended with the string 278.Fa s 279and a colon, and appended with a newline. 280.Pp 281.It Fn clnt_spcreateerror 282Like 283.Fn clnt_pcreateerror , 284except that it returns a string 285instead of printing to the standard error. 286A newline is not appended to the message in this case. 287Warning: 288returns a pointer to a buffer that is overwritten 289on each call. 290.Pp 291.It Fn clnt_raw_create 292.IP 293This routine creates an RPC 294client handle for the remote program 295.Fa prognum 296and version 297.Fa versnum . 298The transport used to pass messages to the service is 299a buffer within the process's address space, 300so the corresponding RPC 301server should live in the same address space; 302(see 303.Fn svc_raw_create 304in 305.Xr rpc_svc_create 3 ). 306This allows simulation of RPC and measurement of 307RPC overheads, such as round trip times, 308without any kernel or networking interference. 309This routine returns 310.Dv NULL 311if it fails. 312.Fn clnt_raw_create 313should be called after 314.Fn svc_raw_create . 315.Pp 316.It Fn clnt_tli_create 317This routine creates an RPC 318client handle for the remote program 319.Fa prognum 320and version 321.Fa versnum . 322The remote program is located at address 323.Fa svcaddr . 324If 325.Fa svcaddr 326is 327.Dv NULL 328and it is connection-oriented, it is assumed that the file descriptor 329is connected. For connectionless transports, if 330.Fa svcaddr 331is 332..Dv NULL , 333.Dv RPC_UNKNOWNADDR 334error is set. 335.Fa fildes 336is a file descriptor which may be open, bound and connected. 337If it is 338.Dv RPC_ANYFD , 339it opens a file descriptor on the transport specified by 340.Fa netconf . 341If 342.Fa fildes 343is 344.Dv RPC_ANYFD 345and 346.Fa netconf 347is 348.Dv NULL , 349a 350.Dv RPC_UNKNOWNPROTO 351error is set. 352If 353.Fa fildes 354is unbound, then it will attempt to bind the descriptor. 355The user may specify the size of the buffers with the parameters 356.Fa sendsz 357and 358.Fa recvsz ; 359values of 0 choose suitable defaults. 360Depending upon the type of the transport (connection-oriented 361or connectionless), 362.Fn clnt_tli_create 363calls appropriate client creation routines. 364This routine returns 365.Dv NULL 366if it fails. 367The 368.Fn clnt_pcreateerror 369routine can be used to print the reason for failure. 370The remote rpcbind 371service (see 372.Xr rpcbind 8 ) 373is not consulted for the address of the remote 374service. 375.Pp 376.It Fn clnt_tp_create 377Like 378.Fn clnt_create 379except 380.Fn clnt_tp_create 381tries only one transport specified through 382.Fa netconf . 383.Fn clnt_tp_create 384creates a client handle for the program 385.Fa prognum , 386the version 387.Fa versnum , 388and for the transport specified by 389.Fa netconf . 390Default options are set, 391which can be changed using 392.Fn clnt_control 393calls. 394The remote pcbind service on the host 395.Fa host 396is consulted for the address of the remote service. 397This routine returns 398.Dv NULL 399if it fails. 400The 401.Fn clnt_pcreateerror 402routine can be used to print the reason for failure. 403.Pp 404.It Fn clnt_vc_create 405This routine creates an RPC 406client for the remote program 407.Fa prognum 408and version 409.Fa versnum ; 410the client uses a connection-oriented transport. 411The remote program is located at address 412.Fa svcaddr . 413The parameter 414.Fa fildes 415is an open and bound file descriptor. 416The user may specify the size of the send and receive buffers 417with the parameters 418.Fa sendsz 419and 420.Fa recvsz ; 421values of 0 choose suitable defaults. 422This routine returns 423.Dv NULL 424if it fails. 425The address 426.Fa svcaddr 427should not be 428.Dv NULL 429and should point to the actual address of the remote program. 430.Fn clnt_vc_create 431does not consult the remote rpcbind service for this information. 432.Pp 433.It struct rpc_createerr rpc_createerr; 434A global variable whose value is set by any RPC 435client handle creation routine 436that fails. It 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