man/rpc_svc_calls.3t

   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.8 2003/09/08 19:57:15 ru Exp $
   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 SYNOPSIS
  25 .In rpc/rpc.h
  26 .Ft int
  27 .Fn svc_dg_enablecache "SVCXPRT *xprt" "const unsigned cache_size"
  28 .Ft void
  29 .Fn svc_exit "void"
  30 .Ft bool_t
  31 .Fn svc_freeargs "const SVCXPRT *xprt" "const xdrproc_t inproc" "caddr_t in"
  32 .Ft bool_t
  33 .Fn svc_getargs "const SVCXPRT *xprt" "const xdrproc_t inproc" "caddr_t in"
  34 .Ft void
  35 .Fn svc_getreq_common "const int fd"
  36 .Ft void
  37 .Fn svc_getreq_poll "struct pollfd *pfdp" "const int pollretval"
  38 .Ft void
  39 .Fn svc_getreqset "fd_set * rdfds"
  40 .Ft "struct netbuf *"
  41 .Fn svc_getrpccaller "const SVCXPRT *xprt"
  42 .Ft "struct cmsgcred *"
  43 .Fn __svc_getcallercreds "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" "char *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 __svc_getcallercreds()
  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 Fn __svc_getcallercreds
 198 .Em Warning :
 199 this macro is specific to
 200 .Fx
 201 and thus not portable.
 202 This macro returns a pointer to a
 203 .Vt cmsgcred
 204 structure, defined in
 205 .In sys/socket.h ,
 206 identifying the calling client.
 207 This only works if the client is
 208 calling the server over an
 209 .Dv AF_LOCAL
 210 socket.
 211 .It Xo
 212 .Vt struct pollfd Va svc_pollset[FD_SETSIZE] ;
 213 .Xc
 214 .Va svc_pollset
 215 is an array of
 216 .Vt pollfd
 217 structures derived from
 218 .Va svc_fdset[] .
 219 It is suitable as an argument to the
 220 .Xr poll 2
 221 system call.
 222 The derivation of
 223 .Va svc_pollset
 224 from
 225 .Va svc_fdset
 226 is made in the current implementation in
 227 .Fn svc_run .
 228 Service implementors who do not call
 229 .Fn svc_run
 230 and who wish to use this array must perform this derivation themselves.
 231 .It Fn svc_run
 232 This routine never returns.
 233 It waits for RPC
 234 requests to arrive, and calls the appropriate service
 235 procedure using
 236 .Fn svc_getreq_poll
 237 when one arrives.
 238 This procedure is usually waiting for the
 239 .Xr poll 2
 240 system call to return.
 241 .It Fn svc_sendreply
 242 Called by an RPC service's dispatch routine to send the results of a
 243 remote procedure call.
 244 The
 245 .Fa xprt
 246 argument
 247 is the request's associated transport handle;
 248 .Fa outproc
 249 is the XDR
 250 routine which is used to encode the results; and
 251 .Fa out
 252 is the address of the results.
 253 This routine returns
 254 .Dv TRUE
 255 if it succeeds,
 256 .Dv FALSE
 257 otherwise.
 258 .El
 259 .Sh AVAILABILITY
 260 These functions are part of libtirpc.
 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