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