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