1 /* $NetBSD: svc.h,v 1.17 2000/06/02 22:57:56 fvdl Exp $ */
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.
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.
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.
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.
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.
27 * Sun Microsystems, Inc.
29 * Mountain View, California 94043
31 * from: @(#)svc.h 1.35 88/12/17 SMI
32 * from: @(#)svc.h 1.27 94/04/25 SMI
37 * svc.h, Server-side remote procedure call interface.
39 * Copyright (C) 1986-1993 by Sun Microsystems, Inc.
44 #include <sys/cdefs.h>
47 #include <sys/queue.h>
48 #include <sys/_lock.h>
49 #include <sys/_mutex.h>
53 * This interface must manage two items concerning remote procedure calling:
55 * 1) An arbitrary number of transport connections upon which rpc requests
56 * are received. The two most notable transports are TCP and UDP; they are
57 * created and registered by routines in svc_tcp.c and svc_udp.c, respectively;
58 * they in turn call xprt_register and xprt_unregister.
60 * 2) An arbitrary number of locally registered services. Services are
61 * described by the following four data: program number, version number,
62 * "service dispatch" function, a transport handle, and a boolean that
63 * indicates whether or not the exported program should be registered with a
64 * local binder service; if true the program's number and version and the
65 * port number from the transport handle are registered with the binder.
66 * These data are registered with the rpc svc system via svc_register.
68 * A service's dispatch function is called whenever an rpc request comes in
69 * on a transport. The request's program and version numbers must match
70 * those of the registered service. The dispatch function is passed two
71 * parameters, struct svc_req * and SVCXPRT *, defined below.
75 * Service control requests
77 #define SVCGET_VERSQUIET 1
78 #define SVCSET_VERSQUIET 2
79 #define SVCGET_CONNMAXREC 3
80 #define SVCSET_CONNMAXREC 4
83 * Operations for rpc_control().
85 #define RPC_SVC_CONNMAXREC_SET 0 /* set max rec size, enable nonblock */
86 #define RPC_SVC_CONNMAXREC_GET 1
97 /* receive incoming requests */
98 bool_t (*xp_recv)(struct __rpc_svcxprt *, struct rpc_msg *);
99 /* get transport status */
100 enum xprt_stat (*xp_stat)(struct __rpc_svcxprt *);
102 bool_t (*xp_getargs)(struct __rpc_svcxprt *, xdrproc_t, void *);
104 bool_t (*xp_reply)(struct __rpc_svcxprt *, struct rpc_msg *);
105 /* free mem allocated for args */
106 bool_t (*xp_freeargs)(struct __rpc_svcxprt *, xdrproc_t, void *);
107 /* destroy this struct */
108 void (*xp_destroy)(struct __rpc_svcxprt *);
110 /* catch-all function */
111 bool_t (*xp_control)(struct __rpc_svcxprt *, const u_int, void *);
117 /* catch-all function */
118 bool_t (*xp_control)(struct __rpc_svcxprt *, const u_int, void *);
123 struct __rpc_svcpool;
127 * Server side transport handle
129 typedef struct __rpc_svcxprt {
132 struct __rpc_svcpool *xp_pool; /* owning pool (see below) */
133 TAILQ_ENTRY(__rpc_svcxprt) xp_link;
134 TAILQ_ENTRY(__rpc_svcxprt) xp_alink;
135 bool_t xp_registered; /* xprt_register has been called */
136 bool_t xp_active; /* xprt_active has been called */
137 struct socket* xp_socket;
138 const struct xp_ops *xp_ops;
139 char *xp_netid; /* network token */
140 struct netbuf xp_ltaddr; /* local transport address */
141 struct netbuf xp_rtaddr; /* remote transport address */
142 struct opaque_auth xp_verf; /* raw response verifier */
143 uint32_t xp_xid; /* current transaction ID */
144 XDR xp_xdrreq; /* xdr stream for decoding request */
145 XDR xp_xdrrep; /* xdr stream for encoding reply */
146 void *xp_p1; /* private: for use by svc ops */
147 void *xp_p2; /* private: for use by svc ops */
148 void *xp_p3; /* private: for use by svc lib */
149 int xp_type; /* transport type */
152 u_short xp_port; /* associated port number */
153 const struct xp_ops *xp_ops;
154 int xp_addrlen; /* length of remote address */
155 struct sockaddr_in xp_raddr; /* remote addr. (backward ABI compat) */
156 /* XXX - fvdl stick this here for ABI backward compat reasons */
157 const struct xp_ops2 *xp_ops2;
158 char *xp_tp; /* transport provider device name */
159 char *xp_netid; /* network token */
160 struct netbuf xp_ltaddr; /* local transport address */
161 struct netbuf xp_rtaddr; /* remote transport address */
162 struct opaque_auth xp_verf; /* raw response verifier */
163 void *xp_p1; /* private: for use by svc ops */
164 void *xp_p2; /* private: for use by svc ops */
165 void *xp_p3; /* private: for use by svc lib */
166 int xp_type; /* transport type */
174 * Each entry represents a set of procedures (an rpc program).
175 * The dispatch routine takes request structs and runs the
176 * apropriate procedure.
179 TAILQ_ENTRY(svc_callout) sc_link;
183 void (*sc_dispatch)(struct svc_req *, SVCXPRT *);
185 TAILQ_HEAD(svc_callout_list, svc_callout);
188 * In the kernel, we can't use global variables to store lists of
189 * transports etc. since otherwise we could not have two unrelated RPC
190 * services running, each on its own thread. We solve this by
191 * importing a tiny part of a Solaris kernel concept, SVCPOOL.
193 * A service pool contains a set of transports and service callbacks
194 * for a set of related RPC services. The pool handle should be passed
195 * when creating new transports etc. Future work may include extending
196 * this to support something similar to the Solaris multi-threaded RPC
199 TAILQ_HEAD(svcxprt_list, __rpc_svcxprt);
200 typedef struct __rpc_svcpool {
201 struct mtx sp_lock; /* protect the transport lists */
202 struct svcxprt_list sp_xlist; /* all transports in the pool */
203 struct svcxprt_list sp_active; /* transports needing service */
204 struct svc_callout_list sp_callouts; /* (prog,vers)->dispatch list */
205 bool_t sp_exited; /* true if shutting down */
214 uint32_t rq_prog; /* service program number */
215 uint32_t rq_vers; /* service protocol version */
216 uint32_t rq_proc; /* the desired procedure */
217 struct opaque_auth rq_cred; /* raw creds from the wire */
218 void *rq_clntcred; /* read only cooked cred */
219 SVCXPRT *rq_xprt; /* associated transport */
223 * Approved way of getting address of caller
225 #define svc_getrpccaller(x) (&(x)->xp_rtaddr)
228 * Operations defined on an SVCXPRT handle
231 * struct rpc_msg *msg;
235 #define SVC_RECV(xprt, msg) \
236 (*(xprt)->xp_ops->xp_recv)((xprt), (msg))
237 #define svc_recv(xprt, msg) \
238 (*(xprt)->xp_ops->xp_recv)((xprt), (msg))
240 #define SVC_STAT(xprt) \
241 (*(xprt)->xp_ops->xp_stat)(xprt)
242 #define svc_stat(xprt) \
243 (*(xprt)->xp_ops->xp_stat)(xprt)
245 #define SVC_GETARGS(xprt, xargs, argsp) \
246 (*(xprt)->xp_ops->xp_getargs)((xprt), (xargs), (argsp))
247 #define svc_getargs(xprt, xargs, argsp) \
248 (*(xprt)->xp_ops->xp_getargs)((xprt), (xargs), (argsp))
250 #define SVC_REPLY(xprt, msg) \
251 (*(xprt)->xp_ops->xp_reply) ((xprt), (msg))
252 #define svc_reply(xprt, msg) \
253 (*(xprt)->xp_ops->xp_reply) ((xprt), (msg))
255 #define SVC_FREEARGS(xprt, xargs, argsp) \
256 (*(xprt)->xp_ops->xp_freeargs)((xprt), (xargs), (argsp))
257 #define svc_freeargs(xprt, xargs, argsp) \
258 (*(xprt)->xp_ops->xp_freeargs)((xprt), (xargs), (argsp))
260 #define SVC_DESTROY(xprt) \
261 (*(xprt)->xp_ops->xp_destroy)(xprt)
262 #define svc_destroy(xprt) \
263 (*(xprt)->xp_ops->xp_destroy)(xprt)
266 #define SVC_CONTROL(xprt, rq, in) \
267 (*(xprt)->xp_ops->xp_control)((xprt), (rq), (in))
269 #define SVC_CONTROL(xprt, rq, in) \
270 (*(xprt)->xp_ops2->xp_control)((xprt), (rq), (in))
274 * Service registration
276 * svc_reg(xprt, prog, vers, dispatch, nconf)
277 * const SVCXPRT *xprt;
278 * const rpcprog_t prog;
279 * const rpcvers_t vers;
280 * const void (*dispatch)();
281 * const struct netconfig *nconf;
285 extern bool_t svc_reg(SVCXPRT *, const rpcprog_t, const rpcvers_t,
286 void (*)(struct svc_req *, SVCXPRT *),
287 const struct netconfig *);
291 * Service un-registration
293 * svc_unreg(prog, vers)
294 * const rpcprog_t prog;
295 * const rpcvers_t vers;
300 extern void svc_unreg(SVCPOOL *, const rpcprog_t, const rpcvers_t);
302 extern void svc_unreg(const rpcprog_t, const rpcvers_t);
307 * Transport registration.
309 * xprt_register(xprt)
313 extern void xprt_register(SVCXPRT *);
317 * Transport un-register
319 * xprt_unregister(xprt)
323 extern void xprt_unregister(SVCXPRT *);
324 extern void __xprt_unregister_unlocked(SVCXPRT *);
330 * Called when a transport has pending requests.
333 extern void xprt_active(SVCXPRT *);
334 extern void xprt_inactive(SVCXPRT *);
340 * When the service routine is called, it must first check to see if it
341 * knows about the procedure; if not, it should call svcerr_noproc
342 * and return. If so, it should deserialize its arguments via
343 * SVC_GETARGS (defined above). If the deserialization does not work,
344 * svcerr_decode should be called followed by a return. Successful
345 * decoding of the arguments should be followed the execution of the
346 * procedure's code and a call to svc_sendreply.
348 * Also, if the service refuses to execute the procedure due to too-
349 * weak authentication parameters, svcerr_weakauth should be called.
350 * Note: do not confuse access-control failure with weak authentication!
352 * NB: In pure implementations of rpc, the caller always waits for a reply
353 * msg. This message is sent when svc_sendreply is called.
354 * Therefore pure service implementations should always call
355 * svc_sendreply even if the function logically returns void; use
356 * xdr.h - xdr_void for the xdr routine. HOWEVER, tcp based rpc allows
357 * for the abuse of pure rpc via batched calling or pipelining. In the
358 * case of a batched call, svc_sendreply should NOT be called since
359 * this would send a return message, which is what batching tries to avoid.
360 * It is the service/protocol writer's responsibility to know which calls are
361 * batched and which are not. Warning: responding to batch calls may
362 * deadlock the caller and server processes!
366 extern bool_t svc_sendreply(SVCXPRT *, xdrproc_t, void *);
367 extern void svcerr_decode(SVCXPRT *);
368 extern void svcerr_weakauth(SVCXPRT *);
369 extern void svcerr_noproc(SVCXPRT *);
370 extern void svcerr_progvers(SVCXPRT *, rpcvers_t, rpcvers_t);
371 extern void svcerr_auth(SVCXPRT *, enum auth_stat);
372 extern void svcerr_noprog(SVCXPRT *);
373 extern void svcerr_systemerr(SVCXPRT *);
374 extern int rpc_reg(rpcprog_t, rpcvers_t, rpcproc_t,
375 char *(*)(char *), xdrproc_t, xdrproc_t,
380 * Lowest level dispatching -OR- who owns this process anyway.
381 * Somebody has to wait for incoming requests and then call the correct
382 * service routine. The routine svc_run does infinite waiting; i.e.,
383 * svc_run never returns.
384 * Since another (co-existant) package may wish to selectively wait for
385 * incoming calls or other events outside of the rpc architecture, the
386 * routine svc_getreq is provided. It must be passed readfds, the
387 * "in-place" results of a select system call (see select, section 2).
392 * Global keeper of rpc service descriptors in use
393 * dynamic; must be inspected before each call to select
395 extern int svc_maxfd;
397 extern fd_set svc_fdset;
398 #define svc_fds svc_fdset.fds_bits[0] /* compatibility */
401 #endif /* def FD_SETSIZE */
405 * a small program implemented by the svc_rpc implementation itself;
406 * also see clnt.h for protocol numbers.
409 extern void rpctest_service(void);
414 extern void svc_getreq(int);
415 extern void svc_getreqset(fd_set *);
416 extern void svc_getreq_common(int);
418 extern void svc_getreq_poll(struct pollfd *, int);
419 extern void svc_run(void);
420 extern void svc_exit(void);
422 extern void svc_run(SVCPOOL *);
423 extern void svc_exit(SVCPOOL *);
428 * Socket to use on svcxxx_create call to get default socket
430 #define RPC_ANYSOCK -1
431 #define RPC_ANYFD RPC_ANYSOCK
434 * These are the existing service side transport implementations
442 * Create a new service pool.
444 extern SVCPOOL* svcpool_create(void);
447 * Destroy a service pool, including all registered transports.
449 extern void svcpool_destroy(SVCPOOL *pool);
452 * Transport independent svc_create routine.
454 extern int svc_create(SVCPOOL *, void (*)(struct svc_req *, SVCXPRT *),
455 const rpcprog_t, const rpcvers_t, const char *);
457 * void (*dispatch)(); -- dispatch routine
458 * const rpcprog_t prognum; -- program number
459 * const rpcvers_t versnum; -- version number
460 * const char *nettype; -- network type
465 * Generic server creation routine. It takes a netconfig structure
466 * instead of a nettype.
469 extern SVCXPRT *svc_tp_create(SVCPOOL *, void (*)(struct svc_req *, SVCXPRT *),
470 const rpcprog_t, const rpcvers_t, const char *uaddr,
471 const struct netconfig *);
473 * void (*dispatch)(); -- dispatch routine
474 * const rpcprog_t prognum; -- program number
475 * const rpcvers_t versnum; -- version number
476 * const char *uaddr; -- universal address of service
477 * const struct netconfig *nconf; -- netconfig structure
480 extern SVCXPRT *svc_dg_create(SVCPOOL *, struct socket *,
481 const size_t, const size_t);
483 * struct socket *; -- open connection
484 * const size_t sendsize; -- max send size
485 * const size_t recvsize; -- max recv size
488 extern SVCXPRT *svc_vc_create(SVCPOOL *, struct socket *,
489 const size_t, const size_t);
491 * struct socket *; -- open connection
492 * const size_t sendsize; -- max send size
493 * const size_t recvsize; -- max recv size
497 * Generic TLI create routine
499 extern SVCXPRT *svc_tli_create(SVCPOOL *, struct socket *,
500 const struct netconfig *, const struct t_bind *, const size_t, const size_t);
502 * struct socket * so; -- connection end point
503 * const struct netconfig *nconf; -- netconfig structure for network
504 * const struct t_bind *bindaddr; -- local bind address
505 * const size_t sendsz; -- max sendsize
506 * const size_t recvsz; -- max recvsize
512 * Transport independent svc_create routine.
514 extern int svc_create(void (*)(struct svc_req *, SVCXPRT *),
515 const rpcprog_t, const rpcvers_t, const char *);
517 * void (*dispatch)(); -- dispatch routine
518 * const rpcprog_t prognum; -- program number
519 * const rpcvers_t versnum; -- version number
520 * const char *nettype; -- network type
525 * Generic server creation routine. It takes a netconfig structure
526 * instead of a nettype.
529 extern SVCXPRT *svc_tp_create(void (*)(struct svc_req *, SVCXPRT *),
530 const rpcprog_t, const rpcvers_t,
531 const struct netconfig *);
533 * void (*dispatch)(); -- dispatch routine
534 * const rpcprog_t prognum; -- program number
535 * const rpcvers_t versnum; -- version number
536 * const struct netconfig *nconf; -- netconfig structure
540 * Generic TLI create routine
542 extern SVCXPRT *svc_tli_create(const int, const struct netconfig *,
543 const struct t_bind *, const u_int,
546 * const int fd; -- connection end point
547 * const struct netconfig *nconf; -- netconfig structure for network
548 * const struct t_bind *bindaddr; -- local bind address
549 * const u_int sendsz; -- max sendsize
550 * const u_int recvsz; -- max recvsize
554 * Connectionless and connectionful create routines
557 extern SVCXPRT *svc_vc_create(const int, const u_int, const u_int);
559 * const int fd; -- open connection end point
560 * const u_int sendsize; -- max send size
561 * const u_int recvsize; -- max recv size
565 * Added for compatibility to old rpc 4.0. Obsoleted by svc_vc_create().
567 extern SVCXPRT *svcunix_create(int, u_int, u_int, char *);
569 extern SVCXPRT *svc_dg_create(const int, const u_int, const u_int);
571 * const int fd; -- open connection
572 * const u_int sendsize; -- max send size
573 * const u_int recvsize; -- max recv size
578 * the routine takes any *open* connection
579 * descriptor as its first input and is used for open connections.
581 extern SVCXPRT *svc_fd_create(const int, const u_int, const u_int);
583 * const int fd; -- open connection end point
584 * const u_int sendsize; -- max send size
585 * const u_int recvsize; -- max recv size
589 * Added for compatibility to old rpc 4.0. Obsoleted by svc_fd_create().
591 extern SVCXPRT *svcunixfd_create(int, u_int, u_int);
594 * Memory based rpc (for speed check and testing)
596 extern SVCXPRT *svc_raw_create(void);
599 * svc_dg_enable_cache() enables the cache on dg transports.
601 int svc_dg_enablecache(SVCXPRT *, const u_int);
603 int __rpc_get_local_uid(SVCXPRT *_transp, uid_t *_uid);
605 #endif /* !_KERNEL */
610 /* for backward compatibility */
611 #include <rpc/svc_soc.h>
614 #endif /* !_RPC_SVC_H */