2 * Sun RPC is a product of Sun Microsystems, Inc. and is provided for
3 * unrestricted use provided that this legend is included on all tape
4 * media and as a part of the software program in whole or part. Users
5 * may copy or modify Sun RPC without charge, but are not authorized
6 * to license or distribute it to anyone else except as part of a product or
7 * program developed by the user.
9 * SUN RPC IS PROVIDED AS IS WITH NO WARRANTIES OF ANY KIND INCLUDING THE
10 * WARRANTIES OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR
11 * PURPOSE, OR ARISING FROM A COURSE OF DEALING, USAGE OR TRADE PRACTICE.
13 * Sun RPC is provided with no support and without any obligation on the
14 * part of Sun Microsystems, Inc. to assist in its use, correction,
15 * modification or enhancement.
17 * SUN MICROSYSTEMS, INC. SHALL HAVE NO LIABILITY WITH RESPECT TO THE
18 * INFRINGEMENT OF COPYRIGHTS, TRADE SECRETS OR ANY PATENTS BY SUN RPC
19 * OR ANY PART THEREOF.
21 * In no event will Sun Microsystems, Inc. be liable for any lost revenue
22 * or profits or other special, indirect and consequential damages, even if
23 * Sun has been advised of the possibility of such damages.
25 * Sun Microsystems, Inc.
27 * Mountain View, California 94043
29 * from: @(#)svc.h 1.20 88/02/08 SMI
30 * from: @(#)svc.h 2.2 88/07/29 4.0 RPCSRC
31 * $FreeBSD: src/include/rpc/svc.h,v 1.16 1999/12/29 05:00:43 peter Exp $
35 * svc.h, Server-side remote procedure call interface.
37 * Copyright (C) 1984, Sun Microsystems, Inc.
42 #include <sys/cdefs.h>
45 * This interface must manage two items concerning remote procedure calling:
47 * 1) An arbitrary number of transport connections upon which rpc requests
48 * are received. The two most notable transports are TCP and UDP; they are
49 * created and registered by routines in svc_tcp.c and svc_udp.c, respectively;
50 * they in turn call xprt_register and xprt_unregister.
52 * 2) An arbitrary number of locally registered services. Services are
53 * described by the following four data: program number, version number,
54 * "service dispatch" function, a transport handle, and a boolean that
55 * indicates whether or not the exported program should be registered with a
56 * local binder service; if true the program's number and version and the
57 * port number from the transport handle are registered with the binder.
58 * These data are registered with the rpc svc system via svc_register.
60 * A service's dispatch function is called whenever an rpc request comes in
61 * on a transport. The request's program and version numbers must match
62 * those of the registered service. The dispatch function is passed two
63 * parameters, struct svc_req * and SVCXPRT *, defined below.
75 * Server side transport handle
77 typedef struct __rpc_svcxprt {
79 u_short xp_port; /* associated port number */
81 /* receive incoming requests */
82 bool_t (*xp_recv) __P((struct __rpc_svcxprt *,
84 /* get transport status */
85 enum xprt_stat (*xp_stat) __P((struct __rpc_svcxprt *));
87 bool_t (*xp_getargs) __P((struct __rpc_svcxprt *, xdrproc_t,
90 bool_t (*xp_reply) __P((struct __rpc_svcxprt *,
92 /* free mem allocated for args */
93 bool_t (*xp_freeargs) __P((struct __rpc_svcxprt *, xdrproc_t,
95 /* destroy this struct */
96 void (*xp_destroy) __P((struct __rpc_svcxprt *));
98 int 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 */
106 * Approved way of getting address of caller
108 #define svc_getcaller(x) (&(x)->xp_raddr)
111 * Operations defined on an SVCXPRT handle
114 * struct rpc_msg *msg;
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))
123 #define SVC_STAT(xprt) \
124 (*(xprt)->xp_ops->xp_stat)(xprt)
125 #define svc_stat(xprt) \
126 (*(xprt)->xp_ops->xp_stat)(xprt)
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))
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))
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))
143 #define SVC_DESTROY(xprt) \
144 (*(xprt)->xp_ops->xp_destroy)(xprt)
145 #define svc_destroy(xprt) \
146 (*(xprt)->xp_ops->xp_destroy)(xprt)
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 */
163 * Service registration
165 * svc_register(xprt, prog, vers, dispatch, protocol)
169 * void (*dispatch)();
170 * int protocol; (like TCP or UDP, zero means do not register)
173 extern bool_t svc_register __P((SVCXPRT *, u_long, u_long,
174 void (*) __P((struct svc_req *, SVCXPRT *)), int));
178 * Service un-registration
180 * svc_unregister(prog, vers)
185 extern void svc_unregister __P((u_long, u_long));
189 * Transport registration.
191 * xprt_register(xprt)
195 extern void xprt_register __P((SVCXPRT *));
199 * Transport un-register
201 * xprt_unregister(xprt)
205 extern void xprt_unregister __P((SVCXPRT *));
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.
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!
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!
238 extern bool_t svc_sendreply __P((SVCXPRT *, xdrproc_t, char *));
239 extern void svcerr_decode __P((SVCXPRT *));
240 extern void svcerr_weakauth __P((SVCXPRT *));
241 extern void svcerr_noproc __P((SVCXPRT *));
242 extern void svcerr_progvers __P((SVCXPRT *, u_long, u_long));
243 extern void svcerr_auth __P((SVCXPRT *, enum auth_stat));
244 extern void svcerr_noprog __P((SVCXPRT *));
245 extern void svcerr_systemerr __P((SVCXPRT *));
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-existant) 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).
260 * Global keeper of rpc service descriptors in use
261 * dynamic; must be inspected before each call to select
263 extern int svc_maxfd;
264 extern fd_set svc_fdset;
265 #define svc_fds svc_fdset.fds_bits[0] /* compatibility */
269 * a small program implemented by the svc_rpc implementation itself;
270 * also see clnt.h for protocol numbers.
272 extern void rpctest_service();
276 extern void svc_getreq __P((int));
277 extern void svc_getreqset __P((fd_set *));
278 extern void svc_getreqset2 __P((fd_set *, int)); /* XXX: nonstd, undoc */
279 extern void svc_run __P((void));
283 * Socket to use on svcxxx_create call to get default socket
285 #define RPC_ANYSOCK -1
288 * These are the existing service side transport implementations
292 * Memory based rpc for testing and timing.
295 extern SVCXPRT *svcraw_create __P((void));
303 extern SVCXPRT *svcudp_create __P((int));
304 extern SVCXPRT *svcudp_bufcreate __P((int, u_int, u_int));
312 extern SVCXPRT *svctcp_create __P((int, u_int, u_int));
313 extern SVCXPRT *svcfd_create __P((int, u_int, u_int));
317 * AF_UNIX socket based rpc.
320 extern SVCXPRT *svcunix_create __P((int, u_int, u_int, char *));
321 extern SVCXPRT *svcunixfd_create __P((int, u_int, u_int));
324 #endif /* !_RPC_SVC_H */