svc.h revision 722:636b850d4ee9
1169695Skan/* 2169695Skan * CDDL HEADER START 3169695Skan * 4169695Skan * The contents of this file are subject to the terms of the 5169695Skan * Common Development and Distribution License, Version 1.0 only 6169695Skan * (the "License"). You may not use this file except in compliance 7169695Skan * with the License. 8169695Skan * 9169695Skan * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 10169695Skan * or http://www.opensolaris.org/os/licensing. 11169695Skan * See the License for the specific language governing permissions 12169695Skan * and limitations under the License. 13169695Skan * 14169695Skan * When distributing Covered Code, include this CDDL HEADER in each 15169695Skan * file and include the License file at usr/src/OPENSOLARIS.LICENSE. 16169695Skan * If applicable, add the following below this CDDL HEADER, with the 17169695Skan * fields enclosed by brackets "[]" replaced with your own identifying 18169695Skan * information: Portions Copyright [yyyy] [name of copyright owner] 19169695Skan * 20169695Skan * CDDL HEADER END 21169695Skan */ 22169695Skan/* 23169695Skan * Copyright 1984 Sun Microsystems, Inc. All rights reserved. 24169695Skan * Use is subject to license terms. 25169695Skan */ 26169695Skan 27169695Skan#ifndef _rpc_svc_h 28169695Skan#define _rpc_svc_h 29169695Skan 30169695Skan#pragma ident "%Z%%M% %I% %E% SMI" 31169695Skan 32169695Skan/* 33169695Skan * svc.h, Server-side remote procedure call interface. 34169695Skan */ 35169695Skan 36169695Skan/* 37169695Skan * This interface must manage two items concerning remote procedure calling: 38169695Skan * 39169695Skan * 1) An arbitrary number of transport connections upon which rpc requests 40169695Skan * are received. The two most notable transports are TCP and UDP; they are 41169695Skan * created and registered by routines in svc_tcp.c and svc_udp.c, respectively; 42169695Skan * they in turn call xprt_register and xprt_unregister. 43169695Skan * 44169695Skan * 2) An arbitrary number of locally registered services. Services are 45169695Skan * described by the following four data: program number, version number, 46169695Skan * "service dispatch" function, a transport handle, and a boolean that 47169695Skan * indicates whether or not the exported program should be registered with a 48169695Skan * local binder service; if true the program's number and version and the 49169695Skan * port number from the transport handle are registered with the binder. 50169695Skan * These data are registered with the rpc svc system via svc_register. 51169695Skan * 52169695Skan * A service's dispatch function is called whenever an rpc request comes in 53169695Skan * on a transport. The request's program and version numbers must match 54169695Skan * those of the registered service. The dispatch function is passed two 55169695Skan * parameters, struct svc_req * and SVCXPRT *, defined below. 56169695Skan */ 57169695Skan 58169695Skanenum xprt_stat { 59169695Skan XPRT_DIED, 60169695Skan XPRT_MOREREQS, 61169695Skan XPRT_IDLE 62169695Skan}; 63169695Skan 64169695Skan/* 65169695Skan * Server side transport handle 66169695Skan */ 67169695Skantypedef struct { 68169695Skan int xp_sock; 69169695Skan u_short xp_port; /* associated port number */ 70169695Skan struct xp_ops { 71169695Skan bool_t (*xp_recv)(); /* receive incomming requests */ 72169695Skan enum xprt_stat (*xp_stat)(); /* get transport status */ 73169695Skan bool_t (*xp_getargs)(); /* get arguments */ 74169695Skan bool_t (*xp_reply)(); /* send reply */ 75169695Skan bool_t (*xp_freeargs)(); /* free mem allocated for args */ 76169695Skan void (*xp_destroy)(); /* destroy this struct */ 77169695Skan } *xp_ops; 78169695Skan int xp_addrlen; /* length of remote address */ 79169695Skan struct sockaddr_in xp_raddr; /* remote address */ 80169695Skan struct opaque_auth xp_verf; /* raw response verifier */ 81169695Skan caddr_t xp_p1; /* private: for use by svc ops */ 82169695Skan caddr_t xp_p2; /* private: for use by svc ops */ 83169695Skan caddr_t xp_p3; /* private: for use by svc lib */ 84169695Skan} SVCXPRT; 85169695Skan 86169695Skan/* 87169695Skan * Approved way of getting address of caller 88169695Skan */ 89169695Skan#define svc_getcaller(x) (&(x)->xp_raddr) 90169695Skan 91169695Skan/* 92169695Skan * Operations defined on an SVCXPRT handle 93169695Skan * 94169695Skan * SVCXPRT *xprt; 95169695Skan * struct rpc_msg *msg; 96169695Skan * xdrproc_t xargs; 97169695Skan * caddr_t argsp; 98169695Skan */ 99169695Skan#define SVC_RECV(xprt, msg) \ 100169695Skan (*(xprt)->xp_ops->xp_recv)((xprt), (msg)) 101169695Skan#define svc_recv(xprt, msg) \ 102169695Skan (*(xprt)->xp_ops->xp_recv)((xprt), (msg)) 103169695Skan 104169695Skan#define SVC_STAT(xprt) \ 105169695Skan (*(xprt)->xp_ops->xp_stat)(xprt) 106169695Skan#define svc_stat(xprt) \ 107169695Skan (*(xprt)->xp_ops->xp_stat)(xprt) 108169695Skan 109169695Skan#define SVC_GETARGS(xprt, xargs, argsp) \ 110169695Skan (*(xprt)->xp_ops->xp_getargs)((xprt), (xargs), (argsp)) 111169695Skan#define svc_getargs(xprt, xargs, argsp) \ 112169695Skan (*(xprt)->xp_ops->xp_getargs)((xprt), (xargs), (argsp)) 113169695Skan 114169695Skan#define SVC_REPLY(xprt, msg) \ 115169695Skan (*(xprt)->xp_ops->xp_reply) ((xprt), (msg)) 116169695Skan#define svc_reply(xprt, msg) \ 117169695Skan (*(xprt)->xp_ops->xp_reply) ((xprt), (msg)) 118169695Skan 119169695Skan#define SVC_FREEARGS(xprt, xargs, argsp) \ 120169695Skan (*(xprt)->xp_ops->xp_freeargs)((xprt), (xargs), (argsp)) 121169695Skan#define svc_freeargs(xprt, xargs, argsp) \ 122169695Skan (*(xprt)->xp_ops->xp_freeargs)((xprt), (xargs), (argsp)) 123169695Skan 124169695Skan#define SVC_DESTROY(xprt) \ 125169695Skan (*(xprt)->xp_ops->xp_destroy)(xprt) 126169695Skan#define svc_destroy(xprt) \ 127169695Skan (*(xprt)->xp_ops->xp_destroy)(xprt) 128169695Skan 129169695Skan 130169695Skan/* 131169695Skan * Service request 132169695Skan */ 133169695Skanstruct svc_req { 134169695Skan u_long rq_prog; /* service program number */ 135169695Skan u_long rq_vers; /* service protocol version */ 136169695Skan u_long rq_proc; /* the desired procedure */ 137169695Skan struct opaque_auth rq_cred; /* raw creds from the wire */ 138169695Skan caddr_t rq_clntcred; /* read only cooked cred */ 139169695Skan SVCXPRT *rq_xprt; /* associated transport */ 140169695Skan}; 141169695Skan 142169695Skan 143169695Skan/* 144169695Skan * Service registration 145169695Skan * 146169695Skan * svc_register(xprt, prog, vers, dispatch, protocol) 147169695Skan * SVCXPRT *xprt; 148169695Skan * u_long prog; 149169695Skan * u_long vers; 150169695Skan * void (*dispatch)(); 151169695Skan * int protocol; like TCP or UDP, zero means do not register 152169695Skan */ 153169695Skanextern bool_t svc_register(); 154169695Skan 155169695Skan/* 156169695Skan * Service un-registration 157169695Skan * 158 * svc_unregister(prog, vers) 159 * u_long prog; 160 * u_long vers; 161 */ 162extern void svc_unregister(); 163 164/* 165 * Transport registration. 166 * 167 * xprt_register(xprt) 168 * SVCXPRT *xprt; 169 */ 170extern void xprt_register(); 171 172/* 173 * Transport un-register 174 * 175 * xprt_unregister(xprt) 176 * SVCXPRT *xprt; 177 */ 178extern 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 209extern bool_t svc_sendreply(); 210extern void svcerr_decode(); 211extern void svcerr_weakauth(); 212extern void svcerr_noproc(); 213extern void svcerr_progvers(); 214extern void svcerr_auth(); 215extern void svcerr_noprog(); 216extern 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 */ 233extern 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 */ 240extern void rpctest_service(); 241 242extern void svc_getreq(); 243extern void svc_getreqset(); /* takes fdset instead of int */ 244extern 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 */ 258extern SVCXPRT *svcraw_create(); 259 260/* 261 * Udp based rpc. 262 */ 263extern SVCXPRT *svcudp_create(); 264extern SVCXPRT *svcudp_bufcreate(); 265 266/* 267 * Tcp based rpc. 268 */ 269extern SVCXPRT *svctcp_create(); 270 271/* 272 * Like svtcp_create(), except the routine takes any *open* UNIX file 273 * descriptor as its first input. 274 */ 275SVCXPRT *svcfd_create(); 276#else 277 278/* 279 * Kernel udp based rpc. 280 */ 281extern SVCXPRT *svckudp_create(); 282 283 284#endif /* !_rpc_svc_h */ 285