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