| rpc_clnt_create.3 (108037) | rpc_clnt_create.3 (108087) |
|---|---|
| 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 $ | 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: head/lib/libc/rpc/rpc_clnt_create.3 108037 2002-12-18 12:45:11Z ru $ | 6.\" $FreeBSD: head/lib/libc/rpc/rpc_clnt_create.3 108087 2002-12-19 09:40:28Z ru $ |
| 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 , --- 53 unchanged lines hidden (view full) --- 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. | 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 , --- 53 unchanged lines hidden (view full) --- 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. |
| 76The |
|
| 76.Fa req | 77.Fa req |
| 78argument |
|
| 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" --- 8 unchanged lines hidden (view full) --- 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 . | 79indicates the type of operation, and 80.Fa info 81is a pointer to the information. 82For both connectionless and connection-oriented transports, 83the supported values of 84.Fa req 85and their argument types and what they do are: 86.Bl -column "CLSET_FD_NCLOSE" "struct timeval *" "set total timeout" --- 8 unchanged lines hidden (view full) --- 95.Fn clnt_call 96is ignored in all subsequent calls. 97.Pp 98Note: 99If you set the timeout value to 0, 100.Fn clnt_control 101immediately returns an error 102.Pq Dv RPC_TIMEDOUT . |
| 101Set the timeout parameter to 0 for batching calls. | 103Set the timeout argument 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 "u_int32_t *" Ta "get RPC program version" 108.It Dv CLSET_VERS Ta "u_int32_t *" Ta "set RPC program version" 109.It Dv CLGET_XID Ta "u_int32_t *" Ta "get XID of previous call" --- 17 unchanged lines hidden (view full) --- 127on success and 128.Dv FALSE 129on failure. 130.It Fn clnt_create 131Generic client creation routine for program 132.Fa prognum 133and version 134.Fa versnum . | 104.Bl -column CLSET_FD_NCLOSE "struct timeval *" "do not close fd on destroy" 105.It Dv CLGET_SVC_ADDR Ta "struct netbuf *" Ta "get servers address" 106.It Dv CLGET_FD Ta "int *" Ta "get fd from handle" 107.It Dv CLSET_FD_CLOSE Ta "void" Ta "close fd on destroy" 108.It Dv CLSET_FD_NCLOSE Ta void Ta "don't close fd on destroy" 109.It Dv CLGET_VERS Ta "u_int32_t *" Ta "get RPC program version" 110.It Dv CLSET_VERS Ta "u_int32_t *" Ta "set RPC program version" 111.It Dv CLGET_XID Ta "u_int32_t *" Ta "get XID of previous call" --- 17 unchanged lines hidden (view full) --- 129on success and 130.Dv FALSE 131on failure. 132.It Fn clnt_create 133Generic client creation routine for program 134.Fa prognum 135and version 136.Fa versnum . |
| 137The |
|
| 135.Fa host | 138.Fa host |
| 139argument |
|
| 136identifies the name of the remote host where the server 137is located. | 140identifies the name of the remote host where the server 141is located. |
| 142The |
|
| 138.Fa nettype | 143.Fa nettype |
| 144argument |
|
| 139indicates the class of transport protocol to use. 140The transports are tried in left to right order in 141.Ev NETPATH 142environment variable or in top to bottom order in 143the netconfig database. 144The 145.Fn clnt_create 146function --- 22 unchanged lines hidden (view full) --- 169service. 170This mismatch will be discovered by a 171.Fn clnt_call 172later (see 173.Xr rpc_clnt_calls 3 ) . 174.It Fn clnt_create_timed 175Generic client creation routine which is similar to 176.Fn clnt_create | 145indicates the class of transport protocol to use. 146The transports are tried in left to right order in 147.Ev NETPATH 148environment variable or in top to bottom order in 149the netconfig database. 150The 151.Fn clnt_create 152function --- 22 unchanged lines hidden (view full) --- 175service. 176This mismatch will be discovered by a 177.Fn clnt_call 178later (see 179.Xr rpc_clnt_calls 3 ) . 180.It Fn clnt_create_timed 181Generic client creation routine which is similar to 182.Fn clnt_create |
| 177but which also has the additional parameter | 183but which also has the additional argument |
| 178.Fa timeout 179that specifies the maximum amount of time allowed for 180each transport class tried. 181In all other respects, the 182.Fn clnt_create_timed 183call behaves exactly like the 184.Fn clnt_create 185call. 186.It Fn clnt_create_vers 187Generic client creation routine which is similar to 188.Fn clnt_create 189but which also checks for the 190version availability. | 184.Fa timeout 185that specifies the maximum amount of time allowed for 186each transport class tried. 187In all other respects, the 188.Fn clnt_create_timed 189call behaves exactly like the 190.Fn clnt_create 191call. 192.It Fn clnt_create_vers 193Generic client creation routine which is similar to 194.Fn clnt_create 195but which also checks for the 196version availability. |
| 197The |
|
| 191.Fa host | 198.Fa host |
| 199argument |
|
| 192identifies the name of the remote host where the server 193is located. | 200identifies the name of the remote host where the server 201is located. |
| 202The |
|
| 194.Fa nettype | 203.Fa nettype |
| 204argument |
|
| 195indicates the class transport protocols to be used. 196If the routine is successful it returns a client handle created for 197the highest version between 198.Fa vers_low 199and 200.Fa vers_high 201that is supported by the server. | 205indicates the class transport protocols to be used. 206If the routine is successful it returns a client handle created for 207the highest version between 208.Fa vers_low 209and 210.Fa vers_high 211that is supported by the server. |
| 212The |
|
| 202.Fa vers_outp | 213.Fa vers_outp |
| 214argument |
|
| 203is set to this value. 204That is, after a successful return 205.Fa vers_low 206<= 207.Fa *vers_outp 208<= 209.Fa vers_high . 210If no version between --- 25 unchanged lines hidden (view full) --- 236However, 237.Fn clnt_create_vers 238does this for you and returns a valid handle 239only if a version within 240the range supplied is supported by the server. 241.It Fn clnt_create_vers_timed 242Generic client creation routine which is similar to 243.Fn clnt_create_vers | 215is set to this value. 216That is, after a successful return 217.Fa vers_low 218<= 219.Fa *vers_outp 220<= 221.Fa vers_high . 222If no version between --- 25 unchanged lines hidden (view full) --- 248However, 249.Fn clnt_create_vers 250does this for you and returns a valid handle 251only if a version within 252the range supplied is supported by the server. 253.It Fn clnt_create_vers_timed 254Generic client creation routine which is similar to 255.Fn clnt_create_vers |
| 244but which also has the additional parameter | 256but which also has the additional argument |
| 245.Fa timeout 246that specifies the maximum amount of time allowed for 247each transport class tried. 248In all other respects, the 249.Fn clnt_create_vers_timed 250call behaves exactly like the 251.Fn clnt_create_vers 252call. --- 23 unchanged lines hidden (view full) --- 276.It Fn clnt_dg_create 277This routine creates an RPC client for the remote program 278.Fa prognum 279and version 280.Fa versnum ; 281the client uses a connectionless transport. 282The remote program is located at address 283.Fa svcaddr . | 257.Fa timeout 258that specifies the maximum amount of time allowed for 259each transport class tried. 260In all other respects, the 261.Fn clnt_create_vers_timed 262call behaves exactly like the 263.Fn clnt_create_vers 264call. --- 23 unchanged lines hidden (view full) --- 288.It Fn clnt_dg_create 289This routine creates an RPC client for the remote program 290.Fa prognum 291and version 292.Fa versnum ; 293the client uses a connectionless transport. 294The remote program is located at address 295.Fa svcaddr . |
| 284The parameter | 296The |
| 285.Fa fildes | 297.Fa fildes |
| 298argument |
|
| 286is an open and bound file descriptor. 287This routine will resend the call message in intervals of 28815 seconds until a response is received or until the 289call times out. 290The total time for the call to time out is specified by 291.Fn clnt_call 292(see 293.Fn clnt_call 294in 295.Xr rpc_clnt_calls 3 ) . 296The retry time out and the total time out periods can 297be changed using 298.Fn clnt_control . 299The user may set the size of the send and receive | 299is an open and bound file descriptor. 300This routine will resend the call message in intervals of 30115 seconds until a response is received or until the 302call times out. 303The total time for the call to time out is specified by 304.Fn clnt_call 305(see 306.Fn clnt_call 307in 308.Xr rpc_clnt_calls 3 ) . 309The retry time out and the total time out periods can 310be changed using 311.Fn clnt_control . 312The user may set the size of the send and receive |
| 300buffers with the parameters | 313buffers with the |
| 301.Fa sendsz 302and | 314.Fa sendsz 315and |
| 303.Fa recvsz ; | 316.Fa recvsz 317arguments; |
| 304values of 0 choose suitable defaults. 305This routine returns 306.Dv NULL 307if it fails. 308.It Fn clnt_pcreateerror 309Print a message to standard error indicating 310why a client RPC handle could not be created. 311The message is prepended with the string --- 48 unchanged lines hidden (view full) --- 360and it is connection-oriented, it is assumed that the file descriptor 361is connected. 362For connectionless transports, if 363.Fa svcaddr 364is 365.Dv NULL , 366.Dv RPC_UNKNOWNADDR 367error is set. | 318values of 0 choose suitable defaults. 319This routine returns 320.Dv NULL 321if it fails. 322.It Fn clnt_pcreateerror 323Print a message to standard error indicating 324why a client RPC handle could not be created. 325The message is prepended with the string --- 48 unchanged lines hidden (view full) --- 374and it is connection-oriented, it is assumed that the file descriptor 375is connected. 376For connectionless transports, if 377.Fa svcaddr 378is 379.Dv NULL , 380.Dv RPC_UNKNOWNADDR 381error is set. |
| 382The |
|
| 368.Fa fildes | 383.Fa fildes |
| 384argument |
|
| 369is a file descriptor which may be open, bound and connected. 370If it is 371.Dv RPC_ANYFD , 372it opens a file descriptor on the transport specified by 373.Fa netconf . 374If 375.Fa fildes 376is 377.Dv RPC_ANYFD 378and 379.Fa netconf 380is 381.Dv NULL , 382a 383.Dv RPC_UNKNOWNPROTO 384error is set. 385If 386.Fa fildes 387is unbound, then it will attempt to bind the descriptor. | 385is a file descriptor which may be open, bound and connected. 386If it is 387.Dv RPC_ANYFD , 388it opens a file descriptor on the transport specified by 389.Fa netconf . 390If 391.Fa fildes 392is 393.Dv RPC_ANYFD 394and 395.Fa netconf 396is 397.Dv NULL , 398a 399.Dv RPC_UNKNOWNPROTO 400error is set. 401If 402.Fa fildes 403is unbound, then it will attempt to bind the descriptor. |
| 388The user may specify the size of the buffers with the parameters | 404The user may specify the size of the buffers with the |
| 389.Fa sendsz 390and | 405.Fa sendsz 406and |
| 391.Fa recvsz ; | 407.Fa recvsz 408arguments; |
| 392values of 0 choose suitable defaults. 393Depending upon the type of the transport (connection-oriented 394or connectionless), 395.Fn clnt_tli_create 396calls appropriate client creation routines. 397This routine returns 398.Dv NULL 399if it fails. --- 34 unchanged lines hidden (view full) --- 434The 435.Fn clnt_pcreateerror 436routine can be used to print the reason for failure. 437.It Fn clnt_tp_create_timed 438Like 439.Fn clnt_tp_create 440except 441.Fn clnt_tp_create_timed | 409values of 0 choose suitable defaults. 410Depending upon the type of the transport (connection-oriented 411or connectionless), 412.Fn clnt_tli_create 413calls appropriate client creation routines. 414This routine returns 415.Dv NULL 416if it fails. --- 34 unchanged lines hidden (view full) --- 451The 452.Fn clnt_pcreateerror 453routine can be used to print the reason for failure. 454.It Fn clnt_tp_create_timed 455Like 456.Fn clnt_tp_create 457except 458.Fn clnt_tp_create_timed |
| 442has the extra parameter | 459has the extra argument |
| 443.Fa timeout 444which specifies the maximum time allowed for 445for the creation attempt to succeed. 446In all other respects, the 447.Fn clnt_tp_create_timed 448call behaves exactly like the 449.Fn clnt_tp_create 450call. 451.It Fn clnt_vc_create 452This routine creates an RPC 453client for the remote program 454.Fa prognum 455and version 456.Fa versnum ; 457the client uses a connection-oriented transport. 458The remote program is located at address 459.Fa svcaddr . | 460.Fa timeout 461which specifies the maximum time allowed for 462for the creation attempt to succeed. 463In all other respects, the 464.Fn clnt_tp_create_timed 465call behaves exactly like the 466.Fn clnt_tp_create 467call. 468.It Fn clnt_vc_create 469This routine creates an RPC 470client for the remote program 471.Fa prognum 472and version 473.Fa versnum ; 474the client uses a connection-oriented transport. 475The remote program is located at address 476.Fa svcaddr . |
| 460The parameter | 477The |
| 461.Fa fildes | 478.Fa fildes |
| 479argument |
|
| 462is an open and bound file descriptor. 463The user may specify the size of the send and receive buffers | 480is an open and bound file descriptor. 481The user may specify the size of the send and receive buffers |
| 464with the parameters | 482with the |
| 465.Fa sendsz 466and | 483.Fa sendsz 484and |
| 467.Fa recvsz ; | 485.Fa recvsz 486arguments; |
| 468values of 0 choose suitable defaults. 469This routine returns 470.Dv NULL 471if it fails. 472The address 473.Fa svcaddr 474should not be 475.Dv NULL --- 20 unchanged lines hidden --- | 487values of 0 choose suitable defaults. 488This routine returns 489.Dv NULL 490if it fails. 491The address 492.Fa svcaddr 493should not be 494.Dv NULL --- 20 unchanged lines hidden --- |