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