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