Back to index

glibc  2.9
svc.h
Go to the documentation of this file.
00001 /*
00002  * Sun RPC is a product of Sun Microsystems, Inc. and is provided for
00003  * unrestricted use provided that this legend is included on all tape
00004  * media and as a part of the software program in whole or part.  Users
00005  * may copy or modify Sun RPC without charge, but are not authorized
00006  * to license or distribute it to anyone else except as part of a product or
00007  * program developed by the user.
00008  *
00009  * SUN RPC IS PROVIDED AS IS WITH NO WARRANTIES OF ANY KIND INCLUDING THE
00010  * WARRANTIES OF DESIGN, MERCHANTIBILITY AND FITNESS FOR A PARTICULAR
00011  * PURPOSE, OR ARISING FROM A COURSE OF DEALING, USAGE OR TRADE PRACTICE.
00012  *
00013  * Sun RPC is provided with no support and without any obligation on the
00014  * part of Sun Microsystems, Inc. to assist in its use, correction,
00015  * modification or enhancement.
00016  *
00017  * SUN MICROSYSTEMS, INC. SHALL HAVE NO LIABILITY WITH RESPECT TO THE
00018  * INFRINGEMENT OF COPYRIGHTS, TRADE SECRETS OR ANY PATENTS BY SUN RPC
00019  * OR ANY PART THEREOF.
00020  *
00021  * In no event will Sun Microsystems, Inc. be liable for any lost revenue
00022  * or profits or other special, indirect and consequential damages, even if
00023  * Sun has been advised of the possibility of such damages.
00024  *
00025  * Sun Microsystems, Inc.
00026  * 2550 Garcia Avenue
00027  * Mountain View, California  94043
00028  */
00029 
00030 /*
00031  * svc.h, Server-side remote procedure call interface.
00032  *
00033  * Copyright (C) 1984, Sun Microsystems, Inc.
00034  */
00035 
00036 #ifndef _RPC_SVC_H
00037 #define _RPC_SVC_H 1
00038 
00039 #include <features.h>
00040 #include <rpc/rpc_msg.h>
00041 
00042 __BEGIN_DECLS
00043 
00044 /*
00045  * This interface must manage two items concerning remote procedure calling:
00046  *
00047  * 1) An arbitrary number of transport connections upon which rpc requests
00048  * are received.  The two most notable transports are TCP and UDP;  they are
00049  * created and registered by routines in svc_tcp.c and svc_udp.c, respectively;
00050  * they in turn call xprt_register and xprt_unregister.
00051  *
00052  * 2) An arbitrary number of locally registered services.  Services are
00053  * described by the following four data: program number, version number,
00054  * "service dispatch" function, a transport handle, and a boolean that
00055  * indicates whether or not the exported program should be registered with a
00056  * local binder service;  if true the program's number and version and the
00057  * port number from the transport handle are registered with the binder.
00058  * These data are registered with the rpc svc system via svc_register.
00059  *
00060  * A service's dispatch function is called whenever an rpc request comes in
00061  * on a transport.  The request's program and version numbers must match
00062  * those of the registered service.  The dispatch function is passed two
00063  * parameters, struct svc_req * and SVCXPRT *, defined below.
00064  */
00065 
00066 enum xprt_stat {
00067        XPRT_DIED,
00068        XPRT_MOREREQS,
00069        XPRT_IDLE
00070 };
00071 
00072 /*
00073  * Server side transport handle
00074  */
00075 typedef struct SVCXPRT SVCXPRT;
00076 struct SVCXPRT {
00077   int xp_sock;
00078   u_short xp_port;          /* associated port number */
00079   const struct xp_ops {
00080     bool_t    (*xp_recv) (SVCXPRT *__xprt, struct rpc_msg *__msg);
00081                             /* receive incoming requests */
00082     enum xprt_stat (*xp_stat) (SVCXPRT *__xprt);
00083                             /* get transport status */
00084     bool_t    (*xp_getargs) (SVCXPRT *__xprt, xdrproc_t __xdr_args,
00085                             caddr_t args_ptr); /* get arguments */
00086     bool_t    (*xp_reply) (SVCXPRT *__xprt, struct rpc_msg *__msg);
00087                             /* send reply */
00088     bool_t    (*xp_freeargs) (SVCXPRT *__xprt, xdrproc_t __xdr_args,
00089                             caddr_t args_ptr);
00090                             /* free mem allocated for args */
00091     void      (*xp_destroy) (SVCXPRT *__xprt);
00092                             /* destroy this struct */
00093   } *xp_ops;
00094   int         xp_addrlen;    /* length of remote address */
00095   struct sockaddr_in xp_raddr;      /* remote address */
00096   struct opaque_auth xp_verf;       /* raw response verifier */
00097   caddr_t            xp_p1;         /* private */
00098   caddr_t            xp_p2;         /* private */
00099   char        xp_pad [256]; /* padding, internal use */
00100 };
00101 
00102 /*
00103  *  Approved way of getting address of caller
00104  */
00105 #define svc_getcaller(x) (&(x)->xp_raddr)
00106 
00107 /*
00108  * Operations defined on an SVCXPRT handle
00109  *
00110  * SVCXPRT           *xprt;
00111  * struct rpc_msg    *msg;
00112  * xdrproc_t          xargs;
00113  * caddr_t            argsp;
00114  */
00115 #define SVC_RECV(xprt, msg)                      \
00116        (*(xprt)->xp_ops->xp_recv)((xprt), (msg))
00117 #define svc_recv(xprt, msg)                      \
00118        (*(xprt)->xp_ops->xp_recv)((xprt), (msg))
00119 
00120 #define SVC_STAT(xprt)                                  \
00121        (*(xprt)->xp_ops->xp_stat)(xprt)
00122 #define svc_stat(xprt)                                  \
00123        (*(xprt)->xp_ops->xp_stat)(xprt)
00124 
00125 #define SVC_GETARGS(xprt, xargs, argsp)                 \
00126        (*(xprt)->xp_ops->xp_getargs)((xprt), (xargs), (argsp))
00127 #define svc_getargs(xprt, xargs, argsp)                 \
00128        (*(xprt)->xp_ops->xp_getargs)((xprt), (xargs), (argsp))
00129 
00130 #define SVC_REPLY(xprt, msg)                            \
00131        (*(xprt)->xp_ops->xp_reply) ((xprt), (msg))
00132 #define svc_reply(xprt, msg)                            \
00133        (*(xprt)->xp_ops->xp_reply) ((xprt), (msg))
00134 
00135 #define SVC_FREEARGS(xprt, xargs, argsp)         \
00136        (*(xprt)->xp_ops->xp_freeargs)((xprt), (xargs), (argsp))
00137 #define svc_freeargs(xprt, xargs, argsp)         \
00138        (*(xprt)->xp_ops->xp_freeargs)((xprt), (xargs), (argsp))
00139 
00140 #define SVC_DESTROY(xprt)                        \
00141        (*(xprt)->xp_ops->xp_destroy)(xprt)
00142 #define svc_destroy(xprt)                        \
00143        (*(xprt)->xp_ops->xp_destroy)(xprt)
00144 
00145 
00146 /*
00147  * Service request
00148  */
00149 struct svc_req {
00150   rpcprog_t rq_prog;            /* service program number */
00151   rpcvers_t rq_vers;            /* service protocol version */
00152   rpcproc_t rq_proc;            /* the desired procedure */
00153   struct opaque_auth rq_cred;   /* raw creds from the wire */
00154   caddr_t rq_clntcred;          /* read only cooked cred */
00155   SVCXPRT *rq_xprt;             /* associated transport */
00156 };
00157 
00158 #ifndef __DISPATCH_FN_T
00159 #define __DISPATCH_FN_T
00160 typedef void (*__dispatch_fn_t) (struct svc_req*, SVCXPRT*);
00161 #endif
00162 
00163 /*
00164  * Service registration
00165  *
00166  * svc_register(xprt, prog, vers, dispatch, protocol)
00167  *     SVCXPRT *xprt;
00168  *     rpcprog_t prog;
00169  *     rpcvers_t vers;
00170  *     void (*dispatch)(struct svc_req*, SVCXPRT*);
00171  *     rpcprot_t protocol;  like TCP or UDP, zero means do not register
00172  */
00173 extern bool_t svc_register (SVCXPRT *__xprt, rpcprog_t __prog,
00174                          rpcvers_t __vers, __dispatch_fn_t __dispatch,
00175                          rpcprot_t __protocol) __THROW;
00176 
00177 /*
00178  * Service un-registration
00179  *
00180  * svc_unregister(prog, vers)
00181  *     rpcprog_t prog;
00182  *     rpcvers_t vers;
00183  */
00184 extern void svc_unregister (rpcprog_t __prog, rpcvers_t __vers) __THROW;
00185 
00186 /*
00187  * Transport registration.
00188  *
00189  * xprt_register(xprt)
00190  *     SVCXPRT *xprt;
00191  */
00192 extern void xprt_register (SVCXPRT *__xprt) __THROW;
00193 
00194 /*
00195  * Transport un-register
00196  *
00197  * xprt_unregister(xprt)
00198  *     SVCXPRT *xprt;
00199  */
00200 extern void xprt_unregister (SVCXPRT *__xprt) __THROW;
00201 
00202 
00203 /*
00204  * When the service routine is called, it must first check to see if it
00205  * knows about the procedure;  if not, it should call svcerr_noproc
00206  * and return.  If so, it should deserialize its arguments via
00207  * SVC_GETARGS (defined above).  If the deserialization does not work,
00208  * svcerr_decode should be called followed by a return.  Successful
00209  * decoding of the arguments should be followed the execution of the
00210  * procedure's code and a call to svc_sendreply.
00211  *
00212  * Also, if the service refuses to execute the procedure due to too-
00213  * weak authentication parameters, svcerr_weakauth should be called.
00214  * Note: do not confuse access-control failure with weak authentication!
00215  *
00216  * NB: In pure implementations of rpc, the caller always waits for a reply
00217  * msg.  This message is sent when svc_sendreply is called.
00218  * Therefore pure service implementations should always call
00219  * svc_sendreply even if the function logically returns void;  use
00220  * xdr.h - xdr_void for the xdr routine.  HOWEVER, tcp based rpc allows
00221  * for the abuse of pure rpc via batched calling or pipelining.  In the
00222  * case of a batched call, svc_sendreply should NOT be called since
00223  * this would send a return message, which is what batching tries to avoid.
00224  * It is the service/protocol writer's responsibility to know which calls are
00225  * batched and which are not.  Warning: responding to batch calls may
00226  * deadlock the caller and server processes!
00227  */
00228 
00229 extern bool_t svc_sendreply (SVCXPRT *xprt, xdrproc_t __xdr_results,
00230                             caddr_t __xdr_location) __THROW;
00231 
00232 extern void   svcerr_decode (SVCXPRT *__xprt) __THROW;
00233 
00234 extern void   svcerr_weakauth (SVCXPRT *__xprt) __THROW;
00235 
00236 extern void   svcerr_noproc (SVCXPRT *__xprt) __THROW;
00237 
00238 extern void   svcerr_progvers (SVCXPRT *__xprt, rpcvers_t __low_vers,
00239                              rpcvers_t __high_vers) __THROW;
00240 
00241 extern void   svcerr_auth (SVCXPRT *__xprt, enum auth_stat __why) __THROW;
00242 
00243 extern void   svcerr_noprog (SVCXPRT *__xprt) __THROW;
00244 
00245 extern void   svcerr_systemerr (SVCXPRT *__xprt) __THROW;
00246 
00247 /*
00248  * Lowest level dispatching -OR- who owns this process anyway.
00249  * Somebody has to wait for incoming requests and then call the correct
00250  * service routine.  The routine svc_run does infinite waiting; i.e.,
00251  * svc_run never returns.
00252  * Since another (coexistent) package may wish to selectively wait for
00253  * incoming calls or other events outside of the rpc architecture, the
00254  * routine svc_getreq is provided.  It must be passed readfds, the
00255  * "in-place" results of a select system call (see select, section 2).
00256  */
00257 
00258 /*
00259  * Global keeper of rpc service descriptors in use
00260  * dynamic; must be inspected before each call to select
00261  */
00262 
00263 extern struct pollfd *svc_pollfd;
00264 extern int svc_max_pollfd;
00265 extern fd_set svc_fdset;
00266 #define svc_fds svc_fdset.fds_bits[0]     /* compatibility */
00267 
00268 /*
00269  * a small program implemented by the svc_rpc implementation itself;
00270  * also see clnt.h for protocol numbers.
00271  */
00272 extern void svc_getreq (int __rdfds) __THROW;
00273 extern void svc_getreq_common (const int __fd) __THROW;
00274 extern void svc_getreqset (fd_set *__readfds) __THROW;
00275 extern void svc_getreq_poll (struct pollfd *, const int) __THROW;
00276 extern void svc_exit (void) __THROW;
00277 extern void svc_run (void) __THROW;
00278 
00279 /*
00280  * Socket to use on svcxxx_create call to get default socket
00281  */
00282 #define       RPC_ANYSOCK   -1
00283 
00284 /*
00285  * These are the existing service side transport implementations
00286  */
00287 
00288 /*
00289  * Memory based rpc for testing and timing.
00290  */
00291 extern SVCXPRT *svcraw_create (void) __THROW;
00292 
00293 /*
00294  * Udp based rpc.
00295  */
00296 extern SVCXPRT *svcudp_create (int __sock) __THROW;
00297 extern SVCXPRT *svcudp_bufcreate (int __sock, u_int __sendsz, u_int __recvsz)
00298      __THROW;
00299 
00300 /*
00301  * Tcp based rpc.
00302  */
00303 extern SVCXPRT *svctcp_create (int __sock, u_int __sendsize, u_int __recvsize)
00304      __THROW;
00305 
00306 /*
00307  * FD based rpc.
00308  */
00309 extern SVCXPRT *svcfd_create (int __sock, u_int __sendsize, u_int __recvsize)
00310      __THROW;
00311 
00312 /*
00313  * Unix based rpc.
00314  */
00315 extern SVCXPRT *svcunix_create (int __sock, u_int __sendsize, u_int __recvsize,
00316                             char *__path) __THROW;
00317 
00318 
00319 __END_DECLS
00320 
00321 #endif /* rpc/svc.h */