| blob | 3eeacd0bcd88b5cb78dcff00e5caea038f488218 |
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