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