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