lib/libc/rpc/rpc_clnt_calls.3

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