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