1 /* $NetBSD: svc.h,v 1.17 2000/06/02 22:57:56 fvdl Exp $ */ 2 3 /*- 4 * SPDX-License-Identifier: BSD-3-Clause 5 * 6 * Copyright (c) 2009, Sun Microsystems, Inc. 7 * All rights reserved. 8 * 9 * Redistribution and use in source and binary forms, with or without 10 * modification, are permitted provided that the following conditions are met: 11 * - Redistributions of source code must retain the above copyright notice, 12 * this list of conditions and the following disclaimer. 13 * - Redistributions in binary form must reproduce the above copyright notice, 14 * this list of conditions and the following disclaimer in the documentation 15 * and/or other materials provided with the distribution. 16 * - Neither the name of Sun Microsystems, Inc. nor the names of its 17 * contributors may be used to endorse or promote products derived 18 * from this software without specific prior written permission. 19 * 20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 21 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 24 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 25 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 26 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 27 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 28 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 29 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 30 * POSSIBILITY OF SUCH DAMAGE. 31 */ 32 33 /* 34 * svc.h, Server-side remote procedure call interface. 35 * 36 * Copyright (C) 1986-1993 by Sun Microsystems, Inc. 37 */ 38 39 #ifndef _RPC_SVC_H 40 #define _RPC_SVC_H 41 #include <sys/cdefs.h> 42 43 /* 44 * This interface must manage two items concerning remote procedure calling: 45 * 46 * 1) An arbitrary number of transport connections upon which rpc requests 47 * are received. The two most notable transports are TCP and UDP; they are 48 * created and registered by routines in svc_tcp.c and svc_udp.c, respectively; 49 * they in turn call xprt_register and xprt_unregister. 50 * 51 * 2) An arbitrary number of locally registered services. Services are 52 * described by the following four data: program number, version number, 53 * "service dispatch" function, a transport handle, and a boolean that 54 * indicates whether or not the exported program should be registered with a 55 * local binder service; if true the program's number and version and the 56 * port number from the transport handle are registered with the binder. 57 * These data are registered with the rpc svc system via svc_register. 58 * 59 * A service's dispatch function is called whenever an rpc request comes in 60 * on a transport. The request's program and version numbers must match 61 * those of the registered service. The dispatch function is passed two 62 * parameters, struct svc_req * and SVCXPRT *, defined below. 63 */ 64 65 /* 66 * Service control requests 67 */ 68 #define SVCGET_VERSQUIET 1 69 #define SVCSET_VERSQUIET 2 70 #define SVCGET_CONNMAXREC 3 71 #define SVCSET_CONNMAXREC 4 72 73 /* 74 * Operations for rpc_control(). 75 */ 76 #define RPC_SVC_CONNMAXREC_SET 0 /* set max rec size, enable nonblock */ 77 #define RPC_SVC_CONNMAXREC_GET 1 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 #define xp_sock xp_fd 91 u_short xp_port; /* associated port number */ 92 const struct xp_ops { 93 /* receive incoming requests */ 94 bool_t (*xp_recv)(struct __rpc_svcxprt *, struct rpc_msg *); 95 /* get transport status */ 96 enum xprt_stat (*xp_stat)(struct __rpc_svcxprt *); 97 /* get arguments */ 98 bool_t (*xp_getargs)(struct __rpc_svcxprt *, xdrproc_t, 99 void *); 100 /* send reply */ 101 bool_t (*xp_reply)(struct __rpc_svcxprt *, struct rpc_msg *); 102 /* free mem allocated for args */ 103 bool_t (*xp_freeargs)(struct __rpc_svcxprt *, xdrproc_t, 104 void *); 105 /* destroy this struct */ 106 void (*xp_destroy)(struct __rpc_svcxprt *); 107 } *xp_ops; 108 int xp_addrlen; /* length of remote address */ 109 struct sockaddr_in xp_raddr; /* remote addr. (backward ABI compat) */ 110 /* XXX - fvdl stick this here for ABI backward compat reasons */ 111 const struct xp_ops2 { 112 /* catch-all function */ 113 bool_t (*xp_control)(struct __rpc_svcxprt *, const u_int, 114 void *); 115 } *xp_ops2; 116 char *xp_tp; /* transport provider device name */ 117 char *xp_netid; /* network token */ 118 struct netbuf xp_ltaddr; /* local transport address */ 119 struct netbuf xp_rtaddr; /* remote transport address */ 120 struct opaque_auth xp_verf; /* raw response verifier */ 121 void *xp_p1; /* private: for use by svc ops */ 122 void *xp_p2; /* private: for use by svc ops */ 123 void *xp_p3; /* private: for use by svc lib */ 124 int xp_type; /* transport type */ 125 } SVCXPRT; 126 127 /* 128 * Interface to server-side authentication flavors. 129 */ 130 typedef struct __rpc_svcauth { 131 struct svc_auth_ops { 132 int (*svc_ah_wrap)(struct __rpc_svcauth *, XDR *, 133 xdrproc_t, caddr_t); 134 int (*svc_ah_unwrap)(struct __rpc_svcauth *, XDR *, 135 xdrproc_t, caddr_t); 136 } *svc_ah_ops; 137 void *svc_ah_private; 138 } SVCAUTH; 139 140 /* 141 * Server transport extensions (accessed via xp_p3). 142 */ 143 typedef struct __rpc_svcxprt_ext { 144 int xp_flags; /* versquiet */ 145 SVCAUTH xp_auth; /* interface to auth methods */ 146 } SVCXPRT_EXT; 147 148 /* 149 * Service request 150 */ 151 struct svc_req { 152 u_int32_t rq_prog; /* service program number */ 153 u_int32_t rq_vers; /* service protocol version */ 154 u_int32_t rq_proc; /* the desired procedure */ 155 struct opaque_auth rq_cred; /* raw creds from the wire */ 156 void *rq_clntcred; /* read only cooked cred */ 157 SVCXPRT *rq_xprt; /* associated transport */ 158 }; 159 160 /* 161 * Approved way of getting address of caller 162 */ 163 #define svc_getrpccaller(x) (&(x)->xp_rtaddr) 164 /* 165 * Approved way of getting address of callee 166 */ 167 #define svc_getrpccallee(x) (&(x)->xp_ltaddr) 168 169 /* 170 * Operations defined on an SVCXPRT handle 171 * 172 * SVCXPRT *xprt; 173 * struct rpc_msg *msg; 174 * xdrproc_t xargs; 175 * void * argsp; 176 */ 177 #define SVC_RECV(xprt, msg) \ 178 (*(xprt)->xp_ops->xp_recv)((xprt), (msg)) 179 #define svc_recv(xprt, msg) \ 180 (*(xprt)->xp_ops->xp_recv)((xprt), (msg)) 181 182 #define SVC_STAT(xprt) \ 183 (*(xprt)->xp_ops->xp_stat)(xprt) 184 #define svc_stat(xprt) \ 185 (*(xprt)->xp_ops->xp_stat)(xprt) 186 187 #define SVC_GETARGS(xprt, xargs, argsp) \ 188 (*(xprt)->xp_ops->xp_getargs)((xprt), (xargs), (argsp)) 189 #define svc_getargs(xprt, xargs, argsp) \ 190 (*(xprt)->xp_ops->xp_getargs)((xprt), (xargs), (argsp)) 191 192 #define SVC_REPLY(xprt, msg) \ 193 (*(xprt)->xp_ops->xp_reply) ((xprt), (msg)) 194 #define svc_reply(xprt, msg) \ 195 (*(xprt)->xp_ops->xp_reply) ((xprt), (msg)) 196 197 #define SVC_FREEARGS(xprt, xargs, argsp) \ 198 (*(xprt)->xp_ops->xp_freeargs)((xprt), (xargs), (argsp)) 199 #define svc_freeargs(xprt, xargs, argsp) \ 200 (*(xprt)->xp_ops->xp_freeargs)((xprt), (xargs), (argsp)) 201 202 #define SVC_DESTROY(xprt) \ 203 (*(xprt)->xp_ops->xp_destroy)(xprt) 204 #define svc_destroy(xprt) \ 205 (*(xprt)->xp_ops->xp_destroy)(xprt) 206 207 #define SVC_CONTROL(xprt, rq, in) \ 208 (*(xprt)->xp_ops2->xp_control)((xprt), (rq), (in)) 209 210 #define SVC_EXT(xprt) \ 211 ((SVCXPRT_EXT *) xprt->xp_p3) 212 213 #define SVC_AUTH(xprt) \ 214 (SVC_EXT(xprt)->xp_auth) 215 216 /* 217 * Operations defined on an SVCAUTH handle 218 */ 219 #define SVCAUTH_WRAP(auth, xdrs, xfunc, xwhere) \ 220 ((auth)->svc_ah_ops->svc_ah_wrap(auth, xdrs, xfunc, xwhere)) 221 #define SVCAUTH_UNWRAP(auth, xdrs, xfunc, xwhere) \ 222 ((auth)->svc_ah_ops->svc_ah_unwrap(auth, xdrs, xfunc, xwhere)) 223 224 /* 225 * Service registration 226 * 227 * svc_reg(xprt, prog, vers, dispatch, nconf) 228 * const SVCXPRT *xprt; 229 * const rpcprog_t prog; 230 * const rpcvers_t vers; 231 * const void (*dispatch)(struct svc_req *, SVCXPRT *); 232 * const struct netconfig *nconf; 233 */ 234 235 __BEGIN_DECLS 236 extern bool_t svc_reg(SVCXPRT *, const rpcprog_t, const rpcvers_t, 237 void (*)(struct svc_req *, SVCXPRT *), 238 const struct netconfig *); 239 __END_DECLS 240 241 /* 242 * Service un-registration 243 * 244 * svc_unreg(prog, vers) 245 * const rpcprog_t prog; 246 * const rpcvers_t vers; 247 */ 248 249 __BEGIN_DECLS 250 extern void svc_unreg(const rpcprog_t, const rpcvers_t); 251 __END_DECLS 252 253 /* 254 * Transport registration. 255 * 256 * xprt_register(xprt) 257 * SVCXPRT *xprt; 258 */ 259 __BEGIN_DECLS 260 extern void xprt_register(SVCXPRT *); 261 __END_DECLS 262 263 /* 264 * Transport un-register 265 * 266 * xprt_unregister(xprt) 267 * SVCXPRT *xprt; 268 */ 269 __BEGIN_DECLS 270 extern void xprt_unregister(SVCXPRT *); 271 __END_DECLS 272 273 274 /* 275 * When the service routine is called, it must first check to see if it 276 * knows about the procedure; if not, it should call svcerr_noproc 277 * and return. If so, it should deserialize its arguments via 278 * SVC_GETARGS (defined above). If the deserialization does not work, 279 * svcerr_decode should be called followed by a return. Successful 280 * decoding of the arguments should be followed the execution of the 281 * procedure's code and a call to svc_sendreply. 282 * 283 * Also, if the service refuses to execute the procedure due to too- 284 * weak authentication parameters, svcerr_weakauth should be called. 285 * Note: do not confuse access-control failure with weak authentication! 286 * 287 * NB: In pure implementations of rpc, the caller always waits for a reply 288 * msg. This message is sent when svc_sendreply is called. 289 * Therefore pure service implementations should always call 290 * svc_sendreply even if the function logically returns void; use 291 * xdr.h - xdr_void for the xdr routine. HOWEVER, tcp based rpc allows 292 * for the abuse of pure rpc via batched calling or pipelining. In the 293 * case of a batched call, svc_sendreply should NOT be called since 294 * this would send a return message, which is what batching tries to avoid. 295 * It is the service/protocol writer's responsibility to know which calls are 296 * batched and which are not. Warning: responding to batch calls may 297 * deadlock the caller and server processes! 298 */ 299 300 __BEGIN_DECLS 301 extern bool_t svc_sendreply(SVCXPRT *, xdrproc_t, void *); 302 extern void svcerr_decode(SVCXPRT *); 303 extern void svcerr_weakauth(SVCXPRT *); 304 extern void svcerr_noproc(SVCXPRT *); 305 extern void svcerr_progvers(SVCXPRT *, rpcvers_t, rpcvers_t); 306 extern void svcerr_auth(SVCXPRT *, enum auth_stat); 307 extern void svcerr_noprog(SVCXPRT *); 308 extern void svcerr_systemerr(SVCXPRT *); 309 extern int rpc_reg(rpcprog_t, rpcvers_t, rpcproc_t, 310 char *(*)(char *), xdrproc_t, xdrproc_t, 311 char *); 312 __END_DECLS 313 314 /* 315 * Lowest level dispatching -OR- who owns this process anyway. 316 * Somebody has to wait for incoming requests and then call the correct 317 * service routine. The routine svc_run does infinite waiting; i.e., 318 * svc_run never returns. 319 * Since another (co-existent) package may wish to selectively wait for 320 * incoming calls or other events outside of the rpc architecture, the 321 * routine svc_getreq is provided. It must be passed readfds, the 322 * "in-place" results of a select system call (see select, section 2). 323 */ 324 325 /* 326 * Global keeper of rpc service descriptors in use 327 * dynamic; must be inspected before each call to select 328 */ 329 extern int svc_maxfd; 330 #ifdef FD_SETSIZE 331 extern fd_set svc_fdset; 332 #define svc_fds svc_fdset.fds_bits[0] /* compatibility */ 333 #else 334 extern int svc_fds; 335 #endif /* def FD_SETSIZE */ 336 337 /* 338 * A set of null auth methods used by any authentication protocols 339 * that don't need to inspect or modify the message body. 340 */ 341 extern SVCAUTH _svc_auth_null; 342 343 /* 344 * a small program implemented by the svc_rpc implementation itself; 345 * also see clnt.h for protocol numbers. 346 */ 347 __BEGIN_DECLS 348 extern void rpctest_service(void); 349 __END_DECLS 350 351 __BEGIN_DECLS 352 extern SVCXPRT *svc_xprt_alloc(void); 353 extern void svc_xprt_free(SVCXPRT *); 354 extern void svc_getreq(int); 355 extern void svc_getreqset(fd_set *); 356 extern void svc_getreq_common(int); 357 struct pollfd; 358 extern void svc_getreq_poll(struct pollfd *, int); 359 360 extern void svc_run(void); 361 extern void svc_exit(void); 362 __END_DECLS 363 364 /* 365 * Socket to use on svcxxx_create call to get default socket 366 */ 367 #define RPC_ANYSOCK -1 368 #define RPC_ANYFD RPC_ANYSOCK 369 370 /* 371 * These are the existing service side transport implementations 372 */ 373 374 __BEGIN_DECLS 375 /* 376 * Transport independent svc_create routine. 377 */ 378 extern int svc_create(void (*)(struct svc_req *, SVCXPRT *), 379 const rpcprog_t, const rpcvers_t, const char *); 380 /* 381 * void (*dispatch)(struct svc_req *, SVCXPRT *); 382 * const rpcprog_t prognum; -- program number 383 * const rpcvers_t versnum; -- version number 384 * const char *nettype; -- network type 385 */ 386 387 388 /* 389 * Generic server creation routine. It takes a netconfig structure 390 * instead of a nettype. 391 */ 392 393 extern SVCXPRT *svc_tp_create(void (*)(struct svc_req *, SVCXPRT *), 394 const rpcprog_t, const rpcvers_t, 395 const struct netconfig *); 396 /* 397 * void (*dispatch)(struct svc_req *, SVCXPRT *); 398 * const rpcprog_t prognum; -- program number 399 * const rpcvers_t versnum; -- version number 400 * const struct netconfig *nconf; -- netconfig structure 401 */ 402 403 404 /* 405 * Generic TLI create routine 406 */ 407 extern SVCXPRT *svc_tli_create(const int, const struct netconfig *, 408 const struct t_bind *, const u_int, 409 const u_int); 410 /* 411 * const int fd; -- connection end point 412 * const struct netconfig *nconf; -- netconfig structure for network 413 * const struct t_bind *bindaddr; -- local bind address 414 * const u_int sendsz; -- max sendsize 415 * const u_int recvsz; -- max recvsize 416 */ 417 418 /* 419 * Connectionless and connectionful create routines 420 */ 421 422 extern SVCXPRT *svc_vc_create(const int, const u_int, const u_int); 423 /* 424 * const int fd; -- open connection end point 425 * const u_int sendsize; -- max send size 426 * const u_int recvsize; -- max recv size 427 */ 428 429 /* 430 * Added for compatibility to old rpc 4.0. Obsoleted by svc_vc_create(). 431 */ 432 extern SVCXPRT *svcunix_create(int, u_int, u_int, char *); 433 434 extern SVCXPRT *svc_dg_create(const int, const u_int, const u_int); 435 /* 436 * const int fd; -- open connection 437 * const u_int sendsize; -- max send size 438 * const u_int recvsize; -- max recv size 439 */ 440 441 442 /* 443 * the routine takes any *open* connection 444 * descriptor as its first input and is used for open connections. 445 */ 446 extern SVCXPRT *svc_fd_create(const int, const u_int, const u_int); 447 /* 448 * const int fd; -- open connection end point 449 * const u_int sendsize; -- max send size 450 * const u_int recvsize; -- max recv size 451 */ 452 453 /* 454 * Added for compatibility to old rpc 4.0. Obsoleted by svc_fd_create(). 455 */ 456 extern SVCXPRT *svcunixfd_create(int, u_int, u_int); 457 458 /* 459 * Memory based rpc (for speed check and testing) 460 */ 461 extern SVCXPRT *svc_raw_create(void); 462 463 /* 464 * svc_dg_enable_cache() enables the cache on dg transports. 465 */ 466 int svc_dg_enablecache(SVCXPRT *, const u_int); 467 468 int __rpc_get_local_uid(SVCXPRT *_transp, uid_t *_uid); 469 470 __END_DECLS 471 472 473 /* for backward compatibility */ 474 #include <rpc/svc_soc.h> 475 476 #endif /* !_RPC_SVC_H */ 477