svc.h revision 330897
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: stable/11/include/rpc/svc.h 330897 2018-03-14 03:19:51Z eadler $ 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 83enum xprt_stat { 84 XPRT_DIED, 85 XPRT_MOREREQS, 86 XPRT_IDLE 87}; 88 89/* 90 * Server side transport handle 91 */ 92typedef 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 */ 134typedef 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 */ 147typedef 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 */ 155struct 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/* 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 236extern 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 250extern 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 260extern 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 270extern 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 301extern bool_t svc_sendreply(SVCXPRT *, xdrproc_t, void *); 302extern void svcerr_decode(SVCXPRT *); 303extern void svcerr_weakauth(SVCXPRT *); 304extern void svcerr_noproc(SVCXPRT *); 305extern void svcerr_progvers(SVCXPRT *, rpcvers_t, rpcvers_t); 306extern void svcerr_auth(SVCXPRT *, enum auth_stat); 307extern void svcerr_noprog(SVCXPRT *); 308extern void svcerr_systemerr(SVCXPRT *); 309extern 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 */ 329extern int svc_maxfd; 330#ifdef FD_SETSIZE 331extern fd_set svc_fdset; 332#define svc_fds svc_fdset.fds_bits[0] /* compatibility */ 333#else 334extern 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 */ 341extern 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 348extern void rpctest_service(void); 349__END_DECLS 350 351__BEGIN_DECLS 352extern SVCXPRT *svc_xprt_alloc(void); 353extern void svc_xprt_free(SVCXPRT *); 354extern void svc_getreq(int); 355extern void svc_getreqset(fd_set *); 356extern void svc_getreq_common(int); 357struct pollfd; 358extern void svc_getreq_poll(struct pollfd *, int); 359 360extern void svc_run(void); 361extern 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 */ 378extern 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 393extern 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 */ 407extern 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 422extern 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 */ 432extern SVCXPRT *svcunix_create(int, u_int, u_int, char *); 433 434extern 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 */ 446extern 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 */ 456extern SVCXPRT *svcunixfd_create(int, u_int, u_int); 457 458/* 459 * Memory based rpc (for speed check and testing) 460 */ 461extern SVCXPRT *svc_raw_create(void); 462 463/* 464 * svc_dg_enable_cache() enables the cache on dg transports. 465 */ 466int svc_dg_enablecache(SVCXPRT *, const u_int); 467 468int __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