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 .Dd January 31, 2009
   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 .Vt struct pollfd svc_pollset[FD_SETSIZE];
  45 .Ft void
  46 .Fn svc_run "void"
  47 .Ft bool_t
  48 .Fn svc_sendreply "SVCXPRT *xprt" "xdrproc_t outproc" "void *out"
  49 .Sh DESCRIPTION
  50 These routines are part of the
  51 RPC
  52 library which allows C language programs to make procedure
  53 calls on other machines across the network.
  54 .Pp
  55 These routines are associated with the server side of the
  56 RPC mechanism.
  57 Some of them are called by the server side dispatch function,
  58 while others
  59 (such as
  60 .Fn svc_run )
  61 are called when the server is initiated.
  62 .\" .Pp
  63 .\" In the current implementation, the service transport handle,
  64 .\" .Dv SVCXPRT ,
  65 .\" contains a single data area for decoding arguments and encoding results.
  66 .\" Therefore, this structure cannot be freely shared between threads that call
  67 .\" functions that do this.
  68 .\" 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 .Vt SVCXPRT
  75 data structure.
  76 .Bl -tag -width ".Fn svc_dg_enablecache"
  77 .It Fn svc_dg_enablecache
  78 This function allocates a duplicate request cache for the
  79 service endpoint
  80 .Fa xprt ,
  81 large enough to hold
  82 .Fa cache_size
  83 entries.
  84 Once enabled, there is no way to disable caching.
  85 This routine returns 0 if space necessary for a cache of the given size
  86 was successfully allocated, and 1 otherwise.
  87 .It Fn svc_exit
  88 This function, when called by any of the RPC server procedure or
  89 otherwise, causes
  90 .Fn svc_run
  91 to return.
  92 .Pp
  93 As currently implemented,
  94 .Fn svc_exit
  95 zeroes the
  96 .Va svc_fdset
  97 global variable.
  98 If RPC server activity is to be resumed,
  99 services must be reregistered with the RPC library
 100 either through one of the
 101 .Xr rpc_svc_create 3
 102 functions, or using
 103 .Fn xprt_register .
 104 The
 105 .Fn svc_exit
 106 function
 107 has global scope and ends all RPC server activity.
 108 .It Xo
 109 .Vt fd_set Va svc_fdset
 110 .Xc
 111 A global variable reflecting the
 112 RPC server's read file descriptor bit mask; it is suitable as an argument
 113 to the
 114 .Xr select 2
 115 system call.
 116 This is only of interest
 117 if service implementors do not call
 118 .Fn svc_run ,
 119 but rather do their own asynchronous event processing.
 120 This variable is read-only (do not pass its address to
 121 .Xr select 2 ! ) ,
 122 yet it may change after calls to
 123 .Fn svc_getreqset
 124 or any creation routines.
 125 .It Fn svc_freeargs
 126 A function macro that frees any data allocated by the
 127 RPC/XDR system when it decoded the arguments to a service procedure
 128 using
 129 .Fn svc_getargs .
 130 This routine returns
 131 .Dv TRUE
 132 if the results were successfully
 133 freed, and
 134 .Dv FALSE
 135 otherwise.
 136 .It Fn svc_getargs
 137 A function macro that decodes the arguments of an
 138 RPC request associated with the RPC
 139 service transport handle
 140 .Fa xprt .
 141 The
 142 .Fa in
 143 argument
 144 is the address where the arguments will be placed;
 145 .Fa inproc
 146 is the XDR
 147 routine used to decode the arguments.
 148 This routine returns
 149 .Dv TRUE
 150 if decoding succeeds, and
 151 .Dv FALSE
 152 otherwise.
 153 .It Fn svc_getreq_common
 154 This routine is called to handle a request on the given
 155 file descriptor.
 156 .It Fn svc_getreq_poll
 157 This routine is only of interest if a service implementor
 158 does not call
 159 .Fn svc_run ,
 160 but instead implements custom asynchronous event processing.
 161 It is called when
 162 .Xr poll 2
 163 has determined that an RPC request has arrived on some RPC
 164 file descriptors;
 165 .Fa pollretval
 166 is the return value from
 167 .Xr poll 2
 168 and
 169 .Fa pfdp
 170 is the array of
 171 .Vt pollfd
 172 structures on which the
 173 .Xr poll 2
 174 was done.
 175 It is assumed to be an array large enough to
 176 contain the maximal number of descriptors allowed.
 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 .It Fn svc_getrpccaller
 193 The approved way of getting the network address of the caller
 194 of a procedure associated with the
 195 RPC service transport handle
 196 .Fa xprt .
 197 .It Xo
 198 .Vt struct pollfd Va svc_pollset[FD_SETSIZE] ;
 199 .Xc
 200 .Va svc_pollset
 201 is an array of
 202 .Vt pollfd
 203 structures derived from
 204 .Va svc_fdset[] .
 205 It is suitable as an argument to the
 206 .Xr poll 2
 207 system call.
 208 The derivation of
 209 .Va svc_pollset
 210 from
 211 .Va svc_fdset
 212 is made in the current implementation in
 213 .Fn svc_run .
 214 Service implementors who do not call
 215 .Fn svc_run
 216 and who wish to use this array must perform this derivation themselves.
 217 .It Fn svc_run
 218 This routine never returns.
 219 It waits for RPC
 220 requests to arrive, and calls the appropriate service
 221 procedure using
 222 .Fn svc_getreq_poll
 223 when one arrives.
 224 This procedure is usually waiting for the
 225 .Xr poll 2
 226 system call to return.
 227 .It Fn svc_sendreply
 228 Called by an RPC service's dispatch routine to send the results of a
 229 remote procedure call.
 230 The
 231 .Fa xprt
 232 argument
 233 is the request's associated transport handle;
 234 .Fa outproc
 235 is the XDR
 236 routine which is used to encode the results; and
 237 .Fa out
 238 is the address of the results.
 239 This routine returns
 240 .Dv TRUE
 241 if it succeeds,
 242 .Dv FALSE
 243 otherwise.
 244 .El
 245 .Sh SEE ALSO
 246 .Xr poll 2 ,
 247 .Xr select 2 ,
 248 .Xr rpc 3 ,
 249 .Xr rpc_svc_create 3 ,
 250 .Xr rpc_svc_err 3 ,
 251 .Xr rpc_svc_reg 3