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