man/rpc_clnt_calls.3t

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