usr/src/lib/libbc/inc/include/rpc/svc.h

   1 /*
   2  * CDDL HEADER START
   3  *
   4  * The contents of this file are subject to the terms of the
   5  * Common Development and Distribution License, Version 1.0 only
   6  * (the "License").  You may not use this file except in compliance
   7  * with the License.
   8  *
   9  * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
  10  * or http://www.opensolaris.org/os/licensing.
  11  * See the License for the specific language governing permissions
  12  * and limitations under the License.
  13  *
  14  * When distributing Covered Code, include this CDDL HEADER in each
  15  * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  16  * If applicable, add the following below this CDDL HEADER, with the
  17  * fields enclosed by brackets "[]" replaced with your own identifying
  18  * information: Portions Copyright [yyyy] [name of copyright owner]
  19  *
  20  * CDDL HEADER END
  21  */
  22 /*
  23  * Copyright 1984 Sun Microsystems, Inc.  All rights reserved.
  24  * Use is subject to license terms.
  25  */
  26
  27 #ifndef _rpc_svc_h
  28 #define _rpc_svc_h
  29
  30 #pragma ident   "%Z%%M% %I%     %E% SMI"
  31
  32 /*
  33  * svc.h, Server-side remote procedure call interface.
  34  */
  35
  36 /*
  37  * This interface must manage two items concerning remote procedure calling:
  38  *
  39  * 1) An arbitrary number of transport connections upon which rpc requests
  40  * are received.  The two most notable transports are TCP and UDP;  they are
  41  * created and registered by routines in svc_tcp.c and svc_udp.c, respectively;
  42  * they in turn call xprt_register and xprt_unregister.
  43  *
  44  * 2) An arbitrary number of locally registered services.  Services are
  45  * described by the following four data: program number, version number,
  46  * "service dispatch" function, a transport handle, and a boolean that
  47  * indicates whether or not the exported program should be registered with a
  48  * local binder service;  if true the program's number and version and the
  49  * port number from the transport handle are registered with the binder.
  50  * These data are registered with the rpc svc system via svc_register.
  51  *
  52  * A service's dispatch function is called whenever an rpc request comes in
  53  * on a transport.  The request's program and version numbers must match
  54  * those of the registered service.  The dispatch function is passed two
  55  * parameters, struct svc_req * and SVCXPRT *, defined below.
  56  */
  57
  58 enum xprt_stat {
  59         XPRT_DIED,
  60         XPRT_MOREREQS,
  61         XPRT_IDLE
  62 };
  63
  64 /*
  65  * Server side transport handle
  66  */
  67 typedef struct {
  68         int             xp_sock;
  69         u_short         xp_port;         /* associated port number */
  70         struct xp_ops {
  71             bool_t      (*xp_recv)();    /* receive incomming requests */
  72             enum xprt_stat (*xp_stat)(); /* get transport status */
  73             bool_t      (*xp_getargs)(); /* get arguments */
  74             bool_t      (*xp_reply)();   /* send reply */
  75             bool_t      (*xp_freeargs)(); /* free mem allocated for args */
  76             void        (*xp_destroy)(); /* destroy this struct */
  77         } *xp_ops;
  78         int             xp_addrlen;      /* length of remote address */
  79         struct sockaddr_in xp_raddr;     /* remote address */
  80         struct opaque_auth xp_verf;      /* raw response verifier */
  81         caddr_t         xp_p1;           /* private: for use by svc ops */
  82         caddr_t         xp_p2;           /* private: for use by svc ops */
  83         caddr_t         xp_p3;           /* private: for use by svc lib */
  84 } SVCXPRT;
  85
  86 /*
  87  *  Approved way of getting address of caller
  88  */
  89 #define svc_getcaller(x) (&(x)->xp_raddr)
  90
  91 /*
  92  * Operations defined on an SVCXPRT handle
  93  *
  94  * SVCXPRT              *xprt;
  95  * struct rpc_msg       *msg;
  96  * xdrproc_t             xargs;
  97  * caddr_t               argsp;
  98  */
  99 #define SVC_RECV(xprt, msg)                             \
 100         (*(xprt)->xp_ops->xp_recv)((xprt), (msg))
 101 #define svc_recv(xprt, msg)                             \
 102         (*(xprt)->xp_ops->xp_recv)((xprt), (msg))
 103
 104 #define SVC_STAT(xprt)                                  \
 105         (*(xprt)->xp_ops->xp_stat)(xprt)
 106 #define svc_stat(xprt)                                  \
 107         (*(xprt)->xp_ops->xp_stat)(xprt)
 108
 109 #define SVC_GETARGS(xprt, xargs, argsp)                 \
 110         (*(xprt)->xp_ops->xp_getargs)((xprt), (xargs), (argsp))
 111 #define svc_getargs(xprt, xargs, argsp)                 \
 112         (*(xprt)->xp_ops->xp_getargs)((xprt), (xargs), (argsp))
 113
 114 #define SVC_REPLY(xprt, msg)                            \
 115         (*(xprt)->xp_ops->xp_reply) ((xprt), (msg))
 116 #define svc_reply(xprt, msg)                            \
 117         (*(xprt)->xp_ops->xp_reply) ((xprt), (msg))
 118
 119 #define SVC_FREEARGS(xprt, xargs, argsp)                \
 120         (*(xprt)->xp_ops->xp_freeargs)((xprt), (xargs), (argsp))
 121 #define svc_freeargs(xprt, xargs, argsp)                \
 122         (*(xprt)->xp_ops->xp_freeargs)((xprt), (xargs), (argsp))
 123
 124 #define SVC_DESTROY(xprt)                               \
 125         (*(xprt)->xp_ops->xp_destroy)(xprt)
 126 #define svc_destroy(xprt)                               \
 127         (*(xprt)->xp_ops->xp_destroy)(xprt)
 128
 129
 130 /*
 131  * Service request
 132  */
 133 struct svc_req {
 134         u_long          rq_prog;        /* service program number */
 135         u_long          rq_vers;        /* service protocol version */
 136         u_long          rq_proc;        /* the desired procedure */
 137         struct opaque_auth rq_cred;     /* raw creds from the wire */
 138         caddr_t         rq_clntcred;    /* read only cooked cred */
 139         SVCXPRT *rq_xprt;               /* associated transport */
 140 };
 141
 142
 143 /*
 144  * Service registration
 145  *
 146  * svc_register(xprt, prog, vers, dispatch, protocol)
 147  *      SVCXPRT *xprt;
 148  *      u_long prog;
 149  *      u_long vers;
 150  *      void (*dispatch)();
 151  *      int protocol;   like TCP or UDP, zero means do not register
 152  */
 153 extern bool_t   svc_register();
 154
 155 /*
 156  * Service un-registration
 157  *
 158  * svc_unregister(prog, vers)
 159  *      u_long prog;
 160  *      u_long vers;
 161  */
 162 extern void     svc_unregister();
 163
 164 /*
 165  * Transport registration.
 166  *
 167  * xprt_register(xprt)
 168  *      SVCXPRT *xprt;
 169  */
 170 extern void     xprt_register();
 171
 172 /*
 173  * Transport un-register
 174  *
 175  * xprt_unregister(xprt)
 176  *      SVCXPRT *xprt;
 177  */
 178 extern 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
 209 extern bool_t   svc_sendreply();
 210 extern void     svcerr_decode();
 211 extern void     svcerr_weakauth();
 212 extern void     svcerr_noproc();
 213 extern void     svcerr_progvers();
 214 extern void     svcerr_auth();
 215 extern void     svcerr_noprog();
 216 extern 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  */
 233 extern 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  */
 240 extern void rpctest_service();
 241
 242 extern void     svc_getreq();
 243 extern void     svc_getreqset();        /* takes fdset instead of int */
 244 extern 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  */
 258 extern SVCXPRT *svcraw_create();
 259
 260 /*
 261  * Udp based rpc.
 262  */
 263 extern SVCXPRT *svcudp_create();
 264 extern SVCXPRT *svcudp_bufcreate();
 265
 266 /*
 267  * Tcp based rpc.
 268  */
 269 extern SVCXPRT *svctcp_create();
 270
 271 /*
 272  * Like svtcp_create(), except the routine takes any *open* UNIX file
 273  * descriptor as its first input.
 274  */
 275 SVCXPRT *svcfd_create();
 276 #else
 277
 278 /*
 279  * Kernel udp based rpc.
 280  */
 281 extern SVCXPRT *svckudp_create();
 282
 283
 284 #endif /* !_rpc_svc_h */