1 /* 2 * CDDL HEADER START 3 * 4 * The contents of this file are subject to the terms of the 5 * Common Development and Distribution License, Version 1.0 only 6 * (the "License"). You may not use this file except in compliance 7 * with the License. 8 * 9 * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 10 * or http://www.opensolaris.org/os/licensing. 11 * See the License for the specific language governing permissions 12 * and limitations under the License. 13 * 14 * When distributing Covered Code, include this CDDL HEADER in each 15 * file and include the License file at usr/src/OPENSOLARIS.LICENSE. 16 * If applicable, add the following below this CDDL HEADER, with the 17 * fields enclosed by brackets "[]" replaced with your own identifying 18 * information: Portions Copyright [yyyy] [name of copyright owner] 19 * 20 * CDDL HEADER END 21 */ 22 #pragma ident "%Z%%M% %I% %E% SMI" 23 24 /* 25 * svc.h, Server-side remote procedure call interface. 26 * 27 * Copyright (C) 1984, Sun Microsystems, Inc. 28 */ 29 30 #ifndef _rpc_svc_h 31 #define _rpc_svc_h 32 33 /* 34 * This interface must manage two items concerning remote procedure calling: 35 * 36 * 1) An arbitrary number of transport connections upon which rpc requests 37 * are received. The two most notable transports are TCP and UDP; they are 38 * created and registered by routines in svc_tcp.c and svc_udp.c, respectively; 39 * they in turn call xprt_register and xprt_unregister. 40 * 41 * 2) An arbitrary number of locally registered services. Services are 42 * described by the following four data: program number, version number, 43 * "service dispatch" function, a transport handle, and a boolean that 44 * indicates whether or not the exported program should be registered with a 45 * local binder service; if true the program's number and version and the 46 * port number from the transport handle are registered with the binder. 47 * These data are registered with the rpc svc system via svc_register. 48 * 49 * A service's dispatch function is called whenever an rpc request comes in 50 * on a transport. The request's program and version numbers must match 51 * those of the registered service. The dispatch function is passed two 52 * parameters, struct svc_req * and SVCXPRT *, defined below. 53 */ 54 55 enum xprt_stat { 56 XPRT_DIED, 57 XPRT_MOREREQS, 58 XPRT_IDLE 59 }; 60 61 /* 62 * Server side transport handle 63 */ 64 typedef struct { 65 #ifdef KERNEL 66 struct socket *xp_sock; 67 #else 68 int xp_sock; 69 #endif 70 u_short xp_port; /* associated port number */ 71 struct xp_ops { 72 bool_t (*xp_recv)(); /* receive incomming requests */ 73 enum xprt_stat (*xp_stat)(); /* get transport status */ 74 bool_t (*xp_getargs)(); /* get arguments */ 75 bool_t (*xp_reply)(); /* send reply */ 76 bool_t (*xp_freeargs)(); /* free mem allocated for args */ 77 void (*xp_destroy)(); /* destroy this struct */ 78 } *xp_ops; 79 int xp_addrlen; /* length of remote address */ 80 struct sockaddr_in xp_raddr; /* remote address */ 81 struct opaque_auth xp_verf; /* raw response verifier */ 82 caddr_t xp_p1; /* private: for use by svc ops */ 83 caddr_t xp_p2; /* private: for use by svc ops */ 84 caddr_t xp_p3; /* private: for use by svc lib */ 85 } SVCXPRT; 86 87 /* 88 * Approved way of getting address of caller 89 */ 90 #define svc_getcaller(x) (&(x)->xp_raddr) 91 92 /* 93 * Operations defined on an SVCXPRT handle 94 * 95 * SVCXPRT *xprt; 96 * struct rpc_msg *msg; 97 * xdrproc_t xargs; 98 * caddr_t argsp; 99 */ 100 #define SVC_RECV(xprt, msg) \ 101 (*(xprt)->xp_ops->xp_recv)((xprt), (msg)) 102 #define svc_recv(xprt, msg) \ 103 (*(xprt)->xp_ops->xp_recv)((xprt), (msg)) 104 105 #define SVC_STAT(xprt) \ 106 (*(xprt)->xp_ops->xp_stat)(xprt) 107 #define svc_stat(xprt) \ 108 (*(xprt)->xp_ops->xp_stat)(xprt) 109 110 #define SVC_GETARGS(xprt, xargs, argsp) \ 111 (*(xprt)->xp_ops->xp_getargs)((xprt), (xargs), (argsp)) 112 #define svc_getargs(xprt, xargs, argsp) \ 113 (*(xprt)->xp_ops->xp_getargs)((xprt), (xargs), (argsp)) 114 115 #define SVC_REPLY(xprt, msg) \ 116 (*(xprt)->xp_ops->xp_reply) ((xprt), (msg)) 117 #define svc_reply(xprt, msg) \ 118 (*(xprt)->xp_ops->xp_reply) ((xprt), (msg)) 119 120 #define SVC_FREEARGS(xprt, xargs, argsp) \ 121 (*(xprt)->xp_ops->xp_freeargs)((xprt), (xargs), (argsp)) 122 #define svc_freeargs(xprt, xargs, argsp) \ 123 (*(xprt)->xp_ops->xp_freeargs)((xprt), (xargs), (argsp)) 124 125 #define SVC_DESTROY(xprt) \ 126 (*(xprt)->xp_ops->xp_destroy)(xprt) 127 #define svc_destroy(xprt) \ 128 (*(xprt)->xp_ops->xp_destroy)(xprt) 129 130 131 /* 132 * Service request 133 */ 134 struct svc_req { 135 u_long rq_prog; /* service program number */ 136 u_long rq_vers; /* service protocol version */ 137 u_long rq_proc; /* the desired procedure */ 138 struct opaque_auth rq_cred; /* raw creds from the wire */ 139 caddr_t rq_clntcred; /* read only cooked cred */ 140 SVCXPRT *rq_xprt; /* associated transport */ 141 }; 142 143 144 /* 145 * Service registration 146 * 147 * svc_register(xprt, prog, vers, dispatch, protocol) 148 * SVCXPRT *xprt; 149 * u_long prog; 150 * u_long vers; 151 * void (*dispatch)(); 152 * int protocol; like TCP or UDP, zero means do not register 153 */ 154 extern bool_t svc_register(); 155 156 /* 157 * Service un-registration 158 * 159 * svc_unregister(prog, vers) 160 * u_long prog; 161 * u_long vers; 162 */ 163 extern void svc_unregister(); 164 165 /* 166 * Transport registration. 167 * 168 * xprt_register(xprt) 169 * SVCXPRT *xprt; 170 */ 171 extern void xprt_register(); 172 173 #ifndef KERNEL 174 /* 175 * Transport un-register 176 * 177 * xprt_unregister(xprt) 178 * SVCXPRT *xprt; 179 */ 180 extern void xprt_unregister(); 181 182 183 #endif !KERNEL 184 185 186 /* 187 * When the service routine is called, it must first check to see if it 188 * knows about the procedure; if not, it should call svcerr_noproc 189 * and return. If so, it should deserialize its arguments via 190 * SVC_GETARGS (defined above). If the deserialization does not work, 191 * svcerr_decode should be called followed by a return. Successful 192 * decoding of the arguments should be followed the execution of the 193 * procedure's code and a call to svc_sendreply. 194 * 195 * Also, if the service refuses to execute the procedure due to too- 196 * weak authentication parameters, svcerr_weakauth should be called. 197 * Note: do not confuse access-control failure with weak authentication! 198 * 199 * NB: In pure implementations of rpc, the caller always waits for a reply 200 * msg. This message is sent when svc_sendreply is called. 201 * Therefore pure service implementations should always call 202 * svc_sendreply even if the function logically returns void; use 203 * xdr.h - xdr_void for the xdr routine. HOWEVER, tcp based rpc allows 204 * for the abuse of pure rpc via batched calling or pipelining. In the 205 * case of a batched call, svc_sendreply should NOT be called since 206 * this would send a return message, which is what batching tries to avoid. 207 * It is the service/protocol writer's responsibility to know which calls are 208 * batched and which are not. Warning: responding to batch calls may 209 * deadlock the caller and server processes! 210 */ 211 212 extern bool_t svc_sendreply(); 213 extern void svcerr_decode(); 214 extern void svcerr_weakauth(); 215 extern void svcerr_noproc(); 216 extern void svcerr_progvers(); 217 extern void svcerr_auth(); 218 extern void svcerr_noprog(); 219 #ifndef KERNEL 220 extern void svcerr_systemerr(); 221 #endif 222 223 /* 224 * Lowest level dispatching -OR- who owns this process anyway. 225 * Somebody has to wait for incoming requests and then call the correct 226 * service routine. The routine svc_run does infinite waiting; i.e., 227 * svc_run never returns. 228 * Since another (co-existant) package may wish to selectively wait for 229 * incoming calls or other events outside of the rpc architecture, the 230 * routine svc_getreq is provided. It must be passed readfds, the 231 * "in-place" results of a select system call (see select, section 2). 232 */ 233 234 #ifndef KERNEL 235 /* 236 * Global keeper of rpc service descriptors in use 237 * dynamic; must be inspected before each call to select 238 */ 239 extern fd_set svc_fdset; 240 #define svc_fds svc_fdset.fds_bits[0] /* compatibility */ 241 242 /* 243 * a small program implemented by the svc_rpc implementation itself; 244 * also see clnt.h for protocol numbers. 245 */ 246 extern void rpctest_service(); 247 #endif !KERNEL 248 249 extern void svc_getreq(); 250 #ifndef KERNEL 251 extern void svc_getreqset(); /* takes fdset instead of int */ 252 #endif 253 extern void svc_run(); /* never returns */ 254 255 /* 256 * Socket to use on svcxxx_create call to get default socket 257 */ 258 #define RPC_ANYSOCK -1 259 260 /* 261 * These are the existing service side transport implementations 262 */ 263 264 #ifndef KERNEL 265 /* 266 * Memory based rpc for testing and timing. 267 */ 268 extern SVCXPRT *svcraw_create(); 269 270 /* 271 * Udp based rpc. 272 */ 273 extern SVCXPRT *svcudp_create(); 274 extern SVCXPRT *svcudp_bufcreate(); 275 276 /* 277 * Tcp based rpc. 278 */ 279 extern SVCXPRT *svctcp_create(); 280 281 /* 282 * Like svtcp_create(), except the routine takes any *open* UNIX file 283 * descriptor as its first input. 284 */ 285 SVCXPRT *svcfd_create(); 286 #else 287 288 /* 289 * Kernel udp based rpc. 290 */ 291 extern SVCXPRT *svckudp_create(); 292 #endif !KERNEL 293 294 295 #endif /*!_rpc_svc_h*/ 296