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