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