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