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