master
1/* $NetBSD: svc.h,v 1.33 2022/05/28 21:14:56 andvar Exp $ */
2
3/*
4 * Sun RPC is a product of Sun Microsystems, Inc. and is provided for
5 * unrestricted use provided that this legend is included on all tape
6 * media and as a part of the software program in whole or part. Users
7 * may copy or modify Sun RPC without charge, but are not authorized
8 * to license or distribute it to anyone else except as part of a product or
9 * program developed by the user.
10 *
11 * SUN RPC IS PROVIDED AS IS WITH NO WARRANTIES OF ANY KIND INCLUDING THE
12 * WARRANTIES OF DESIGN, MERCHANTIBILITY AND FITNESS FOR A PARTICULAR
13 * PURPOSE, OR ARISING FROM A COURSE OF DEALING, USAGE OR TRADE PRACTICE.
14 *
15 * Sun RPC is provided with no support and without any obligation on the
16 * part of Sun Microsystems, Inc. to assist in its use, correction,
17 * modification or enhancement.
18 *
19 * SUN MICROSYSTEMS, INC. SHALL HAVE NO LIABILITY WITH RESPECT TO THE
20 * INFRINGEMENT OF COPYRIGHTS, TRADE SECRETS OR ANY PATENTS BY SUN RPC
21 * OR ANY PART THEREOF.
22 *
23 * In no event will Sun Microsystems, Inc. be liable for any lost revenue
24 * or profits or other special, indirect and consequential damages, even if
25 * Sun has been advised of the possibility of such damages.
26 *
27 * Sun Microsystems, Inc.
28 * 2550 Garcia Avenue
29 * Mountain View, California 94043
30 *
31 * from: @(#)svc.h 1.35 88/12/17 SMI
32 * @(#)svc.h 1.27 94/04/25 SMI
33 */
34
35/*
36 * svc.h, Server-side remote procedure call interface.
37 *
38 * Copyright (C) 1986-1993 by Sun Microsystems, Inc.
39 */
40
41#ifndef _RPC_SVC_H_
42#define _RPC_SVC_H_
43#include <sys/cdefs.h>
44
45#include <sys/select.h>
46#include <rpc/rpc_com.h>
47
48/*
49 * This interface must manage two items concerning remote procedure calling:
50 *
51 * 1) An arbitrary number of transport connections upon which rpc requests
52 * are received. The two most notable transports are TCP and UDP; they are
53 * created and registered by routines in svc_tcp.c and svc_udp.c, respectively;
54 * they in turn call xprt_register and xprt_unregister.
55 *
56 * 2) An arbitrary number of locally registered services. Services are
57 * described by the following four data: program number, version number,
58 * "service dispatch" function, a transport handle, and a boolean that
59 * indicates whether or not the exported program should be registered with a
60 * local binder service; if true the program's number and version and the
61 * port number from the transport handle are registered with the binder.
62 * These data are registered with the rpc svc system via svc_register.
63 *
64 * A service's dispatch function is called whenever an rpc request comes in
65 * on a transport. The request's program and version numbers must match
66 * those of the registered service. The dispatch function is passed two
67 * parameters, struct svc_req * and SVCXPRT *, defined below.
68 */
69
70/*
71 * Service control requests
72 */
73#define SVCGET_VERSQUIET 1
74#define SVCSET_VERSQUIET 2
75#define SVCGET_CONNMAXREC 3
76#define SVCSET_CONNMAXREC 4
77
78
79enum xprt_stat {
80 XPRT_DIED,
81 XPRT_MOREREQS,
82 XPRT_IDLE
83};
84
85/*
86 * Server side transport handle
87 */
88typedef struct __rpc_svcxprt {
89 int xp_fd;
90 unsigned short xp_port; /* associated port number */
91 const struct xp_ops {
92 /* receive incoming requests */
93 bool_t (*xp_recv)(struct __rpc_svcxprt *, struct rpc_msg *);
94 /* get transport status */
95 enum xprt_stat (*xp_stat)(struct __rpc_svcxprt *);
96 /* get arguments */
97 bool_t (*xp_getargs)(struct __rpc_svcxprt *, xdrproc_t,
98 caddr_t);
99 /* send reply */
100 bool_t (*xp_reply)(struct __rpc_svcxprt *, struct rpc_msg *);
101 /* free mem allocated for args */
102 bool_t (*xp_freeargs)(struct __rpc_svcxprt *, xdrproc_t,
103 caddr_t);
104 /* destroy this struct */
105 void (*xp_destroy)(struct __rpc_svcxprt *);
106 } *xp_ops;
107 int xp_addrlen; /* length of remote address */
108 struct sockaddr_in xp_raddr; /* rem. addr. (backward ABI compat) */
109 /* XXX - fvdl stick this here for ABI backward compat reasons */
110 const struct xp_ops2 {
111 /* catch-all function */
112 bool_t (*xp_control)(struct __rpc_svcxprt *,
113 const unsigned int, void *);
114 } *xp_ops2;
115 char *xp_tp; /* transport provider device name */
116 char *xp_netid; /* network token */
117 struct netbuf xp_ltaddr; /* local transport address */
118 struct netbuf xp_rtaddr; /* remote transport address */
119 struct opaque_auth xp_verf; /* raw response verifier */
120 void *xp_p1; /* private: for use by svc ops */
121 void *xp_p2; /* private: for use by svc ops */
122 void *xp_p3; /* private: for use by svc lib */
123 int xp_type; /* transport type */
124} SVCXPRT;
125
126/*
127 * Service request
128 */
129struct svc_req {
130 uint32_t rq_prog; /* service program number */
131 uint32_t rq_vers; /* service protocol version */
132 uint32_t rq_proc; /* the desired procedure */
133 struct opaque_auth rq_cred; /* raw creds from the wire */
134 void *rq_clntcred; /* read only cooked cred */
135 SVCXPRT *rq_xprt; /* associated transport */
136};
137
138/*
139 * Approved way of getting address of caller
140 */
141#define svc_getrpccaller(x) (&(x)->xp_rtaddr)
142
143/*
144 * NetBSD-only definition to get the creds of the caller (AF_LOCAL).
145 */
146#define __svc_getcallercreds(x) ((struct sockcred *)(x)->xp_p2)
147
148/*
149 * Operations defined on an SVCXPRT handle
150 *
151 * SVCXPRT *xprt;
152 * struct rpc_msg *msg;
153 * xdrproc_t xargs;
154 * caddr_t argsp;
155 */
156#define SVC_RECV(xprt, msg) \
157 (*(xprt)->xp_ops->xp_recv)((xprt), (msg))
158#define svc_recv(xprt, msg) \
159 (*(xprt)->xp_ops->xp_recv)((xprt), (msg))
160
161#define SVC_STAT(xprt) \
162 (*(xprt)->xp_ops->xp_stat)(xprt)
163#define svc_stat(xprt) \
164 (*(xprt)->xp_ops->xp_stat)(xprt)
165
166#define SVC_GETARGS(xprt, xargs, argsp) \
167 (*(xprt)->xp_ops->xp_getargs)((xprt), ((xdrproc_t)(xargs)), (argsp))
168#define svc_getargs(xprt, xargs, argsp) \
169 (*(xprt)->xp_ops->xp_getargs)((xprt), ((xdrproc_t)(xargs)), (argsp))
170
171#define SVC_REPLY(xprt, msg) \
172 (*(xprt)->xp_ops->xp_reply) ((xprt), (msg))
173#define svc_reply(xprt, msg) \
174 (*(xprt)->xp_ops->xp_reply) ((xprt), (msg))
175
176#define SVC_FREEARGS(xprt, xargs, argsp) \
177 (*(xprt)->xp_ops->xp_freeargs)((xprt), ((xdrproc_t)(xargs)), (argsp))
178#define svc_freeargs(xprt, xargs, argsp) \
179 (*(xprt)->xp_ops->xp_freeargs)((xprt), ((xdrproc_t)(xargs)), (argsp))
180
181#define SVC_DESTROY(xprt) \
182 (*(xprt)->xp_ops->xp_destroy)(xprt)
183#define svc_destroy(xprt) \
184 (*(xprt)->xp_ops->xp_destroy)(xprt)
185
186#define SVC_CONTROL(xprt, rq, in) \
187 (*(xprt)->xp_ops2->xp_control)((xprt), (rq), (in))
188
189/*
190 * Service registration
191 *
192 * svc_reg(xprt, prog, vers, dispatch, nconf)
193 * const SVCXPRT *xprt;
194 * const rpcprog_t prog;
195 * const rpcvers_t vers;
196 * const void (*dispatch)(...);
197 * const struct netconfig *nconf;
198 */
199
200__BEGIN_DECLS
201extern bool_t svc_reg(SVCXPRT *, const rpcprog_t, const rpcvers_t,
202 void (*)(struct svc_req *, SVCXPRT *),
203 const struct netconfig *);
204__END_DECLS
205
206/*
207 * Service un-registration
208 *
209 * svc_unreg(prog, vers)
210 * const rpcprog_t prog;
211 * const rpcvers_t vers;
212 */
213
214__BEGIN_DECLS
215extern void svc_unreg(const rpcprog_t, const rpcvers_t);
216__END_DECLS
217
218/*
219 * Transport registration.
220 *
221 * xprt_register(xprt)
222 * SVCXPRT *xprt;
223 */
224__BEGIN_DECLS
225extern bool_t xprt_register (SVCXPRT *);
226__END_DECLS
227
228/*
229 * Transport un-register
230 *
231 * xprt_unregister(xprt)
232 * SVCXPRT *xprt;
233 */
234__BEGIN_DECLS
235extern void xprt_unregister (SVCXPRT *);
236__END_DECLS
237
238
239/*
240 * When the service routine is called, it must first check to see if it
241 * knows about the procedure; if not, it should call svcerr_noproc
242 * and return. If so, it should deserialize its arguments via
243 * SVC_GETARGS (defined above). If the deserialization does not work,
244 * svcerr_decode should be called followed by a return. Successful
245 * decoding of the arguments should be followed the execution of the
246 * procedure's code and a call to svc_sendreply.
247 *
248 * Also, if the service refuses to execute the procedure due to too-
249 * weak authentication parameters, svcerr_weakauth should be called.
250 * Note: do not confuse access-control failure with weak authentication!
251 *
252 * NB: In pure implementations of rpc, the caller always waits for a reply
253 * msg. This message is sent when svc_sendreply is called.
254 * Therefore pure service implementations should always call
255 * svc_sendreply even if the function logically returns void; use
256 * xdr.h - xdr_void for the xdr routine. HOWEVER, tcp based rpc allows
257 * for the abuse of pure rpc via batched calling or pipelining. In the
258 * case of a batched call, svc_sendreply should NOT be called since
259 * this would send a return message, which is what batching tries to avoid.
260 * It is the service/protocol writer's responsibility to know which calls are
261 * batched and which are not. Warning: responding to batch calls may
262 * deadlock the caller and server processes!
263 */
264
265__BEGIN_DECLS
266extern bool_t svc_sendreply (SVCXPRT *, xdrproc_t, const char *);
267extern void svcerr_decode (SVCXPRT *);
268extern void svcerr_weakauth (SVCXPRT *);
269extern void svcerr_noproc (SVCXPRT *);
270extern void svcerr_progvers (SVCXPRT *, rpcvers_t, rpcvers_t);
271extern void svcerr_auth (SVCXPRT *, enum auth_stat);
272extern void svcerr_noprog (SVCXPRT *);
273extern void svcerr_systemerr(SVCXPRT *);
274extern int rpc_reg(rpcprog_t, rpcvers_t, rpcproc_t,
275 char *(*)(char *), xdrproc_t, xdrproc_t,
276 char *);
277__END_DECLS
278
279/*
280 * Lowest level dispatching -OR- who owns this process anyway.
281 * Somebody has to wait for incoming requests and then call the correct
282 * service routine. The routine svc_run does infinite waiting; i.e.,
283 * svc_run never returns.
284 * Since another (co-existent) package may wish to selectively wait for
285 * incoming calls or other events outside of the rpc architecture, the
286 * routine svc_getreq is provided. It must be passed readfds, the
287 * "in-place" results of a select system call (see select, section 2).
288 */
289
290/*
291 * Global keeper of rpc service descriptors in use
292 * dynamic; must be inspected before each call to select
293 */
294#ifdef SVC_LEGACY
295extern int svc_maxfd;
296extern fd_set svc_fdset;
297#else
298#define svc_maxfd (*svc_fdset_getmax())
299#define svc_fdset (*svc_fdset_get())
300#define svc_pollfd svc_pollfd_get()
301#define svc_max_pollfd (*svc_fdset_getmax())
302#endif
303
304#define svc_fds svc_fdset.fds_bits[0] /* compatibility */
305
306/*
307 * a small program implemented by the svc_rpc implementation itself;
308 * also see clnt.h for protocol numbers.
309 */
310__BEGIN_DECLS
311extern void rpctest_service(void);
312__END_DECLS
313
314__BEGIN_DECLS
315
316#define SVC_FDSET_MT 1 /* each thread gets own fd_set/pollfd */
317#define SVC_FDSET_POLL 2 /* use poll in svc_run */
318extern void svc_fdset_init(int);
319
320
321extern void svc_fdset_zero(void);
322extern int svc_fdset_isset(int);
323extern int svc_fdset_clr(int);
324extern int svc_fdset_set(int);
325
326extern fd_set *svc_fdset_get(void);
327extern int svc_fdset_getsize(int);
328extern int *svc_fdset_getmax(void);
329extern fd_set *svc_fdset_copy(const fd_set *);
330
331extern struct pollfd *svc_pollfd_get(void);
332extern int svc_pollfd_getsize(int);
333extern int *svc_pollfd_getmax(void);
334extern struct pollfd *svc_pollfd_copy(const struct pollfd *);
335
336extern void svc_getreq (int);
337extern void svc_getreqset (fd_set *);
338extern void svc_getreqset2 (fd_set *, int);
339extern void svc_getreq_common (int);
340struct pollfd;
341extern void svc_getreq_poll(struct pollfd *, int);
342
343extern void svc_run (void);
344extern void svc_exit (void);
345__END_DECLS
346
347/*
348 * Socket to use on svcxxx_create call to get default socket
349 */
350#define RPC_ANYSOCK -1
351#define RPC_ANYFD RPC_ANYSOCK
352
353/*
354 * These are the existing service side transport implementations
355 */
356
357__BEGIN_DECLS
358/*
359 * Transport independent svc_create routine.
360 */
361extern int svc_create(void (*)(struct svc_req *, SVCXPRT *),
362 const rpcprog_t, const rpcvers_t, const char *);
363/*
364 * void (*dispatch)(...); -- dispatch routine
365 * const rpcprog_t prognum; -- program number
366 * const rpcvers_t versnum; -- version number
367 * const char *nettype; -- network type
368 */
369
370
371/*
372 * Generic server creation routine. It takes a netconfig structure
373 * instead of a nettype.
374 */
375
376extern SVCXPRT *svc_tp_create(void (*)(struct svc_req *, SVCXPRT *),
377 const rpcprog_t, const rpcvers_t,
378 const struct netconfig *);
379/*
380 * void (*dispatch)(...); -- dispatch routine
381 * const rpcprog_t prognum; -- program number
382 * const rpcvers_t versnum; -- version number
383 * const struct netconfig *nconf; -- netconfig structure
384 */
385
386
387/*
388 * Generic TLI create routine
389 */
390extern SVCXPRT *svc_tli_create(const int, const struct netconfig *,
391 const struct t_bind *, const unsigned int,
392 const unsigned int);
393/*
394 * const int fd; -- connection end point
395 * const struct netconfig *nconf; -- netconfig structure for network
396 * const struct t_bind *bindaddr; -- local bind address
397 * const unsigned sendsz; -- max sendsize
398 * const unsigned recvsz; -- max recvsize
399 */
400
401/*
402 * Connectionless and connectionful create routines
403 */
404
405extern SVCXPRT *svc_vc_create(const int, const unsigned int,
406 const unsigned int);
407/*
408 * const int fd; -- open connection end point
409 * const unsigned sendsize; -- max send size
410 * const unsigned recvsize; -- max recv size
411 */
412
413extern SVCXPRT *svc_dg_create(const int, const unsigned int,
414 const unsigned int);
415/*
416 * const int fd; -- open connection
417 * const unsigned sendsize; -- max send size
418 * const unsigned recvsize; -- max recv size
419 */
420
421
422/*
423 * the routine takes any *open* connection
424 * descriptor as its first input and is used for open connections.
425 */
426extern SVCXPRT *svc_fd_create(const int, const unsigned int,
427 const unsigned int);
428/*
429 * const int fd; -- open connection end point
430 * const unsigned sendsize; -- max send size
431 * const unsigned recvsize; -- max recv size
432 */
433
434/*
435 * Memory based rpc (for speed check and testing)
436 */
437extern SVCXPRT *svc_raw_create(void);
438
439/*
440 * svc_dg_enable_cache() enables the cache on dg transports.
441 */
442int svc_dg_enablecache(SVCXPRT *, const unsigned int);
443
444__END_DECLS
445
446
447/* for backward compatibility */
448#include <rpc/svc_soc.h>
449
450#endif /* !_RPC_SVC_H_ */