]>
Commit | Line | Data |
---|---|---|
28f540f4 RM |
1 | /* |
2 | * svc.h, Server-side remote procedure call interface. | |
3 | * | |
2b778ceb | 4 | * Copyright (C) 2012-2021 Free Software Foundation, Inc. |
14bc93a9 JL |
5 | * This file is part of the GNU C Library. |
6 | * | |
7 | * The GNU C Library is free software; you can redistribute it and/or | |
8 | * modify it under the terms of the GNU Lesser General Public | |
9 | * License as published by the Free Software Foundation; either | |
10 | * version 2.1 of the License, or (at your option) any later version. | |
11 | * | |
12 | * The GNU C Library is distributed in the hope that it will be useful, | |
13 | * but WITHOUT ANY WARRANTY; without even the implied warranty of | |
14 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | |
15 | * Lesser General Public License for more details. | |
16 | * | |
17 | * You should have received a copy of the GNU Lesser General Public | |
18 | * License along with the GNU C Library; if not, see | |
5a82c748 | 19 | * <https://www.gnu.org/licenses/>. |
14bc93a9 | 20 | * |
a7ab6ec8 UD |
21 | * Copyright (c) 2010, Oracle America, Inc. |
22 | * | |
23 | * Redistribution and use in source and binary forms, with or without | |
24 | * modification, are permitted provided that the following conditions are | |
25 | * met: | |
26 | * | |
27 | * * Redistributions of source code must retain the above copyright | |
28 | * notice, this list of conditions and the following disclaimer. | |
29 | * * Redistributions in binary form must reproduce the above | |
30 | * copyright notice, this list of conditions and the following | |
31 | * disclaimer in the documentation and/or other materials | |
32 | * provided with the distribution. | |
33 | * * Neither the name of the "Oracle America, Inc." nor the names of its | |
34 | * contributors may be used to endorse or promote products derived | |
35 | * from this software without specific prior written permission. | |
36 | * | |
37 | * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS | |
38 | * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT | |
39 | * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS | |
40 | * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE | |
41 | * COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, | |
42 | * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |
43 | * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE | |
44 | * GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS | |
45 | * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, | |
46 | * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING | |
47 | * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE | |
48 | * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. | |
28f540f4 RM |
49 | */ |
50 | ||
5107cf1d UD |
51 | #ifndef _RPC_SVC_H |
52 | #define _RPC_SVC_H 1 | |
28f540f4 | 53 | |
e7fd8a39 UD |
54 | #include <features.h> |
55 | #include <rpc/rpc_msg.h> | |
56 | ||
fc933e28 RM |
57 | __BEGIN_DECLS |
58 | ||
28f540f4 RM |
59 | /* |
60 | * This interface must manage two items concerning remote procedure calling: | |
61 | * | |
62 | * 1) An arbitrary number of transport connections upon which rpc requests | |
63 | * are received. The two most notable transports are TCP and UDP; they are | |
64 | * created and registered by routines in svc_tcp.c and svc_udp.c, respectively; | |
65 | * they in turn call xprt_register and xprt_unregister. | |
66 | * | |
67 | * 2) An arbitrary number of locally registered services. Services are | |
68 | * described by the following four data: program number, version number, | |
69 | * "service dispatch" function, a transport handle, and a boolean that | |
70 | * indicates whether or not the exported program should be registered with a | |
71 | * local binder service; if true the program's number and version and the | |
72 | * port number from the transport handle are registered with the binder. | |
73 | * These data are registered with the rpc svc system via svc_register. | |
74 | * | |
75 | * A service's dispatch function is called whenever an rpc request comes in | |
76 | * on a transport. The request's program and version numbers must match | |
77 | * those of the registered service. The dispatch function is passed two | |
78 | * parameters, struct svc_req * and SVCXPRT *, defined below. | |
79 | */ | |
80 | ||
81 | enum xprt_stat { | |
82 | XPRT_DIED, | |
83 | XPRT_MOREREQS, | |
84 | XPRT_IDLE | |
85 | }; | |
86 | ||
87 | /* | |
88 | * Server side transport handle | |
89 | */ | |
e7fd8a39 UD |
90 | typedef struct SVCXPRT SVCXPRT; |
91 | struct SVCXPRT { | |
92 | int xp_sock; | |
93 | u_short xp_port; /* associated port number */ | |
94 | const struct xp_ops { | |
c1422e5b | 95 | bool_t (*xp_recv) (SVCXPRT *__xprt, struct rpc_msg *__msg); |
e7fd8a39 | 96 | /* receive incoming requests */ |
c1422e5b | 97 | enum xprt_stat (*xp_stat) (SVCXPRT *__xprt); |
e7fd8a39 | 98 | /* get transport status */ |
c1422e5b | 99 | bool_t (*xp_getargs) (SVCXPRT *__xprt, xdrproc_t __xdr_args, |
d82a27f8 | 100 | caddr_t __args_ptr); /* get arguments */ |
c1422e5b | 101 | bool_t (*xp_reply) (SVCXPRT *__xprt, struct rpc_msg *__msg); |
e7fd8a39 | 102 | /* send reply */ |
c1422e5b | 103 | bool_t (*xp_freeargs) (SVCXPRT *__xprt, xdrproc_t __xdr_args, |
d82a27f8 | 104 | caddr_t __args_ptr); |
e7fd8a39 | 105 | /* free mem allocated for args */ |
c1422e5b | 106 | void (*xp_destroy) (SVCXPRT *__xprt); |
e7fd8a39 UD |
107 | /* destroy this struct */ |
108 | } *xp_ops; | |
109 | int xp_addrlen; /* length of remote address */ | |
be18eced | 110 | struct sockaddr_in xp_raddr; /* remote address */ |
e7fd8a39 UD |
111 | struct opaque_auth xp_verf; /* raw response verifier */ |
112 | caddr_t xp_p1; /* private */ | |
113 | caddr_t xp_p2; /* private */ | |
ada24bb2 | 114 | char xp_pad [256]; /* padding, internal use */ |
e7fd8a39 | 115 | }; |
28f540f4 RM |
116 | |
117 | /* | |
118 | * Approved way of getting address of caller | |
119 | */ | |
120 | #define svc_getcaller(x) (&(x)->xp_raddr) | |
121 | ||
122 | /* | |
123 | * Operations defined on an SVCXPRT handle | |
124 | * | |
125 | * SVCXPRT *xprt; | |
126 | * struct rpc_msg *msg; | |
127 | * xdrproc_t xargs; | |
128 | * caddr_t argsp; | |
129 | */ | |
130 | #define SVC_RECV(xprt, msg) \ | |
131 | (*(xprt)->xp_ops->xp_recv)((xprt), (msg)) | |
132 | #define svc_recv(xprt, msg) \ | |
133 | (*(xprt)->xp_ops->xp_recv)((xprt), (msg)) | |
134 | ||
135 | #define SVC_STAT(xprt) \ | |
136 | (*(xprt)->xp_ops->xp_stat)(xprt) | |
137 | #define svc_stat(xprt) \ | |
138 | (*(xprt)->xp_ops->xp_stat)(xprt) | |
139 | ||
140 | #define SVC_GETARGS(xprt, xargs, argsp) \ | |
141 | (*(xprt)->xp_ops->xp_getargs)((xprt), (xargs), (argsp)) | |
142 | #define svc_getargs(xprt, xargs, argsp) \ | |
143 | (*(xprt)->xp_ops->xp_getargs)((xprt), (xargs), (argsp)) | |
144 | ||
145 | #define SVC_REPLY(xprt, msg) \ | |
146 | (*(xprt)->xp_ops->xp_reply) ((xprt), (msg)) | |
147 | #define svc_reply(xprt, msg) \ | |
148 | (*(xprt)->xp_ops->xp_reply) ((xprt), (msg)) | |
149 | ||
150 | #define SVC_FREEARGS(xprt, xargs, argsp) \ | |
151 | (*(xprt)->xp_ops->xp_freeargs)((xprt), (xargs), (argsp)) | |
152 | #define svc_freeargs(xprt, xargs, argsp) \ | |
153 | (*(xprt)->xp_ops->xp_freeargs)((xprt), (xargs), (argsp)) | |
154 | ||
155 | #define SVC_DESTROY(xprt) \ | |
156 | (*(xprt)->xp_ops->xp_destroy)(xprt) | |
157 | #define svc_destroy(xprt) \ | |
158 | (*(xprt)->xp_ops->xp_destroy)(xprt) | |
159 | ||
160 | ||
161 | /* | |
162 | * Service request | |
163 | */ | |
164 | struct svc_req { | |
bdb04ee8 UD |
165 | rpcprog_t rq_prog; /* service program number */ |
166 | rpcvers_t rq_vers; /* service protocol version */ | |
167 | rpcproc_t rq_proc; /* the desired procedure */ | |
168 | struct opaque_auth rq_cred; /* raw creds from the wire */ | |
169 | caddr_t rq_clntcred; /* read only cooked cred */ | |
170 | SVCXPRT *rq_xprt; /* associated transport */ | |
28f540f4 RM |
171 | }; |
172 | ||
76b87c03 | 173 | #ifndef __DISPATCH_FN_T |
50304ef0 | 174 | #define __DISPATCH_FN_T |
c1422e5b | 175 | typedef void (*__dispatch_fn_t) (struct svc_req*, SVCXPRT*); |
50304ef0 | 176 | #endif |
28f540f4 RM |
177 | |
178 | /* | |
179 | * Service registration | |
180 | * | |
181 | * svc_register(xprt, prog, vers, dispatch, protocol) | |
182 | * SVCXPRT *xprt; | |
bdb04ee8 UD |
183 | * rpcprog_t prog; |
184 | * rpcvers_t vers; | |
0ebfb8d7 | 185 | * void (*dispatch)(struct svc_req*, SVCXPRT*); |
bdb04ee8 | 186 | * rpcprot_t protocol; like TCP or UDP, zero means do not register |
28f540f4 | 187 | */ |
c1422e5b UD |
188 | extern bool_t svc_register (SVCXPRT *__xprt, rpcprog_t __prog, |
189 | rpcvers_t __vers, __dispatch_fn_t __dispatch, | |
190 | rpcprot_t __protocol) __THROW; | |
28f540f4 RM |
191 | |
192 | /* | |
193 | * Service un-registration | |
194 | * | |
195 | * svc_unregister(prog, vers) | |
bdb04ee8 UD |
196 | * rpcprog_t prog; |
197 | * rpcvers_t vers; | |
28f540f4 | 198 | */ |
c1422e5b | 199 | extern void svc_unregister (rpcprog_t __prog, rpcvers_t __vers) __THROW; |
28f540f4 RM |
200 | |
201 | /* | |
202 | * Transport registration. | |
203 | * | |
204 | * xprt_register(xprt) | |
205 | * SVCXPRT *xprt; | |
206 | */ | |
c1422e5b | 207 | extern void xprt_register (SVCXPRT *__xprt) __THROW; |
28f540f4 RM |
208 | |
209 | /* | |
210 | * Transport un-register | |
211 | * | |
212 | * xprt_unregister(xprt) | |
213 | * SVCXPRT *xprt; | |
214 | */ | |
c1422e5b | 215 | extern void xprt_unregister (SVCXPRT *__xprt) __THROW; |
28f540f4 RM |
216 | |
217 | ||
218 | /* | |
219 | * When the service routine is called, it must first check to see if it | |
220 | * knows about the procedure; if not, it should call svcerr_noproc | |
fc933e28 | 221 | * and return. If so, it should deserialize its arguments via |
28f540f4 RM |
222 | * SVC_GETARGS (defined above). If the deserialization does not work, |
223 | * svcerr_decode should be called followed by a return. Successful | |
224 | * decoding of the arguments should be followed the execution of the | |
225 | * procedure's code and a call to svc_sendreply. | |
226 | * | |
227 | * Also, if the service refuses to execute the procedure due to too- | |
228 | * weak authentication parameters, svcerr_weakauth should be called. | |
229 | * Note: do not confuse access-control failure with weak authentication! | |
230 | * | |
231 | * NB: In pure implementations of rpc, the caller always waits for a reply | |
fc933e28 | 232 | * msg. This message is sent when svc_sendreply is called. |
28f540f4 RM |
233 | * Therefore pure service implementations should always call |
234 | * svc_sendreply even if the function logically returns void; use | |
235 | * xdr.h - xdr_void for the xdr routine. HOWEVER, tcp based rpc allows | |
236 | * for the abuse of pure rpc via batched calling or pipelining. In the | |
237 | * case of a batched call, svc_sendreply should NOT be called since | |
238 | * this would send a return message, which is what batching tries to avoid. | |
239 | * It is the service/protocol writer's responsibility to know which calls are | |
240 | * batched and which are not. Warning: responding to batch calls may | |
241 | * deadlock the caller and server processes! | |
242 | */ | |
243 | ||
d82a27f8 | 244 | extern bool_t svc_sendreply (SVCXPRT *__xprt, xdrproc_t __xdr_results, |
c1422e5b | 245 | caddr_t __xdr_location) __THROW; |
fc933e28 | 246 | |
c1422e5b | 247 | extern void svcerr_decode (SVCXPRT *__xprt) __THROW; |
fc933e28 | 248 | |
c1422e5b | 249 | extern void svcerr_weakauth (SVCXPRT *__xprt) __THROW; |
fc933e28 | 250 | |
c1422e5b | 251 | extern void svcerr_noproc (SVCXPRT *__xprt) __THROW; |
fc933e28 | 252 | |
c1422e5b UD |
253 | extern void svcerr_progvers (SVCXPRT *__xprt, rpcvers_t __low_vers, |
254 | rpcvers_t __high_vers) __THROW; | |
fc933e28 | 255 | |
c1422e5b | 256 | extern void svcerr_auth (SVCXPRT *__xprt, enum auth_stat __why) __THROW; |
fc933e28 | 257 | |
c1422e5b | 258 | extern void svcerr_noprog (SVCXPRT *__xprt) __THROW; |
fc933e28 | 259 | |
c1422e5b | 260 | extern void svcerr_systemerr (SVCXPRT *__xprt) __THROW; |
fc933e28 | 261 | |
28f540f4 RM |
262 | /* |
263 | * Lowest level dispatching -OR- who owns this process anyway. | |
264 | * Somebody has to wait for incoming requests and then call the correct | |
265 | * service routine. The routine svc_run does infinite waiting; i.e., | |
266 | * svc_run never returns. | |
5b826692 | 267 | * Since another (coexistent) package may wish to selectively wait for |
28f540f4 RM |
268 | * incoming calls or other events outside of the rpc architecture, the |
269 | * routine svc_getreq is provided. It must be passed readfds, the | |
270 | * "in-place" results of a select system call (see select, section 2). | |
271 | */ | |
272 | ||
273 | /* | |
274 | * Global keeper of rpc service descriptors in use | |
fc933e28 | 275 | * dynamic; must be inspected before each call to select |
28f540f4 | 276 | */ |
bdb04ee8 UD |
277 | |
278 | extern struct pollfd *svc_pollfd; | |
279 | extern int svc_max_pollfd; | |
28f540f4 RM |
280 | extern fd_set svc_fdset; |
281 | #define svc_fds svc_fdset.fds_bits[0] /* compatibility */ | |
28f540f4 RM |
282 | |
283 | /* | |
284 | * a small program implemented by the svc_rpc implementation itself; | |
285 | * also see clnt.h for protocol numbers. | |
286 | */ | |
c1422e5b UD |
287 | extern void svc_getreq (int __rdfds) __THROW; |
288 | extern void svc_getreq_common (const int __fd) __THROW; | |
289 | extern void svc_getreqset (fd_set *__readfds) __THROW; | |
290 | extern void svc_getreq_poll (struct pollfd *, const int) __THROW; | |
291 | extern void svc_exit (void) __THROW; | |
292 | extern void svc_run (void) __THROW; | |
28f540f4 RM |
293 | |
294 | /* | |
295 | * Socket to use on svcxxx_create call to get default socket | |
296 | */ | |
297 | #define RPC_ANYSOCK -1 | |
298 | ||
299 | /* | |
300 | * These are the existing service side transport implementations | |
301 | */ | |
302 | ||
303 | /* | |
304 | * Memory based rpc for testing and timing. | |
305 | */ | |
c1422e5b | 306 | extern SVCXPRT *svcraw_create (void) __THROW; |
28f540f4 RM |
307 | |
308 | /* | |
309 | * Udp based rpc. | |
310 | */ | |
c1422e5b UD |
311 | extern SVCXPRT *svcudp_create (int __sock) __THROW; |
312 | extern SVCXPRT *svcudp_bufcreate (int __sock, u_int __sendsz, u_int __recvsz) | |
313 | __THROW; | |
28f540f4 RM |
314 | |
315 | /* | |
316 | * Tcp based rpc. | |
317 | */ | |
c1422e5b UD |
318 | extern SVCXPRT *svctcp_create (int __sock, u_int __sendsize, u_int __recvsize) |
319 | __THROW; | |
28f540f4 | 320 | |
2bcaff08 UD |
321 | /* |
322 | * FD based rpc. | |
323 | */ | |
324 | extern SVCXPRT *svcfd_create (int __sock, u_int __sendsize, u_int __recvsize) | |
325 | __THROW; | |
28f540f4 | 326 | |
e852e889 UD |
327 | /* |
328 | * Unix based rpc. | |
329 | */ | |
c1422e5b UD |
330 | extern SVCXPRT *svcunix_create (int __sock, u_int __sendsize, u_int __recvsize, |
331 | char *__path) __THROW; | |
e852e889 UD |
332 | |
333 | ||
fc933e28 | 334 | __END_DECLS |
28f540f4 | 335 | |
5107cf1d | 336 | #endif /* rpc/svc.h */ |