1.\" @(#)rpc_clnt_calls.3n 1.30 93/08/31 SMI; from SVr4 2.\" Copyright 1989 AT&T 3.\" @(#)rpc_clnt_calls 1.4 89/07/20 SMI; 4.\" Copyright (c) 1988 Sun Microsystems, Inc. - All Rights Reserved. 5.\" $FreeBSD: src/lib/libc/rpc/rpc_clnt_calls.3,v 1.8 2005/02/09 18:03:14 ru Exp $ 6.Dd May 7, 1993 7.Dt RPC_CLNT_CALLS 3 8.Os 9.Sh NAME 10.Nm rpc_clnt_calls , 11.Nm clnt_call , 12.Nm clnt_freeres , 13.Nm clnt_geterr , 14.Nm clnt_perrno , 15.Nm clnt_perror , 16.Nm clnt_sperrno , 17.Nm clnt_sperror , 18.Nm rpc_broadcast , 19.Nm rpc_broadcast_exp , 20.Nm rpc_call 21.Nd library routines for client side calls 22.Sh LIBRARY 23.Lb libc 24.Sh SYNOPSIS 25.In rpc/rpc.h 26.Ft "enum clnt_stat" 27.Fn clnt_call "CLIENT *clnt" "const rpcproc_t procnum" "const xdrproc_t inproc" "const caddr_t in" "const xdrproc_t outproc" "caddr_t out" "const struct timeval tout" 28.Ft bool_t 29.Fn clnt_freeres "CLIENT *clnt" "const xdrproc_t outproc" "caddr_t out" 30.Ft void 31.Fn clnt_geterr "const CLIENT * clnt" "struct rpc_err * errp" 32.Ft void 33.Fn clnt_perrno "const enum clnt_stat stat" 34.Ft void 35.Fn clnt_perror "CLIENT *clnt" "const char *s" 36.Ft "char *" 37.Fn clnt_sperrno "const enum clnt_stat stat" 38.Ft "char *" 39.Fn clnt_sperror "CLIENT *clnt" "const char * s" 40.Ft "enum clnt_stat" 41.Fo rpc_broadcast 42.Fa "const rpcprog_t prognum" "const rpcvers_t versnum" 43.Fa "const rpcproc_t procnum" "const xdrproc_t inproc" 44.Fa "const caddr_t in" "const xdrproc_t outproc" "caddr_t out" 45.Fa "const resultproc_t eachresult" "const char *nettype" 46.Fc 47.Ft "enum clnt_stat" 48.Fo rpc_broadcast_exp 49.Fa "const rpcprog_t prognum" "const rpcvers_t versnum" 50.Fa "const rpcproc_t procnum" "const xdrproc_t xargs" 51.Fa "caddr_t argsp" "const xdrproc_t xresults" 52.Fa "caddr_t resultsp" "const resultproc_t eachresult" 53.Fa "const int inittime" "const int waittime" 54.Fa "const char * nettype" 55.Fc 56.Ft "enum clnt_stat" 57.Fo rpc_call 58.Fa "const char *host" "const rpcprog_t prognum" 59.Fa "const rpcvers_t versnum" "const rpcproc_t procnum" 60.Fa "const xdrproc_t inproc" "const char *in" 61.Fa "const xdrproc_t outproc" "char *out" "const char *nettype" 62.Fc 63.Sh DESCRIPTION 64RPC library routines allow C language programs to make procedure 65calls on other machines across the network. 66First, the client calls a procedure to send a request to the server. 67Upon receipt of the request, the server calls a dispatch routine 68to perform the requested service, and then sends back a reply. 69.Pp 70The 71.Fn clnt_call , 72.Fn rpc_call , 73and 74.Fn rpc_broadcast 75routines handle the client side of the procedure call. 76The remaining routines deal with error handling in the case of errors. 77.Pp 78Some of the routines take a 79.Vt CLIENT 80handle as one of the arguments. 81A 82.Vt CLIENT 83handle can be created by an RPC creation routine such as 84.Fn clnt_create 85(see 86.Xr rpc_clnt_create 3 ) . 87.Pp 88These routines are safe for use in multithreaded applications. 89.Vt CLIENT 90handles can be shared between threads, however in this implementation 91requests by different threads are serialized (that is, the first request will 92receive its results before the second request is sent). 93.Sh Routines 94See 95.Xr rpc 3 96for the definition of the 97.Vt CLIENT 98data structure. 99.Bl -tag -width XXXXX 100.It Fn clnt_call 101A function macro that calls the remote procedure 102.Fa procnum 103associated with the client handle, 104.Fa clnt , 105which is obtained with an RPC 106client creation routine such as 107.Fn clnt_create 108(see 109.Xr rpc_clnt_create 3 ) . 110The 111.Fa inproc 112argument 113is the XDR function used to encode the procedure's arguments, and 114.Fa outproc 115is the XDR function used to decode the procedure's results; 116.Fa in 117is the address of the procedure's argument(s), and 118.Fa out 119is the address of where to place the result(s). 120The 121.Fa tout 122argument 123is the time allowed for results to be returned, which is overridden by 124a time-out set explicitly through 125.Fn clnt_control , 126see 127.Xr rpc_clnt_create 3 . 128If the remote call succeeds, the status returned is 129.Dv RPC_SUCCESS , 130otherwise an appropriate status is returned. 131.It Fn clnt_freeres 132A function macro that frees any data allocated by the 133RPC/XDR system when it decoded the results of an RPC call. 134The 135.Fa out 136argument 137is the address of the results, and 138.Fa outproc 139is the XDR routine describing the results. 140This routine returns 1 if the results were successfully freed, 141and 0 otherwise. 142.It Fn clnt_geterr 143A function macro that copies the error structure out of the client 144handle to the structure at address 145.Fa errp . 146.It Fn clnt_perrno 147Print a message to standard error corresponding 148to the condition indicated by 149.Fa stat . 150A newline is appended. 151Normally used after a procedure call fails for a routine 152for which a client handle is not needed, for instance 153.Fn rpc_call . 154.It Fn clnt_perror 155Print a message to the standard error indicating why an 156RPC call failed; 157.Fa clnt 158is the handle used to do the call. 159The message is prepended with string 160.Fa s 161and a colon. 162A newline is appended. 163Normally used after a remote procedure call fails 164for a routine which requires a client handle, 165for instance 166.Fn clnt_call . 167.It Fn clnt_sperrno 168Take the same arguments as 169.Fn clnt_perrno , 170but instead of sending a message to the standard error 171indicating why an RPC 172call failed, return a pointer to a string which contains the message. 173The 174.Fn clnt_sperrno 175function 176is normally used instead of 177.Fn clnt_perrno 178when the program does not have a standard error (as a program 179running as a server quite likely does not), or if the programmer 180does not want the message to be output with 181.Fn printf 182(see 183.Xr printf 3 ) , 184or if a message format different than that supported by 185.Fn clnt_perrno 186is to be used. 187Note: 188unlike 189.Fn clnt_sperror 190and 191.Fn clnt_spcreateerror 192(see 193.Xr rpc_clnt_create 3 ) , 194.Fn clnt_sperrno 195does not return pointer to static data so the 196result will not get overwritten on each call. 197.It Fn clnt_sperror 198Like 199.Fn clnt_perror , 200except that (like 201.Fn clnt_sperrno ) 202it returns a string instead of printing to standard error. 203However, 204.Fn clnt_sperror 205does not append a newline at the end of the message. 206Warning: 207returns pointer to a buffer that is overwritten 208on each call. 209.It Fn rpc_broadcast 210Like 211.Fn rpc_call , 212except the call message is broadcast to 213all the connectionless transports specified by 214.Fa nettype . 215If 216.Fa nettype 217is 218.Dv NULL , 219it defaults to 220.Qq netpath . 221Each time it receives a response, 222this routine calls 223.Fn eachresult , 224whose form is: 225.Ft bool_t 226.Fn eachresult "caddr_t out" "const struct netbuf * addr" "const struct netconfig * netconf" 227where 228.Fa out 229is the same as 230.Fa out 231passed to 232.Fn rpc_broadcast , 233except that the remote procedure's output is decoded there; 234.Fa addr 235points to the address of the machine that sent the results, and 236.Fa netconf 237is the netconfig structure of the transport on which the remote 238server responded. 239If 240.Fn eachresult 241returns 0, 242.Fn rpc_broadcast 243waits for more replies; 244otherwise it returns with appropriate status. 245Warning: 246broadcast file descriptors are limited in size to the 247maximum transfer size of that transport. 248For Ethernet, this value is 1500 bytes. 249The 250.Fn rpc_broadcast 251function 252uses 253.Dv AUTH_SYS 254credentials by default (see 255.Xr rpc_clnt_auth 3 ) . 256.It Fn rpc_broadcast_exp 257Like 258.Fn rpc_broadcast , 259except that the initial timeout, 260.Fa inittime 261and the maximum timeout, 262.Fa waittime 263are specified in milliseconds. 264The 265.Fa inittime 266argument 267is the initial time that 268.Fn rpc_broadcast_exp 269waits before resending the request. 270After the first resend, the re-transmission interval 271increases exponentially until it exceeds 272.Fa waittime . 273.It Fn rpc_call 274Call the remote procedure associated with 275.Fa prognum , 276.Fa versnum , 277and 278.Fa procnum 279on the machine, 280.Fa host . 281The 282.Fa inproc 283argument 284is used to encode the procedure's arguments, and 285.Fa outproc 286is used to decode the procedure's results; 287.Fa in 288is the address of the procedure's argument(s), and 289.Fa out 290is the address of where to place the result(s). 291The 292.Fa nettype 293argument 294can be any of the values listed on 295.Xr rpc 3 . 296This routine returns 297.Dv RPC_SUCCESS 298if it succeeds, 299or an appropriate status is returned. 300Use the 301.Fn clnt_perrno 302routine to translate failure status into error messages. 303Warning: 304.Fn rpc_call 305uses the first available transport belonging 306to the class 307.Fa nettype , 308on which it can create a connection. 309You do not have control of timeouts or authentication 310using this routine. 311.El 312.Sh SEE ALSO 313.Xr printf 3 , 314.Xr rpc 3 , 315.Xr rpc_clnt_auth 3 , 316.Xr rpc_clnt_create 3 317