lib/libc/rpc/rpc_svc_calls.3

   1 .\" Copyright 1989 AT&T
   2 .\" Copyright (c) 1988 Sun Microsystems, Inc. - All Rights Reserved.
   3 .\"     $NetBSD: rpc_svc_calls.3,v 1.1 2000/06/02 23:11:13 fvdl Exp $
   4 .Dd May 3, 1993
   5 .Dt RPC_SVC_CALLS 3
   6 .Os
   7 .Sh NAME
   8 .Nm svc_dg_enablecache ,
   9 .Nm svc_exit ,
  10 .Nm svc_fdset ,
  11 .Nm svc_freeargs ,
  12 .Nm svc_getargs ,
  13 .Nm svc_getreq_common ,
  14 .Nm svc_getreq_poll ,
  15 .Nm svc_getreqset ,
  16 .Nm svc_getrpccaller ,
  17 .Nm svc_pollset ,
  18 .Nm svc_run ,
  19 .Nm svc_sendreply
  20 .Nd library routines for RPC servers
  21 .Sh LIBRARY
  22 .Lb libc
  23 .Sh SYNOPSIS
  24 .In rpc/rpc.h
  25 .Ft int
  26 .Fn svc_dg_enablecache "SVCXPRT *xprt" "const unsigned cache_size"
  27 .Ft void
  28 .Fn svc_exit "void"
  29 .Ft bool_t
  30 .Fn svc_freeargs "const SVCXPRT *xprt" "const xdrproc_t inproc" "caddr_t in"
  31 .Ft bool_t
  32 .Fn svc_getargs "const SVCXPRT *xprt" "const xdrproc_t inproc" "caddr_t in"
  33 .Ft void
  34 .Fn svc_getreq_common "const int fd"
  35 .Ft void
  36 .Fn svc_getreq_poll "struct pollfd *pfdp" "const int pollretval"
  37 .Ft void
  38 .Fn svc_getreqset "fd_set * rdfds"
  39 .Ft "struct netbuf *"
  40 .Fn svc_getrpccaller "const SVCXPRT *xprt"
  41 .Ft "struct cmsgcred *"
  42 .Fn __svc_getcallercreds "const SVCXPRT *xprt"
  43 .Vt struct pollfd svc_pollset[FD_SETSIZE];
  44 .Ft void
  45 .Fn svc_run "void"
  46 .Ft bool_t
  47 .Fn svc_sendreply "SVCXPRT *xprt" "xdrproc_t outproc" "void *out"
  48 .Sh DESCRIPTION
  49 These routines are part of the
  50 RPC
  51 library which allows C language programs to make procedure
  52 calls on other machines across the network.
  53 .Pp
  54 These routines are associated with the server side of the
  55 RPC mechanism.
  56 Some of them are called by the server side dispatch function,
  57 while others
  58 (such as
  59 .Fn svc_run )
  60 are called when the server is initiated.
  61 .\" .Pp
  62 .\" In the current implementation, the service transport handle,
  63 .\" .Dv SVCXPRT ,
  64 .\" contains a single data area for decoding arguments and encoding results.
  65 .\" Therefore, this structure cannot be freely shared between threads that call
  66 .\" functions that do this.
  67 .\" Routines on this page that are affected by this
  68 .\" restriction are marked as unsafe for MT applications.
  69 .Sh Routines
  70 See
  71 .Xr rpc 3
  72 for the definition of the
  73 .Vt SVCXPRT
  74 data structure.
  75 .Bl -tag -width __svc_getcallercreds()
  76 .It Fn svc_dg_enablecache
  77 This function allocates a duplicate request cache for the
  78 service endpoint
  79 .Fa xprt ,
  80 large enough to hold
  81 .Fa cache_size
  82 entries.
  83 Once enabled, there is no way to disable caching.
  84 This routine returns 0 if space necessary for a cache of the given size
  85 was successfully allocated, and 1 otherwise.
  86 .It Fn svc_exit
  87 This function, when called by any of the RPC server procedure or
  88 otherwise, causes
  89 .Fn svc_run
  90 to return.
  91 .Pp
  92 As currently implemented,
  93 .Fn svc_exit
  94 zeroes the
  95 .Va svc_fdset
  96 global variable.
  97 If RPC server activity is to be resumed,
  98 services must be reregistered with the RPC library
  99 either through one of the
 100 .Xr rpc_svc_create 3
 101 functions, or using
 102 .Fn xprt_register .
 103 The
 104 .Fn svc_exit
 105 function
 106 has global scope and ends all RPC server activity.
 107 .It Xo
 108 .Vt fd_set Va svc_fdset
 109 .Xc
 110 A global variable reflecting the
 111 RPC server's read file descriptor bit mask; it is suitable as an argument
 112 to the
 113 .Xr select 2
 114 system call.
 115 This is only of interest
 116 if service implementors do not call
 117 .Fn svc_run ,
 118 but rather do their own asynchronous event processing.
 119 This variable is read-only (do not pass its address to
 120 .Xr select 2 ! ) ,
 121 yet it may change after calls to
 122 .Fn svc_getreqset
 123 or any creation routines.
 124 .It Fn svc_freeargs
 125 A function macro that frees any data allocated by the
 126 RPC/XDR system when it decoded the arguments to a service procedure
 127 using
 128 .Fn svc_getargs .
 129 This routine returns
 130 .Dv TRUE
 131 if the results were successfully
 132 freed, and
 133 .Dv FALSE
 134 otherwise.
 135 .It Fn svc_getargs
 136 A function macro that decodes the arguments of an
 137 RPC request associated with the RPC
 138 service transport handle
 139 .Fa xprt .
 140 The
 141 .Fa in
 142 argument
 143 is the address where the arguments will be placed;
 144 .Fa inproc
 145 is the XDR
 146 routine used to decode the arguments.
 147 This routine returns
 148 .Dv TRUE
 149 if decoding succeeds, and
 150 .Dv FALSE
 151 otherwise.
 152 .It Fn svc_getreq_common
 153 This routine is called to handle a request on the given
 154 file descriptor.
 155 .It Fn svc_getreq_poll
 156 This routine is only of interest if a service implementor
 157 does not call
 158 .Fn svc_run ,
 159 but instead implements custom asynchronous event processing.
 160 It is called when
 161 .Xr poll 2
 162 has determined that an RPC request has arrived on some RPC
 163 file descriptors;
 164 .Fa pollretval
 165 is the return value from
 166 .Xr poll 2
 167 and
 168 .Fa pfdp
 169 is the array of
 170 .Vt pollfd
 171 structures on which the
 172 .Xr poll 2
 173 was done.
 174 It is assumed to be an array large enough to
 175 contain the maximal number of descriptors allowed.
 176 .It Fn svc_getreqset
 177 This routine is only of interest if a service implementor
 178 does not call
 179 .Fn svc_run ,
 180 but instead implements custom asynchronous event processing.
 181 It is called when
 182 .Xr poll 2
 183 has determined that an RPC
 184 request has arrived on some RPC file descriptors;
 185 .Fa rdfds
 186 is the resultant read file descriptor bit mask.
 187 The routine returns when all file descriptors
 188 associated with the value of
 189 .Fa rdfds
 190 have been serviced.
 191 .It Fn svc_getrpccaller
 192 The approved way of getting the network address of the caller
 193 of a procedure associated with the
 194 RPC service transport handle
 195 .Fa xprt .
 196 .It Fn __svc_getcallercreds
 197 .Em Warning :
 198 this macro is specific to
 199 .Fx
 200 and thus not portable.
 201 This macro returns a pointer to a
 202 .Vt cmsgcred
 203 structure, defined in
 204 .In sys/socket.h ,
 205 identifying the calling client.
 206 This only works if the client is
 207 calling the server over an
 208 .Dv AF_LOCAL
 209 socket.
 210 .It Xo
 211 .Vt struct pollfd Va svc_pollset[FD_SETSIZE] ;
 212 .Xc
 213 .Va svc_pollset
 214 is an array of
 215 .Vt pollfd
 216 structures derived from
 217 .Va svc_fdset[] .
 218 It is suitable as an argument to the
 219 .Xr poll 2
 220 system call.
 221 The derivation of
 222 .Va svc_pollset
 223 from
 224 .Va svc_fdset
 225 is made in the current implementation in
 226 .Fn svc_run .
 227 Service implementors who do not call
 228 .Fn svc_run
 229 and who wish to use this array must perform this derivation themselves.
 230 .It Fn svc_run
 231 This routine never returns.
 232 It waits for RPC
 233 requests to arrive, and calls the appropriate service
 234 procedure using
 235 .Fn svc_getreq_poll
 236 when one arrives.
 237 This procedure is usually waiting for the
 238 .Xr poll 2
 239 system call to return.
 240 .It Fn svc_sendreply
 241 Called by an RPC service's dispatch routine to send the results of a
 242 remote procedure call.
 243 The
 244 .Fa xprt
 245 argument
 246 is the request's associated transport handle;
 247 .Fa outproc
 248 is the XDR
 249 routine which is used to encode the results; and
 250 .Fa out
 251 is the address of the results.
 252 This routine returns
 253 .Dv TRUE
 254 if it succeeds,
 255 .Dv FALSE
 256 otherwise.
 257 .El
 258 .Sh SEE ALSO
 259 .Xr poll 2 ,
 260 .Xr select 2 ,
 261 .Xr rpc 3 ,
 262 .Xr rpc_svc_create 3 ,
 263 .Xr rpc_svc_err 3 ,
 264 .Xr rpc_svc_reg 3