1 /* $NetBSD: svc.h,v 1.33 2022/05/28 21:14:56 andvar Exp $ */ 2 3 /* 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. 10 * 11 * SUN RPC IS PROVIDED AS IS WITH NO WARRANTIES OF ANY KIND INCLUDING THE 12 * WARRANTIES OF DESIGN, MERCHANTIBILITY AND FITNESS FOR A PARTICULAR 13 * PURPOSE, OR ARISING FROM A COURSE OF DEALING, USAGE OR TRADE PRACTICE. 14 * 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. 18 * 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. 22 * 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. 26 * 27 * Sun Microsystems, Inc. 28 * 2550 Garcia Avenue 29 * Mountain View, California 94043 30 * 31 * from: @(#)svc.h 1.35 88/12/17 SMI 32 * @(#)svc.h 1.27 94/04/25 SMI 33 */ 34 35 /* 36 * svc.h, Server-side remote procedure call interface. 37 * 38 * Copyright (C) 1986-1993 by Sun Microsystems, Inc. 39 */ 40 41 #ifndef _RPC_SVC_H_ 42 #define _RPC_SVC_H_ 43 #include <sys/cdefs.h> 44 45 #include <sys/select.h> 46 #include <rpc/rpc_com.h> 47 48 /* 49 * This interface must manage two items concerning remote procedure calling: 50 * 51 * 1) An arbitrary number of transport connections upon which rpc requests 52 * are received. The two most notable transports are TCP and UDP; they are 53 * created and registered by routines in svc_tcp.c and svc_udp.c, respectively; 54 * they in turn call xprt_register and xprt_unregister. 55 * 56 * 2) An arbitrary number of locally registered services. Services are 57 * described by the following four data: program number, version number, 58 * "service dispatch" function, a transport handle, and a boolean that 59 * indicates whether or not the exported program should be registered with a 60 * local binder service; if true the program's number and version and the 61 * port number from the transport handle are registered with the binder. 62 * These data are registered with the rpc svc system via svc_register. 63 * 64 * A service's dispatch function is called whenever an rpc request comes in 65 * on a transport. The request's program and version numbers must match 66 * those of the registered service. The dispatch function is passed two 67 * parameters, struct svc_req * and SVCXPRT *, defined below. 68 */ 69 70 /* 71 * Service control requests 72 */ 73 #define SVCGET_VERSQUIET 1 74 #define SVCSET_VERSQUIET 2 75 #define SVCGET_CONNMAXREC 3 76 #define SVCSET_CONNMAXREC 4 77 78 79 enum xprt_stat { 80 XPRT_DIED, 81 XPRT_MOREREQS, 82 XPRT_IDLE 83 }; 84 85 /* 86 * Server side transport handle 87 */ 88 typedef struct __rpc_svcxprt { 89 int xp_fd; 90 unsigned short xp_port; /* associated port number */ 91 const struct xp_ops { 92 /* receive incoming requests */ 93 bool_t (*xp_recv)(struct __rpc_svcxprt *, struct rpc_msg *); 94 /* get transport status */ 95 enum xprt_stat (*xp_stat)(struct __rpc_svcxprt *); 96 /* get arguments */ 97 bool_t (*xp_getargs)(struct __rpc_svcxprt *, xdrproc_t, 98 caddr_t); 99 /* send reply */ 100 bool_t (*xp_reply)(struct __rpc_svcxprt *, struct rpc_msg *); 101 /* free mem allocated for args */ 102 bool_t (*xp_freeargs)(struct __rpc_svcxprt *, xdrproc_t, 103 caddr_t); 104 /* destroy this struct */ 105 void (*xp_destroy)(struct __rpc_svcxprt *); 106 } *xp_ops; 107 int xp_addrlen; /* length of remote address */ 108 struct sockaddr_in xp_raddr; /* rem. addr. (backward ABI compat) */ 109 /* XXX - fvdl stick this here for ABI backward compat reasons */ 110 const struct xp_ops2 { 111 /* catch-all function */ 112 bool_t (*xp_control)(struct __rpc_svcxprt *, 113 const unsigned int, void *); 114 } *xp_ops2; 115 char *xp_tp; /* transport provider device name */ 116 char *xp_netid; /* network token */ 117 struct netbuf xp_ltaddr; /* local transport address */ 118 struct netbuf xp_rtaddr; /* remote transport address */ 119 struct opaque_auth xp_verf; /* raw response verifier */ 120 void *xp_p1; /* private: for use by svc ops */ 121 void *xp_p2; /* private: for use by svc ops */ 122 void *xp_p3; /* private: for use by svc lib */ 123 int xp_type; /* transport type */ 124 } SVCXPRT; 125 126 /* 127 * Service request 128 */ 129 struct svc_req { 130 uint32_t rq_prog; /* service program number */ 131 uint32_t rq_vers; /* service protocol version */ 132 uint32_t rq_proc; /* the desired procedure */ 133 struct opaque_auth rq_cred; /* raw creds from the wire */ 134 void *rq_clntcred; /* read only cooked cred */ 135 SVCXPRT *rq_xprt; /* associated transport */ 136 }; 137 138 /* 139 * Approved way of getting address of caller 140 */ 141 #define svc_getrpccaller(x) (&(x)->xp_rtaddr) 142 143 /* 144 * NetBSD-only definition to get the creds of the caller (AF_LOCAL). 145 */ 146 #define __svc_getcallercreds(x) ((struct sockcred *)(x)->xp_p2) 147 148 /* 149 * Operations defined on an SVCXPRT handle 150 * 151 * SVCXPRT *xprt; 152 * struct rpc_msg *msg; 153 * xdrproc_t xargs; 154 * caddr_t argsp; 155 */ 156 #define SVC_RECV(xprt, msg) \ 157 (*(xprt)->xp_ops->xp_recv)((xprt), (msg)) 158 #define svc_recv(xprt, msg) \ 159 (*(xprt)->xp_ops->xp_recv)((xprt), (msg)) 160 161 #define SVC_STAT(xprt) \ 162 (*(xprt)->xp_ops->xp_stat)(xprt) 163 #define svc_stat(xprt) \ 164 (*(xprt)->xp_ops->xp_stat)(xprt) 165 166 #define SVC_GETARGS(xprt, xargs, argsp) \ 167 (*(xprt)->xp_ops->xp_getargs)((xprt), ((xdrproc_t)(xargs)), (argsp)) 168 #define svc_getargs(xprt, xargs, argsp) \ 169 (*(xprt)->xp_ops->xp_getargs)((xprt), ((xdrproc_t)(xargs)), (argsp)) 170 171 #define SVC_REPLY(xprt, msg) \ 172 (*(xprt)->xp_ops->xp_reply) ((xprt), (msg)) 173 #define svc_reply(xprt, msg) \ 174 (*(xprt)->xp_ops->xp_reply) ((xprt), (msg)) 175 176 #define SVC_FREEARGS(xprt, xargs, argsp) \ 177 (*(xprt)->xp_ops->xp_freeargs)((xprt), ((xdrproc_t)(xargs)), (argsp)) 178 #define svc_freeargs(xprt, xargs, argsp) \ 179 (*(xprt)->xp_ops->xp_freeargs)((xprt), ((xdrproc_t)(xargs)), (argsp)) 180 181 #define SVC_DESTROY(xprt) \ 182 (*(xprt)->xp_ops->xp_destroy)(xprt) 183 #define svc_destroy(xprt) \ 184 (*(xprt)->xp_ops->xp_destroy)(xprt) 185 186 #define SVC_CONTROL(xprt, rq, in) \ 187 (*(xprt)->xp_ops2->xp_control)((xprt), (rq), (in)) 188 189 /* 190 * Service registration 191 * 192 * svc_reg(xprt, prog, vers, dispatch, nconf) 193 * const SVCXPRT *xprt; 194 * const rpcprog_t prog; 195 * const rpcvers_t vers; 196 * const void (*dispatch)(...); 197 * const struct netconfig *nconf; 198 */ 199 200 __BEGIN_DECLS 201 extern bool_t svc_reg(SVCXPRT *, const rpcprog_t, const rpcvers_t, 202 void (*)(struct svc_req *, SVCXPRT *), 203 const struct netconfig *); 204 __END_DECLS 205 206 /* 207 * Service un-registration 208 * 209 * svc_unreg(prog, vers) 210 * const rpcprog_t prog; 211 * const rpcvers_t vers; 212 */ 213 214 __BEGIN_DECLS 215 extern void svc_unreg(const rpcprog_t, const rpcvers_t); 216 __END_DECLS 217 218 /* 219 * Transport registration. 220 * 221 * xprt_register(xprt) 222 * SVCXPRT *xprt; 223 */ 224 __BEGIN_DECLS 225 extern bool_t xprt_register (SVCXPRT *); 226 __END_DECLS 227 228 /* 229 * Transport un-register 230 * 231 * xprt_unregister(xprt) 232 * SVCXPRT *xprt; 233 */ 234 __BEGIN_DECLS 235 extern void xprt_unregister (SVCXPRT *); 236 __END_DECLS 237 238 239 /* 240 * When the service routine is called, it must first check to see if it 241 * knows about the procedure; if not, it should call svcerr_noproc 242 * and return. If so, it should deserialize its arguments via 243 * SVC_GETARGS (defined above). If the deserialization does not work, 244 * svcerr_decode should be called followed by a return. Successful 245 * decoding of the arguments should be followed the execution of the 246 * procedure's code and a call to svc_sendreply. 247 * 248 * Also, if the service refuses to execute the procedure due to too- 249 * weak authentication parameters, svcerr_weakauth should be called. 250 * Note: do not confuse access-control failure with weak authentication! 251 * 252 * NB: In pure implementations of rpc, the caller always waits for a reply 253 * msg. This message is sent when svc_sendreply is called. 254 * Therefore pure service implementations should always call 255 * svc_sendreply even if the function logically returns void; use 256 * xdr.h - xdr_void for the xdr routine. HOWEVER, tcp based rpc allows 257 * for the abuse of pure rpc via batched calling or pipelining. In the 258 * case of a batched call, svc_sendreply should NOT be called since 259 * this would send a return message, which is what batching tries to avoid. 260 * It is the service/protocol writer's responsibility to know which calls are 261 * batched and which are not. Warning: responding to batch calls may 262 * deadlock the caller and server processes! 263 */ 264 265 __BEGIN_DECLS 266 extern bool_t svc_sendreply (SVCXPRT *, xdrproc_t, const char *); 267 extern void svcerr_decode (SVCXPRT *); 268 extern void svcerr_weakauth (SVCXPRT *); 269 extern void svcerr_noproc (SVCXPRT *); 270 extern void svcerr_progvers (SVCXPRT *, rpcvers_t, rpcvers_t); 271 extern void svcerr_auth (SVCXPRT *, enum auth_stat); 272 extern void svcerr_noprog (SVCXPRT *); 273 extern void svcerr_systemerr(SVCXPRT *); 274 extern int rpc_reg(rpcprog_t, rpcvers_t, rpcproc_t, 275 char *(*)(char *), xdrproc_t, xdrproc_t, 276 char *); 277 __END_DECLS 278 279 /* 280 * Lowest level dispatching -OR- who owns this process anyway. 281 * Somebody has to wait for incoming requests and then call the correct 282 * service routine. The routine svc_run does infinite waiting; i.e., 283 * svc_run never returns. 284 * Since another (co-existent) package may wish to selectively wait for 285 * incoming calls or other events outside of the rpc architecture, the 286 * routine svc_getreq is provided. It must be passed readfds, the 287 * "in-place" results of a select system call (see select, section 2). 288 */ 289 290 /* 291 * Global keeper of rpc service descriptors in use 292 * dynamic; must be inspected before each call to select 293 */ 294 #ifdef SVC_LEGACY 295 extern int svc_maxfd; 296 extern fd_set svc_fdset; 297 #else 298 #define svc_maxfd (*svc_fdset_getmax()) 299 #define svc_fdset (*svc_fdset_get()) 300 #define svc_pollfd svc_pollfd_get() 301 #define svc_max_pollfd (*svc_fdset_getmax()) 302 #endif 303 304 #define svc_fds svc_fdset.fds_bits[0] /* compatibility */ 305 306 /* 307 * a small program implemented by the svc_rpc implementation itself; 308 * also see clnt.h for protocol numbers. 309 */ 310 __BEGIN_DECLS 311 extern void rpctest_service(void); 312 __END_DECLS 313 314 __BEGIN_DECLS 315 316 #define SVC_FDSET_MT 1 /* each thread gets own fd_set/pollfd */ 317 #define SVC_FDSET_POLL 2 /* use poll in svc_run */ 318 extern void svc_fdset_init(int); 319 320 321 extern void svc_fdset_zero(void); 322 extern int svc_fdset_isset(int); 323 extern int svc_fdset_clr(int); 324 extern int svc_fdset_set(int); 325 326 extern fd_set *svc_fdset_get(void); 327 extern int svc_fdset_getsize(int); 328 extern int *svc_fdset_getmax(void); 329 extern fd_set *svc_fdset_copy(const fd_set *); 330 331 extern struct pollfd *svc_pollfd_get(void); 332 extern int svc_pollfd_getsize(int); 333 extern int *svc_pollfd_getmax(void); 334 extern struct pollfd *svc_pollfd_copy(const struct pollfd *); 335 336 extern void svc_getreq (int); 337 extern void svc_getreqset (fd_set *); 338 extern void svc_getreqset2 (fd_set *, int); 339 extern void svc_getreq_common (int); 340 struct pollfd; 341 extern void svc_getreq_poll(struct pollfd *, int); 342 343 extern void svc_run (void); 344 extern void svc_exit (void); 345 __END_DECLS 346 347 /* 348 * Socket to use on svcxxx_create call to get default socket 349 */ 350 #define RPC_ANYSOCK -1 351 #define RPC_ANYFD RPC_ANYSOCK 352 353 /* 354 * These are the existing service side transport implementations 355 */ 356 357 __BEGIN_DECLS 358 /* 359 * Transport independent svc_create routine. 360 */ 361 extern int svc_create(void (*)(struct svc_req *, SVCXPRT *), 362 const rpcprog_t, const rpcvers_t, const char *); 363 /* 364 * void (*dispatch)(...); -- dispatch routine 365 * const rpcprog_t prognum; -- program number 366 * const rpcvers_t versnum; -- version number 367 * const char *nettype; -- network type 368 */ 369 370 371 /* 372 * Generic server creation routine. It takes a netconfig structure 373 * instead of a nettype. 374 */ 375 376 extern SVCXPRT *svc_tp_create(void (*)(struct svc_req *, SVCXPRT *), 377 const rpcprog_t, const rpcvers_t, 378 const struct netconfig *); 379 /* 380 * void (*dispatch)(...); -- dispatch routine 381 * const rpcprog_t prognum; -- program number 382 * const rpcvers_t versnum; -- version number 383 * const struct netconfig *nconf; -- netconfig structure 384 */ 385 386 387 /* 388 * Generic TLI create routine 389 */ 390 extern SVCXPRT *svc_tli_create(const int, const struct netconfig *, 391 const struct t_bind *, const unsigned int, 392 const unsigned int); 393 /* 394 * const int fd; -- connection end point 395 * const struct netconfig *nconf; -- netconfig structure for network 396 * const struct t_bind *bindaddr; -- local bind address 397 * const unsigned sendsz; -- max sendsize 398 * const unsigned recvsz; -- max recvsize 399 */ 400 401 /* 402 * Connectionless and connectionful create routines 403 */ 404 405 extern SVCXPRT *svc_vc_create(const int, const unsigned int, 406 const unsigned int); 407 /* 408 * const int fd; -- open connection end point 409 * const unsigned sendsize; -- max send size 410 * const unsigned recvsize; -- max recv size 411 */ 412 413 extern SVCXPRT *svc_dg_create(const int, const unsigned int, 414 const unsigned int); 415 /* 416 * const int fd; -- open connection 417 * const unsigned sendsize; -- max send size 418 * const unsigned recvsize; -- max recv size 419 */ 420 421 422 /* 423 * the routine takes any *open* connection 424 * descriptor as its first input and is used for open connections. 425 */ 426 extern SVCXPRT *svc_fd_create(const int, const unsigned int, 427 const unsigned int); 428 /* 429 * const int fd; -- open connection end point 430 * const unsigned sendsize; -- max send size 431 * const unsigned recvsize; -- max recv size 432 */ 433 434 /* 435 * Memory based rpc (for speed check and testing) 436 */ 437 extern SVCXPRT *svc_raw_create(void); 438 439 /* 440 * svc_dg_enable_cache() enables the cache on dg transports. 441 */ 442 int svc_dg_enablecache(SVCXPRT *, const unsigned int); 443 444 __END_DECLS 445 446 447 /* for backward compatibility */ 448 #include <rpc/svc_soc.h> 449 450 #endif /* !_RPC_SVC_H_ */ 451