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$ 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 parameters. 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 parameter 111.Fa inproc 112is the XDR function used to encode the procedure's parameters, 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). 119.Fa tout 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 parameter 132.Fa out 133is the address of the results, and 134.Fa outproc 135is the XDR routine describing the results. 136This routine returns 1 if the results were successfully freed, 137and 0 otherwise. 138.It Fn clnt_geterr 139A function macro that copies the error structure out of the client 140handle to the structure at address 141.Fa errp . 142.It Fn clnt_perrno 143Print a message to standard error corresponding 144to the condition indicated by 145.Fa stat . 146A newline is appended. 147Normally used after a procedure call fails for a routine 148for which a client handle is not needed, for instance 149.Fn rpc_call . 150.It Fn clnt_perror 151Print a message to the standard error indicating why an 152RPC call failed; 153.Fa clnt 154is the handle used to do the call. 155The message is prepended with string 156.Fa s 157and a colon. 158A newline is appended. 159Normally used after a remote procedure call fails 160for a routine which requires a client handle, 161for instance 162.Fn clnt_call . 163.It Fn clnt_sperrno 164Take the same arguments as 165.Fn clnt_perrno , 166but instead of sending a message to the standard error 167indicating why an RPC 168call failed, return a pointer to a string which contains the message. 169.Fn clnt_sperrno 170is normally used instead of 171.Fn clnt_perrno 172when the program does not have a standard error (as a program 173running as a server quite likely does not), or if the programmer 174does not want the message to be output with 175.Fn printf 176(see 177.Xr printf 3 ) , 178or if a message format different than that supported by 179.Fn clnt_perrno 180is to be used. 181Note: 182unlike 183.Fn clnt_sperror 184and 185.Fn clnt_spcreateerror 186(see 187.Xr rpc_clnt_create 3 ) , 188.Fn clnt_sperrno 189does not return pointer to static data so the 190result will not get overwritten on each call. 191.It Fn clnt_sperror 192Like 193.Fn clnt_perror , 194except that (like 195.Fn clnt_sperrno ) 196it returns a string instead of printing to standard error. 197However, 198.Fn clnt_sperror 199does not append a newline at the end of the message. 200Warning: 201returns pointer to a buffer that is overwritten 202on each call. 203.It Fn rpc_broadcast 204Like 205.Fn rpc_call , 206except the call message is broadcast to 207all the connectionless transports specified by 208.Fa nettype . 209If 210.Fa nettype 211is 212.Dv NULL , 213it defaults to 214.Qq netpath . 215Each time it receives a response, 216this routine calls 217.Fn eachresult , 218whose form is: 219.Ft bool_t 220.Fn eachresult "caddr_t out" "const struct netbuf * addr" "const struct netconfig * netconf" 221where 222.Fa out 223is the same as 224.Fa out 225passed to 226.Fn rpc_broadcast , 227except that the remote procedure's output is decoded there; 228.Fa addr 229points to the address of the machine that sent the results, and 230.Fa netconf 231is the netconfig structure of the transport on which the remote 232server responded. 233If 234.Fn eachresult 235returns 0, 236.Fn rpc_broadcast 237waits for more replies; 238otherwise it returns with appropriate status. 239Warning: 240broadcast file descriptors are limited in size to the 241maximum transfer size of that transport. 242For Ethernet, this value is 1500 bytes. 243.Fn rpc_broadcast 244uses 245.Dv AUTH_SYS 246credentials by default (see 247.Xr rpc_clnt_auth 3 ) . 248.It Fn rpc_broadcast_exp 249Like 250.Fn rpc_broadcast , 251except that the initial timeout, 252.Fa inittime 253and the maximum timeout, 254.Fa waittime 255are specified in milliseconds. 256.Fa inittime 257is the initial time that 258.Fn rpc_broadcast_exp 259waits before resending the request. 260After the first resend, the re-transmission interval 261increases exponentially until it exceeds 262.Fa waittime . 263.It Fn rpc_call 264Call the remote procedure associated with 265.Fa prognum , 266.Fa versnum , 267and 268.Fa procnum 269on the machine, 270.Fa host . 271The parameter 272.Fa inproc 273is used to encode the procedure's parameters, and 274.Fa outproc 275is used to decode the procedure's results; 276.Fa in 277is the address of the procedure's argument(s), and 278.Fa out 279is the address of where to place the result(s). 280.Fa nettype 281can be any of the values listed on 282.Xr rpc 3 . 283This routine returns 284.Dv RPC_SUCCESS 285if it succeeds, 286or an appropriate status is returned. 287Use the 288.Fn clnt_perrno 289routine to translate failure status into error messages. 290Warning: 291.Fn rpc_call 292uses the first available transport belonging 293to the class 294.Fa nettype , 295on which it can create a connection. 296You do not have control of timeouts or authentication 297using this routine. 298.El 299.Sh SEE ALSO 300.Xr printf 3 , 301.Xr rpc 3 , 302.Xr rpc_clnt_auth 3 , 303.Xr rpc_clnt_create 3 304