xref: /freebsd/include/rpc/svc.h (revision 370c6ad8ce0240dea404b09164528ec7142eb94b)
1 /*	$NetBSD: svc.h,v 1.17 2000/06/02 22:57:56 fvdl 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, MERCHANTABILITY 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  *	from: @(#)svc.h      1.27    94/04/25 SMI
33  * $FreeBSD$
34  */
35 
36 /*
37  * svc.h, Server-side remote procedure call interface.
38  *
39  * Copyright (C) 1986-1993 by Sun Microsystems, Inc.
40  */
41 
42 #ifndef _RPC_SVC_H
43 #define _RPC_SVC_H
44 #include <sys/cdefs.h>
45 
46 /*
47  * This interface must manage two items concerning remote procedure calling:
48  *
49  * 1) An arbitrary number of transport connections upon which rpc requests
50  * are received.  The two most notable transports are TCP and UDP;  they are
51  * created and registered by routines in svc_tcp.c and svc_udp.c, respectively;
52  * they in turn call xprt_register and xprt_unregister.
53  *
54  * 2) An arbitrary number of locally registered services.  Services are
55  * described by the following four data: program number, version number,
56  * "service dispatch" function, a transport handle, and a boolean that
57  * indicates whether or not the exported program should be registered with a
58  * local binder service;  if true the program's number and version and the
59  * port number from the transport handle are registered with the binder.
60  * These data are registered with the rpc svc system via svc_register.
61  *
62  * A service's dispatch function is called whenever an rpc request comes in
63  * on a transport.  The request's program and version numbers must match
64  * those of the registered service.  The dispatch function is passed two
65  * parameters, struct svc_req * and SVCXPRT *, defined below.
66  */
67 
68 #ifdef	__cplusplus
69 extern "C" {
70 #endif
71 
72 /*
73  *      Service control requests
74  */
75 #define SVCGET_VERSQUIET	1
76 #define SVCSET_VERSQUIET	2
77 #define SVCGET_CONNMAXREC	3
78 #define SVCSET_CONNMAXREC	4
79 
80 /*
81  * Operations for rpc_control().
82  */
83 #define RPC_SVC_CONNMAXREC_SET  0	/* set max rec size, enable nonblock */
84 #define RPC_SVC_CONNMAXREC_GET  1
85 
86 enum xprt_stat {
87 	XPRT_DIED,
88 	XPRT_MOREREQS,
89 	XPRT_IDLE
90 };
91 
92 /*
93  * Server side transport handle
94  */
95 typedef struct __rpc_svcxprt {
96 	int		xp_fd;
97 	u_short		xp_port;	 /* associated port number */
98 	const struct xp_ops {
99 	    /* receive incoming requests */
100 	    bool_t	(*xp_recv)(struct __rpc_svcxprt *, struct rpc_msg *);
101 	    /* get transport status */
102 	    enum xprt_stat (*xp_stat)(struct __rpc_svcxprt *);
103 	    /* get arguments */
104 	    bool_t	(*xp_getargs)(struct __rpc_svcxprt *, xdrproc_t,
105 				void *);
106 	    /* send reply */
107 	    bool_t	(*xp_reply)(struct __rpc_svcxprt *, struct rpc_msg *);
108 	    /* free mem allocated for args */
109 	    bool_t	(*xp_freeargs)(struct __rpc_svcxprt *, xdrproc_t,
110 				void *);
111 	    /* destroy this struct */
112 	    void	(*xp_destroy)(struct __rpc_svcxprt *);
113 	} *xp_ops;
114 	int		xp_addrlen;	 /* length of remote address */
115 	struct sockaddr_in xp_raddr;	 /* remote addr. (backward ABI compat) */
116 	/* XXX - fvdl stick this here for ABI backward compat reasons */
117 	const struct xp_ops2 {
118 		/* catch-all function */
119 		bool_t  (*xp_control)(struct __rpc_svcxprt *, const u_int,
120 				void *);
121 	} *xp_ops2;
122 	char		*xp_tp;		 /* transport provider device name */
123 	char		*xp_netid;	 /* network token */
124 	struct netbuf	xp_ltaddr;	 /* local transport address */
125 	struct netbuf	xp_rtaddr;	 /* remote transport address */
126 	struct opaque_auth xp_verf;	 /* raw response verifier */
127 	void		*xp_p1;		 /* private: for use by svc ops */
128 	void		*xp_p2;		 /* private: for use by svc ops */
129 	void		*xp_p3;		 /* private: for use by svc lib */
130 	int		xp_type;	 /* transport type */
131 } SVCXPRT;
132 
133 /*
134  * Interface to server-side authentication flavors.
135  */
136 typedef struct __rpc_svcauth {
137 	struct svc_auth_ops {
138 		int   (*svc_ah_wrap)(struct __rpc_svcauth *, XDR *,
139 		    xdrproc_t, caddr_t);
140 		int   (*svc_ah_unwrap)(struct __rpc_svcauth *, XDR *,
141 		    xdrproc_t, caddr_t);
142 	} *svc_ah_ops;
143 	void *svc_ah_private;
144 } SVCAUTH;
145 
146 /*
147  * Server transport extensions (accessed via xp_p3).
148  */
149 typedef struct __rpc_svcxprt_ext {
150 	int		xp_flags;	/* versquiet */
151 	SVCAUTH		xp_auth;	/* interface to auth methods */
152 } SVCXPRT_EXT;
153 
154 /*
155  * Service request
156  */
157 struct svc_req {
158 	u_int32_t	rq_prog;	/* service program number */
159 	u_int32_t	rq_vers;	/* service protocol version */
160 	u_int32_t	rq_proc;	/* the desired procedure */
161 	struct opaque_auth rq_cred;	/* raw creds from the wire */
162 	void		*rq_clntcred;	/* read only cooked cred */
163 	SVCXPRT		*rq_xprt;	/* associated transport */
164 };
165 
166 /*
167  *  Approved way of getting address of caller
168  */
169 #define svc_getrpccaller(x) (&(x)->xp_rtaddr)
170 
171 /*
172  * Operations defined on an SVCXPRT handle
173  *
174  * SVCXPRT		*xprt;
175  * struct rpc_msg	*msg;
176  * xdrproc_t		 xargs;
177  * void *		 argsp;
178  */
179 #define SVC_RECV(xprt, msg)				\
180 	(*(xprt)->xp_ops->xp_recv)((xprt), (msg))
181 #define svc_recv(xprt, msg)				\
182 	(*(xprt)->xp_ops->xp_recv)((xprt), (msg))
183 
184 #define SVC_STAT(xprt)					\
185 	(*(xprt)->xp_ops->xp_stat)(xprt)
186 #define svc_stat(xprt)					\
187 	(*(xprt)->xp_ops->xp_stat)(xprt)
188 
189 #define SVC_GETARGS(xprt, xargs, argsp)			\
190 	(*(xprt)->xp_ops->xp_getargs)((xprt), (xargs), (argsp))
191 #define svc_getargs(xprt, xargs, argsp)			\
192 	(*(xprt)->xp_ops->xp_getargs)((xprt), (xargs), (argsp))
193 
194 #define SVC_REPLY(xprt, msg)				\
195 	(*(xprt)->xp_ops->xp_reply) ((xprt), (msg))
196 #define svc_reply(xprt, msg)				\
197 	(*(xprt)->xp_ops->xp_reply) ((xprt), (msg))
198 
199 #define SVC_FREEARGS(xprt, xargs, argsp)		\
200 	(*(xprt)->xp_ops->xp_freeargs)((xprt), (xargs), (argsp))
201 #define svc_freeargs(xprt, xargs, argsp)		\
202 	(*(xprt)->xp_ops->xp_freeargs)((xprt), (xargs), (argsp))
203 
204 #define SVC_DESTROY(xprt)				\
205 	(*(xprt)->xp_ops->xp_destroy)(xprt)
206 #define svc_destroy(xprt)				\
207 	(*(xprt)->xp_ops->xp_destroy)(xprt)
208 
209 #define SVC_CONTROL(xprt, rq, in)			\
210 	(*(xprt)->xp_ops2->xp_control)((xprt), (rq), (in))
211 
212 #define SVC_EXT(xprt)					\
213 	((SVCXPRT_EXT *) xprt->xp_p3)
214 
215 #define SVC_AUTH(xprt)					\
216 	(SVC_EXT(xprt)->xp_auth)
217 
218 /*
219  * Operations defined on an SVCAUTH handle
220  */
221 #define SVCAUTH_WRAP(auth, xdrs, xfunc, xwhere)		\
222 	((auth)->svc_ah_ops->svc_ah_wrap(auth, xdrs, xfunc, xwhere))
223 #define SVCAUTH_UNWRAP(auth, xdrs, xfunc, xwhere)	\
224 	((auth)->svc_ah_ops->svc_ah_unwrap(auth, xdrs, xfunc, xwhere))
225 
226 /*
227  * Service registration
228  *
229  * svc_reg(xprt, prog, vers, dispatch, nconf)
230  *	const SVCXPRT *xprt;
231  *	const rpcprog_t prog;
232  *	const rpcvers_t vers;
233  *	const void (*dispatch)(struct svc_req *, SVCXPRT *);
234  *	const struct netconfig *nconf;
235  */
236 
237 __BEGIN_DECLS
238 extern bool_t	svc_reg(SVCXPRT *, const rpcprog_t, const rpcvers_t,
239 			void (*)(struct svc_req *, SVCXPRT *),
240 			const struct netconfig *);
241 __END_DECLS
242 
243 /*
244  * Service un-registration
245  *
246  * svc_unreg(prog, vers)
247  *	const rpcprog_t prog;
248  *	const rpcvers_t vers;
249  */
250 
251 __BEGIN_DECLS
252 extern void	svc_unreg(const rpcprog_t, const rpcvers_t);
253 __END_DECLS
254 
255 /*
256  * Transport registration.
257  *
258  * xprt_register(xprt)
259  *	SVCXPRT *xprt;
260  */
261 __BEGIN_DECLS
262 extern void	xprt_register(SVCXPRT *);
263 __END_DECLS
264 
265 /*
266  * Transport un-register
267  *
268  * xprt_unregister(xprt)
269  *	SVCXPRT *xprt;
270  */
271 __BEGIN_DECLS
272 extern void	xprt_unregister(SVCXPRT *);
273 __END_DECLS
274 
275 
276 /*
277  * When the service routine is called, it must first check to see if it
278  * knows about the procedure;  if not, it should call svcerr_noproc
279  * and return.  If so, it should deserialize its arguments via
280  * SVC_GETARGS (defined above).  If the deserialization does not work,
281  * svcerr_decode should be called followed by a return.  Successful
282  * decoding of the arguments should be followed the execution of the
283  * procedure's code and a call to svc_sendreply.
284  *
285  * Also, if the service refuses to execute the procedure due to too-
286  * weak authentication parameters, svcerr_weakauth should be called.
287  * Note: do not confuse access-control failure with weak authentication!
288  *
289  * NB: In pure implementations of rpc, the caller always waits for a reply
290  * msg.  This message is sent when svc_sendreply is called.
291  * Therefore pure service implementations should always call
292  * svc_sendreply even if the function logically returns void;  use
293  * xdr.h - xdr_void for the xdr routine.  HOWEVER, tcp based rpc allows
294  * for the abuse of pure rpc via batched calling or pipelining.  In the
295  * case of a batched call, svc_sendreply should NOT be called since
296  * this would send a return message, which is what batching tries to avoid.
297  * It is the service/protocol writer's responsibility to know which calls are
298  * batched and which are not.  Warning: responding to batch calls may
299  * deadlock the caller and server processes!
300  */
301 
302 __BEGIN_DECLS
303 extern bool_t	svc_sendreply(SVCXPRT *, xdrproc_t, void *);
304 extern void	svcerr_decode(SVCXPRT *);
305 extern void	svcerr_weakauth(SVCXPRT *);
306 extern void	svcerr_noproc(SVCXPRT *);
307 extern void	svcerr_progvers(SVCXPRT *, rpcvers_t, rpcvers_t);
308 extern void	svcerr_auth(SVCXPRT *, enum auth_stat);
309 extern void	svcerr_noprog(SVCXPRT *);
310 extern void	svcerr_systemerr(SVCXPRT *);
311 extern int	rpc_reg(rpcprog_t, rpcvers_t, rpcproc_t,
312 			char *(*)(char *), xdrproc_t, xdrproc_t,
313 			char *);
314 __END_DECLS
315 
316 /*
317  * Lowest level dispatching -OR- who owns this process anyway.
318  * Somebody has to wait for incoming requests and then call the correct
319  * service routine.  The routine svc_run does infinite waiting; i.e.,
320  * svc_run never returns.
321  * Since another (co-existent) package may wish to selectively wait for
322  * incoming calls or other events outside of the rpc architecture, the
323  * routine svc_getreq is provided.  It must be passed readfds, the
324  * "in-place" results of a select system call (see select, section 2).
325  */
326 
327 /*
328  * Global keeper of rpc service descriptors in use
329  * dynamic; must be inspected before each call to select
330  */
331 extern int svc_maxfd;
332 #ifdef FD_SETSIZE
333 extern fd_set svc_fdset;
334 #define svc_fds svc_fdset.fds_bits[0]	/* compatibility */
335 #else
336 extern int svc_fds;
337 #endif /* def FD_SETSIZE */
338 
339 /*
340  * A set of null auth methods used by any authentication protocols
341  * that don't need to inspect or modify the message body.
342  */
343 extern SVCAUTH _svc_auth_null;
344 
345 /*
346  * a small program implemented by the svc_rpc implementation itself;
347  * also see clnt.h for protocol numbers.
348  */
349 __BEGIN_DECLS
350 extern void rpctest_service(void);
351 __END_DECLS
352 
353 __BEGIN_DECLS
354 extern SVCXPRT *svc_xprt_alloc(void);
355 extern void	svc_xprt_free(SVCXPRT *);
356 extern void	svc_getreq(int);
357 extern void	svc_getreqset(fd_set *);
358 extern void	svc_getreq_common(int);
359 struct pollfd;
360 extern void	svc_getreq_poll(struct pollfd *, int);
361 
362 extern void	svc_run(void);
363 extern void	svc_exit(void);
364 __END_DECLS
365 
366 /*
367  * Socket to use on svcxxx_create call to get default socket
368  */
369 #define	RPC_ANYSOCK	-1
370 #define RPC_ANYFD	RPC_ANYSOCK
371 
372 /*
373  * These are the existing service side transport implementations
374  */
375 
376 __BEGIN_DECLS
377 /*
378  * Transport independent svc_create routine.
379  */
380 extern int svc_create(void (*)(struct svc_req *, SVCXPRT *),
381 			   const rpcprog_t, const rpcvers_t, const char *);
382 /*
383  *      void (*dispatch)(struct svc_req *, SVCXPRT *);
384  *      const rpcprog_t prognum;        -- program number
385  *      const rpcvers_t versnum;        -- version number
386  *      const char *nettype;            -- network type
387  */
388 
389 
390 /*
391  * Generic server creation routine. It takes a netconfig structure
392  * instead of a nettype.
393  */
394 
395 extern SVCXPRT *svc_tp_create(void (*)(struct svc_req *, SVCXPRT *),
396 				   const rpcprog_t, const rpcvers_t,
397 				   const struct netconfig *);
398         /*
399          * void (*dispatch)(struct svc_req *, SVCXPRT *);
400          * const rpcprog_t prognum;       -- program number
401          * const rpcvers_t versnum;       -- version number
402          * const struct netconfig *nconf; -- netconfig structure
403          */
404 
405 
406 /*
407  * Generic TLI create routine
408  */
409 extern SVCXPRT *svc_tli_create(const int, const struct netconfig *,
410 			       const struct t_bind *, const u_int,
411 			       const u_int);
412 /*
413  *      const int fd;                   -- connection end point
414  *      const struct netconfig *nconf;  -- netconfig structure for network
415  *      const struct t_bind *bindaddr;  -- local bind address
416  *      const u_int sendsz;             -- max sendsize
417  *      const u_int recvsz;             -- max recvsize
418  */
419 
420 /*
421  * Connectionless and connectionful create routines
422  */
423 
424 extern SVCXPRT *svc_vc_create(const int, const u_int, const u_int);
425 /*
426  *      const int fd;                           -- open connection end point
427  *      const u_int sendsize;                   -- max send size
428  *      const u_int recvsize;                   -- max recv size
429  */
430 
431 /*
432  * Added for compatibility to old rpc 4.0. Obsoleted by svc_vc_create().
433  */
434 extern SVCXPRT *svcunix_create(int, u_int, u_int, char *);
435 
436 extern SVCXPRT *svc_dg_create(const int, const u_int, const u_int);
437         /*
438          * const int fd;                                -- open connection
439          * const u_int sendsize;                        -- max send size
440          * const u_int recvsize;                        -- max recv size
441          */
442 
443 
444 /*
445  * the routine takes any *open* connection
446  * descriptor as its first input and is used for open connections.
447  */
448 extern SVCXPRT *svc_fd_create(const int, const u_int, const u_int);
449 /*
450  *      const int fd;                           -- open connection end point
451  *      const u_int sendsize;                   -- max send size
452  *      const u_int recvsize;                   -- max recv size
453  */
454 
455 /*
456  * Added for compatibility to old rpc 4.0. Obsoleted by svc_fd_create().
457  */
458 extern SVCXPRT *svcunixfd_create(int, u_int, u_int);
459 
460 /*
461  * Memory based rpc (for speed check and testing)
462  */
463 extern SVCXPRT *svc_raw_create(void);
464 
465 /*
466  * svc_dg_enable_cache() enables the cache on dg transports.
467  */
468 int svc_dg_enablecache(SVCXPRT *, const u_int);
469 
470 int __rpc_get_local_uid(SVCXPRT *_transp, uid_t *_uid);
471 
472 __END_DECLS
473 
474 #ifdef	__cplusplus
475 }
476 #endif
477 
478 /* for backward compatibility */
479 #include <rpc/svc_soc.h>
480 
481 #endif /* !_RPC_SVC_H */
482