lib/libc/rpc/rpc_svc_calls.3

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