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