• Main Page
  • Related Pages
  • Files
  • File List

rx-spec.h

00001 
00351  *      LWP_DispatchProcess(); 
00352  *      for     (;;) 
00353  *      {  
00354  *              /* Wait until there is something in the queue */
00355  *              while   (empty(q)) LWP_WaitProcess(q); 
00356  *              /* Process the newly-arrived queue entry */
00357  *              LWP_DispatchProcess(); 
00358  *      } 
00359  * } 
00360  * \endcode
00361  * 
00362  * \par
00363  * The next routine, write process(), sits in a loop, putting messages on the
00364  * shared queue and signalling the reader, which is waiting for activity on the
00365  * queue. Signalling a thread is accomplished via the LWP SignalProcess()
00366  * library routine. 
00367  * 
00368  * \code
00369  * static write_process() 
00370  * { ... 
00371  *      /* Loop, writing data to the shared queue.  */
00372  *      for     (mesg = messages; *mesg != 0; mesg++) 
00373  *      { 
00374  *              insert(q, *mesg); 
00375  *              LWP_SignalProcess(q); 
00376  *      } 
00377  * } 
00378  * \endcode
00379  * 
00380  * \par
00381  * finally, here is the main routine for this demo pseudocode. It starts by
00382  * calling the LWP initialization routine. Next, it creates some number of
00383  * reader threads with calls to LWP CreateProcess() in addition to the single
00384  * writer thread. When all threads terminate, they will signal the main routine
00385  * on the done variable. Once signalled, the main routine will reap all the
00386  * threads with the help of the LWP DestroyProcess() function. 
00387  * 
00388  * \code
00389  * main(argc, argv) 
00390  * int argc; 
00391  * char **argv; 
00392  * { 
00393  *      PROCESS *id;  /* Initial thread ID */
00394  *      /* Set up the LWP package, create the initial thread ID. */
00395  *      LWP_InitializeProcessSupport(0, &id); 
00396  *      /* Create a set of reader threads.  */
00397  *      for (i = 0; i < nreaders; i++) 
00398  *              LWP_CreateProcess(read_process, STACK_SIZE, 0, i, "Reader",
00399  *              &readers[i]); 
00400  * 
00401  *      /* Create a single writer thread.  */
00402  *      LWP_CreateProcess(write_process, STACK_SIZE, 1, 0, "Writer", &writer); 
00403  *      /* Wait for all the above threads to terminate.  */
00404  *      for (i = 0; i <= nreaders; i++) 
00405  *              LWP_WaitProcess(&done); 
00406  * 
00407  *      /* All threads are done. Destroy them all.  */
00408  *      for (i = nreaders-1; i >= 0; i--) 
00409  *              LWP_DestroyProcess(readers[i]); 
00410  * } 
00411  * \endcode
00412  * 
00413  *      \subsection sec2-2-2 Section 2.2.2: Locking 
00414  * \par
00415  * The LWP locking facility exports a number of routines and macros that allow
00416  * a C programmer using LWP threading to place read and write locks on shared
00417  * data structures.  This locking facility was also written with simplicity in
00418  * mind. 
00419  * \par
00420  * In order to invoke the locking mechanism, an object of type struct Lock must
00421  * be associated with the object. After being initialized with a call to
00422  * LockInit(), the lock object is used in invocations of various macros,
00423  * including ObtainReadLock(), ObtainWriteLock(), ReleaseReadLock(),
00424  * ReleaseWriteLock(), ObtainSharedLock(), ReleaseSharedLock(), and
00425  * BoostSharedLock(). 
00426  * \par
00427  * Lock semantics specify that any number of readers may hold a lock in the
00428  * absence of a writer. Only a single writer may acquire a lock at any given
00429  * time. The lock package guarantees fairness, legislating that each reader and
00430  * writer will eventually obtain a given lock. However, this fairness is only
00431  * guaranteed if the priorities of the competing processes are identical. Note
00432  * that ordering is not guaranteed by this package. 
00433  * \par
00434  * Shared locks are read locks that can be "boosted" into write locks. These
00435  * shared locks have an unusual locking matrix. Unboosted shared locks are
00436  * compatible with read locks, yet incompatible with write locks and other
00437  * shared locks. In essence, a thread holding a shared lock on an object has
00438  * effectively read-locked it, and has the option to promote it to a write lock
00439  * without allowing any other writer to enter the critical region during the
00440  * boost operation itself. 
00441  * \par
00442  * It is illegal for a process to request a particular lock more than once
00443  * without first releasing it. Failure to obey this restriction will cause
00444  * deadlock. This restriction is not enforced by the LWP code. 
00445  * \par
00446  * Here is a simple pseudocode fragment serving as an example of the available
00447  * locking operations. It defines a struct Vnode object, which contains a lock
00448  * object. The get vnode() routine will look up a struct Vnode object by name,
00449  * and then either read-lock or write-lock it. 
00450  * \par
00451  * As with the high-level LWP example above, the locking routines introduced
00452  * here will be fully defined later, in Section 2.3.2. 
00453  * 
00454  * \code
00455  * #include <afs/lock.h> 
00456  * 
00457  * struct Vnode { 
00458  *      ... 
00459  *      struct Lock lock;  Used to lock this vnode  
00460  * ... }; 
00461  * 
00462  * #define READ 0 
00463  * #define WRITE 1 
00464  * 
00465  * struct Vnode *get_vnode(name, how) char *name; 
00466  * int how; 
00467  * { 
00468  *      struct Vnode *v; 
00469  *      v = lookup(name); 
00470  *      if (how == READ) 
00471  *              ObtainReadLock(&v->lock); 
00472  *      else 
00473  *              ObtainWriteLock(&v->lock); 
00474  * } 
00475  * \endcode
00476  * 
00477  * 
00478  *      \subsection sec2-2-3 Section 2.2.3: IOMGR 
00479  * 
00480  * \par
00481  * The IOMGR facility associated with the LWP service allows threads to wait on
00482  * various unix events. The exported IOMGR Select() routine allows a thread to
00483  * wait on the same set of events as the unix select() call. The parameters to
00484  * these two routines are identical. IOMGR Select() puts the calling LWP to
00485  * sleep until no threads are active. At this point, the built-in IOMGR thread,
00486  * which runs at the lowest priority, wakes up and coalesces all of the select
00487  * requests together. It then performs a single select() and wakes up all
00488  * threads affected by the result. 
00489  * \par
00490  * The IOMGR Signal() routine allows an LWP to wait on the delivery of a unix
00491  * signal. The IOMGR thread installs a signal handler to catch all deliveries
00492  * of the unix signal. This signal handler posts information about the signal
00493  * delivery to a global data structure. The next time that the IOMGR thread
00494  * runs, it delivers the signal to any waiting LWP. 
00495  * \par
00496  * Here is a pseudocode example of the use of the IOMGR facility, providing the
00497  * blueprint for an implemention a thread-level socket listener. 
00498  * 
00499  * \code
00500  * void rpc_SocketListener() 
00501  * { 
00502  *      int ReadfdMask, WritefdMask, ExceptfdMask, rc; 
00503  *      struct timeval *tvp; 
00504  *      while(TRUE) 
00505  *      { ... 
00506  *              ExceptfdMask = ReadfdMask = (1 << rpc_RequestSocket); 
00507  *              WritefdMask = 0; 
00508  * 
00509  *              rc = IOMGR_Select(8*sizeof(int), &ReadfdMask, &WritefdMask,
00510  *              &ExceptfdMask, tvp); 
00511  * 
00512  *              switch(rc) 
00513  *              { 
00514  *                      case 0: /* Timeout */ continue; 
00515  *                      /* Main while loop */
00516  * 
00517  *                      case -1: /* Error */ 
00518  *                      SystemError("IOMGR_Select"); 
00519  *                      exit(-1); 
00520  * 
00521  *                      case 1: /* RPC packet arrived! */ ... 
00522  *                      process packet ... 
00523  *                      break; 
00524  * 
00525  *                      default: Should never occur 
00526  *              } 
00527  *      } 
00528  * } 
00529  * \endcode
00530  * 
00531  *      \subsection sec2-2-4 Section 2.2.4: Timer 
00532  * \par
00533  * The timer package exports a number of routines that assist in manipulating
00534  * lists of objects of type struct TM Elem. These struct TM Elem timers are
00535  * assigned a timeout value by the user and inserted in a package-maintained
00536  * list. The time remaining to each timer's timeout is kept up to date by the
00537  * package under user control. There are routines to remove a timer from its
00538  * list, to return an expired timer from a list, and to return the next timer
00539  * to expire. 
00540  * \par
00541  * A timer is commonly used by inserting a field of type struct TM Elem into a
00542  * structure. After setting the desired timeout value, the structure is
00543  * inserted into a list by means of its timer field. 
00544  * \par
00545  * Here is a simple pseudocode example of how the timer package may be used.
00546  * After calling the package initialization function, TM Init(), the pseudocode
00547  * spins in a loop. first, it updates all the timers via TM Rescan() calls.
00548  * Then, it pulls out the first expired timer object with TM GetExpired() (if
00549  * any), and processes it. 
00550  * 
00551  * \code
00552  * static struct TM_Elem *requests; 
00553  * ... 
00554  * TM_Init(&requests); /* Initialize timer list */ ... 
00555  * for (;;) { 
00556  *      TM_Rescan(requests);  /* Update the timers */
00557  *      expired = TM_GetExpired(requests); 
00558  *      if (expired == 0) 
00559  *      break; 
00560  *      . . . process expired element . . . 
00561  *      } 
00562  * \endcode
00563  * 
00564  *      \subsection sec2-2-5 Section 2.2.5: Fast Time 
00565  * 
00566  * \par
00567  * The fast time routines allows a caller to determine the current time of day
00568  * without incurring the expense of a kernel call. It works by mapping the page
00569  * of the kernel that holds the time-of-day variable and examining it directly.
00570  * Currently, this package only works on Suns. The routines may be called on
00571  * other architectures, but they will run more slowly. 
00572  * \par
00573  * The initialization routine for this package is fairly expensive, since it
00574  * does a lookup of a kernel symbol via nlist(). If the client application
00575  * program only runs for only a short time, it may wish to call FT Init() with
00576  * the notReally parameter set to TRUE in order to prevent the lookup from
00577  * taking place. This is useful if you are using another package that uses the
00578  * fast time facility. 
00579  * 
00580  *      \subsection sec2-2-6 Section 2.2.6: Preemption 
00581  * 
00582  * \par
00583  * The preemption package provides a mechanism by which control can pass
00584  * between lightweight processes without the need for explicit calls to LWP
00585  * DispatchProcess(). This effect is achieved by periodically interrupting the
00586  * normal flow of control to check if other (higher priority) procesess are
00587  * ready to run. 
00588  * \par
00589  * The package makes use of the BSD interval timer facilities, and so will
00590  * cause programs that make their own use of these facilities to malfunction.
00591  * In particular, use of alarm(3) or explicit handling of SIGALRM is
00592  * disallowed. Also, calls to sleep(3) may return prematurely. 
00593  * \par
00594  * Care should be taken that routines are re-entrant where necessary. In
00595  * particular, note that stdio(3) is not re-entrant in general, and hence
00596  * multiple threads performing I/O on the same fiLE structure may function
00597  * incorrectly. 
00598  * \par
00599  * An example pseudocode routine illustrating the use of this preemption
00600  * facility appears below. 
00601  * 
00602  * \code
00603  * #include <sys/time.h> 
00604  * #include "preempt.h" 
00605  *      ...  struct timeval tv; 
00606  *      LWP_InitializeProcessSupport( ... ); 
00607  *      tv.tv_sec = 10; 
00608  *      tv.tv_usec = 0; 
00609  *      PRE_InitPreempt(&tv); 
00610  *      PRE_PreemptMe(); ... 
00611  *      PRE_BeginCritical(); ... 
00612  *      PRE_EndCritical(); ... 
00613  *      PRE_EndPreempt(); 
00614  * \endcode
00615  * 
00616  *      \section sec2-3 Section 2.3: Interface Specifications 
00617  * 
00618  *      \subsection sec2-3-1 Section 2.3.1: LWP 
00619  * 
00620  * \par
00621  * This section covers the calling interfaces to the LWP package. Please note
00622  * that LWP macros (e.g., ActiveProcess) are also included here, rather than
00623  * being relegated to a different section. 
00624  * 
00625  *      \subsubsection sec2-3-1-1 Section 2.3.1.1: LWP_InitializeProcessSupport
00626  *      _ Initialize the LWP package 
00627  * 
00628  * \par
00629  * int LWP_InitializeProcessSupport(IN int priority; OUT PROCESS *pid) 
00630  * \par Description 
00631  * This function initializes the LWP package. In addition, it turns the current
00632  * thread of control into the initial process with the specified priority. The
00633  * process ID of this initial thread is returned in the pid parameter. This
00634  * routine must be called before any other routine in the LWP library. The
00635  * scheduler will NOT be invoked as a result of calling
00636  * LWP_InitializeProcessSupport(). 
00637  * \par Error Codes 
00638  * LWP EBADPRI The given priority is invalid, either negative or too large. 
00639  * 
00640  *       \subsubsection sec2-3-1-2 Section 2.3.1.2: LWP_TerminateProcessSupport
00641  *       _ End process support, perform cleanup 
00642  * 
00643  * \par
00644  * int LWP_TerminateProcessSupport() 
00645  * \par Description 
00646  * This routine terminates the LWP threading support and cleans up after it by
00647  * freeing any auxiliary storage used. This routine must be called from within
00648  * the process that invoked LWP InitializeProcessSupport(). After LWP
00649  * TerminateProcessSupport() has been called, it is acceptable to call LWP
00650  * InitializeProcessSupport() again in order to restart LWP process support. 
00651  * \par Error Codes 
00652  * ---Always succeeds, or performs an abort(). 
00653  * 
00654  *      \subsubsection sec2-3-1-3 Section 2.3.1.3: LWP_CreateProcess _ Create a
00655  *      new thread 
00656  * 
00657  * \par
00658  * int LWP_CreateProcess(IN int (*ep)(); IN int stacksize; IN int priority; IN
00659  * char *parm; IN char *name; OUT PROCESS *pid) 
00660  * \par Description 
00661  * This function is used to create a new lightweight process with a given
00662  * printable name. The ep argument identifies the function to be used as the
00663  * body of the thread. The argument to be passed to this function is contained
00664  * in parm. The new thread's stack size in bytes is specified in stacksize, and
00665  * its execution priority in priority. The pid parameter is used to return the
00666  * process ID of the new thread. 
00667  * \par
00668  * If the thread is successfully created, it will be marked as runnable. The
00669  * scheduler is called before the LWP CreateProcess() call completes, so the
00670  * new thread may indeed begin its execution before the completion. Note that
00671  * the new thread is guaranteed NOT to run before the call completes if the
00672  * specified priority is lower than the caller's. On the other hand, if the new
00673  * thread's priority is higher than the caller's, then it is guaranteed to run
00674  * before the creation call completes. 
00675  * \par Error Codes 
00676  * LWP EBADPRI The given priority is invalid, either negative or too large. 
00677  * \n LWP NOMEM Could not allocate memory to satisfy the creation request. 
00678  * 
00679  *      \subsubsection sec2-3-1-4 Section: 2.3.1.4: LWP_DestroyProcess _ Create
00680  *      a new thread 
00681  * 
00682  * \par
00683  * int LWP_DestroyProcess(IN PROCESS pid) 
00684  * \par Description 
00685  * This routine destroys the thread identified by pid. It will be terminated
00686  * immediately, and its internal storage will be reclaimed. A thread is allowed
00687  * to destroy itself. In this case, of course, it will only get to see the
00688  * return code if the operation fails. Note that a thread may also destroy
00689  * itself by returning from the parent C routine. 
00690  * \par
00691  * The scheduler is called by this operation, which may cause an arbitrary
00692  * number of threads to execute before the caller regains the processor. 
00693  * \par Error Codes 
00694  * LWP EINIT The LWP package has not been initialized. 
00695  * 
00696  *      \subsubsection sec2-3-1-5 Section 2.3.1.5: WaitProcess _ Wait on an
00697  *      event 
00698  * 
00699  * \par
00700  * int LWP WaitProcess(IN char *event) 
00701  * \par Description 
00702  * This routine puts the thread making the call to sleep until another LWP
00703  * calls the LWP SignalProcess() or LWP NoYieldSignal() routine with the
00704  * specified event. Note that signalled events are not queued. If a signal
00705  * occurs and no thread is awakened, the signal is lost. The scheduler is
00706  * invoked by the LWP WaitProcess() routine. 
00707  * \par Error Codes 
00708  * LWP EINIT The LWP package has not been initialized. 
00709  * \n LWP EBADEVENT The given event pointer is null. 
00710  * 
00711  *      \subsubsection sec2-3-1-6 Section 2.3.1.6: MwaitProcess _ Wait on a set
00712  *      of events 
00713  * 
00714  * \par
00715  * int LWP MwaitProcess(IN int wcount; IN char *evlist[]) 
00716  * \par Description 
00717  * This function allows a thread to wait for wcount signals on any of the items
00718  * in the given evlist. Any number of signals of a particular event are only
00719  * counted once. The evlist is a null-terminated list of events to wait for.
00720  * The scheduler will be invoked. 
00721  * \par Error Codes 
00722  * LWP EINIT The LWP package has not been initialized. 
00723  * \n LWP EBADCOUNT An illegal number of events has been supplied. 
00724  * 
00725  *      \subsubsection sec2-3-1-7 Section 2.3.1.7: SignalProcess _ Signal an
00726  *      event 
00727  * 
00728  * \par
00729  * int LWP SignalProcess(IN char *event) 
00730  * \par Description 
00731  * This routine causes the given event to be signalled. All threads waiting for
00732  * this event (exclusively) will be marked as runnable, and the scheduler will
00733  * be invoked. Note that threads waiting on multiple events via LWP
00734  * MwaitProcess() may not be marked as runnable. Signals are not queued.
00735  * Therefore, if no thread is waiting for the signalled event, the signal will
00736  * be lost. 
00737  * \par Error Codes 
00738  * LWP EINIT The LWP package has not been initialized. LWP EBADEVENT A null
00739  * event pointer has been provided. LWP ENOWAIT No thread was waiting on the
00740  * given event. 
00741  * 
00742  *      \subsubsection sec2-3-1-8 Section 2.3.1.8: NoYieldSignal _ Signal an
00743  *      event without invoking scheduler 
00744  * 
00745  * \par
00746  * int LWP NoYieldSignal(IN char *event) 
00747  * \par Description 
00748  * This function is identical to LWP SignalProcess() except that the scheduler
00749  * will not be invoked. Thus, control will remain with the signalling process. 
00750  * \par Error Codes 
00751  * LWP EINIT The LWP package has not been initialized. LWP EBADEVENT A null
00752  * event pointer has been provided. LWP ENOWAIT No thread was waiting on the
00753  * given event. 
00754  * 
00755  *      \subsubsection sec2-3-1-9 Section 2.3.1.9: DispatchProcess _ Yield
00756  *      control to the scheduler 
00757  * 
00758  * \par
00759  * int LWP DispatchProcess() 
00760  * \par Description 
00761  * This routine causes the calling thread to yield voluntarily to the LWP
00762  * scheduler. If no other thread of appropriate priority is marked as runnable,
00763  * the caller will continue its execution. 
00764  * \par Error Codes 
00765  * LWP EINIT The LWP package has not been initialized. 
00766  * 
00767  *      \subsubsection sec2-3-1-10 Section 2.3.1.10: CurrentProcess _ Get the
00768  *      current thread's ID 
00769  * 
00770  * \par
00771  * int LWP CurrentProcess(IN PROCESS *pid) 
00772  * \par Description 
00773  * This call places the current lightweight process ID in the pid parameter. 
00774  * \par Error Codes 
00775  * LWP EINIT The LWP package has not been initialized. 
00776  * 
00777  *      \subsubsection sec2-3-1-11 Section 2.3.1.11: ActiveProcess _ Get the
00778  *      current thread's ID (macro) 
00779  * 
00780  * \par
00781  * int LWP ActiveProcess() 
00782  * \par Description 
00783  * This macro's value is the current lightweight process ID. It generates a
00784  * value identical to that acquired by calling the LWP CurrentProcess()
00785  * function described above if the LWP package has been initialized. If no such
00786  * initialization has been done, it will return a value of zero. 
00787  * 
00788  *      \subsubsection sec2-3-1-12 Section: 2.3.1.12: StackUsed _ Calculate
00789  *      stack usage 
00790  * 
00791  * \par
00792  * int LWP StackUsed(IN PROCESS pid; OUT int *max; OUT int *used) 
00793  * \par Description 
00794  * This function returns the amount of stack space allocated to the thread
00795  * whose identifier is pid, and the amount actually used so far. This is
00796  * possible if the global variable lwp stackUseEnabled was TRUE when the thread
00797  * was created (it is set this way by default). If so, the thread's stack area
00798  * was initialized with a special pattern. The memory still stamped with this
00799  * pattern can be determined, and thus the amount of stack used can be
00800  * calculated. The max parameter is always set to the thread's stack allocation
00801  * value, and used is set to the computed stack usage if lwp stackUseEnabled
00802  * was set when the process was created, or else zero. 
00803  * \par Error Codes 
00804  * LWP NO STACK Stack usage was not enabled at thread creation time. 
00805  * 
00806  *      \subsubsection sec2-3-1-13 Section 2.3.1.13: NewRock _ Establish
00807  *      thread-specific storage 
00808  * 
00809  * \par
00810  * int LWP NewRock (IN int tag; IN char **value)
00811  * \par Description
00812  * This function establishes a "rock", or thread-specific information,
00813  * associating it with the calling LWP. The tag is intended to be any unique
00814  * integer value, and the value is a pointer to a character array containing
00815  * the given data. 
00816  * \par
00817  * Users of the LWP package must coordinate their choice of tag values. Note
00818  * that a tag's value cannot be changed. Thus, to obtain a mutable data
00819  * structure, another level of indirection is required. Up to MAXROCKS (4)
00820  * rocks may be associated with any given thread. 
00821  * \par Error Codes
00822  * ENOROCKS A rock with the given tag field already exists. All of the MAXROCKS
00823  * are in use. 
00824  * 
00825  * 
00826  *      \subsubsection sec2-3-1-14 Section: 2.3.1.14: GetRock _ Retrieve
00827  *      thread-specific storage 
00828  * 
00829  * \par
00830  * int LWP GetRock(IN int tag; OUT **value) 
00831  * \par Description 
00832  * This routine recovers the thread-specific information associated with the
00833  * calling process and the given tag, if any. Such a rock had to be established
00834  * through a LWP NewRock() call. The rock's value is deposited into value. 
00835  * \par Error Codes 
00836  * LWP EBADROCK A rock has not been associated with the given tag for this
00837  * thread. 
00838  * 
00839  *      \subsection sec2-3-2 Section 2.3.2: Locking 
00840  * 
00841  * \par
00842  * This section covers the calling interfaces to the locking package. Many of
00843  * the user-callable routines are actually implemented as macros. 
00844  * 
00845  *      \subsubsection sec2-3-2-1 Section 2.3.2.1: Lock Init _ Initialize lock
00846  *      structure 
00847  * 
00848  * \par
00849  * void Lock Init(IN struct Lock *lock) 
00850  * \par Description 
00851  * This function must be called on the given lock object before any other
00852  * operations can be performed on it. 
00853  * \par Error Codes 
00854  * ---No value is returned. 
00855  * 
00856  *      \subsubsection sec2-3-2-2 Section 2.3.2.2: ObtainReadLock _ Acquire a
00857  *      read lock 
00858  * 
00859  * \par
00860  * void ObtainReadLock(IN struct Lock *lock) 
00861  * \par Description 
00862  * This macro obtains a read lock on the specified lock object. Since this is a
00863  * macro and not a function call, results are not predictable if the value of
00864  * the lock parameter is a side-effect producing expression, as it will be
00865  * evaluated multiple times in the course of the macro interpretation. 
00866  * Read locks are incompatible with write, shared, and boosted shared locks. 
00867  * \par Error Codes 
00868  * ---No value is returned. 
00869  * 
00870  *      \subsubsection sec2-3-2-3 Section 2.3.2.3: ObtainWriteLock _ Acquire a
00871  *      write lock 
00872  * 
00873  * \par
00874  * void ObtainWriteLock(IN struct Lock *lock) 
00875  * \par Description 
00876  * This macro obtains a write lock on the specified lock object. Since this is
00877  * a macro and not a function call, results are not predictable if the value of
00878  * the lock parameter is a side-effect producing expression, as it will be
00879  * evaluated multiple times in the course of the macro interpretation. 
00880  * \par
00881  * Write locks are incompatible with all other locks. 
00882  * \par Error Codes 
00883  * ---No value is returned. 
00884  * 
00885  *      \subsubsection sec2-3-2-4 Section 2.3.2.4: ObtainSharedLock _ Acquire a
00886  *      shared lock 
00887  * 
00888  * \par
00889  * void ObtainSharedLock(IN struct Lock *lock) 
00890  * \par Description 
00891  * This macro obtains a shared lock on the specified lock object. Since this is
00892  * a macro and not a function call, results are not predictable if the value of
00893  * the lock parameter is a side-effect producing expression, as it will be
00894  * evaluated multiple times in the course of the macro interpretation. 
00895  * \par
00896  * Shared locks are incompatible with write and boosted shared locks, but are
00897  * compatible with read locks. 
00898  * \par Error Codes 
00899  * ---No value is returned. 
00900  * 
00901  *      \subsubsection sec2-3-2-5 Section 2.3.2.5: ReleaseReadLock _ Release
00902  *      read lock 
00903  * 
00904  * \par
00905  * void ReleaseReadLock(IN struct Lock *lock) 
00906  * \par Description 
00907  * This macro releases the specified lock. The lock must have been previously
00908  * read-locked. Since this is a macro and not a function call, results are not
00909  * predictable if the value of the lock parameter is a side-effect producing
00910  * expression, as it will be evaluated multiple times in the course of the
00911  * macro interpretation. The results are also unpredictable if the lock was not
00912  * previously read-locked by the thread calling ReleaseReadLock(). 
00913  * \par Error Codes 
00914  * ---No value is returned. 
00915  * 
00916  *      \subsubsection sec2-3-2-6 Section 2.3.2.6: ReleaseWriteLock _ Release
00917  *      write lock 
00918  * 
00919  * \par
00920  * void ReleaseWriteLock(IN struct Lock *lock) 
00921  * \par Description 
00922  * This macro releases the specified lock. The lock must have been previously
00923  * write-locked. Since this is a macro and not a function call, results are not
00924  * predictable if the value of the lock parameter is a side-effect producing
00925  * expression, as it will be evaluated multiple times in the course of the
00926  * macro interpretation. The results are also unpredictable if the lock was not
00927  * previously write-locked by the thread calling ReleaseWriteLock(). 
00928  * \par Error Codes 
00929  * ---No value is returned. 
00930  * 
00931  *      \subsubsection sec2-3-2-7 Section 2.3.2.7: ReleaseSharedLock _ Release
00932  *      shared lock 
00933  * 
00934  * \par
00935  * void ReleaseSharedLock(IN struct Lock *lock) 
00936  * \par Description 
00937  * This macro releases the specified lock. The lock must have been previously
00938  * share-locked. Since this is a macro and not a function call, results are not
00939  * predictalbe if the value of the lock parameter is a side-effect producing
00940  * expression, as it will be evaluated multiple times in the course of the
00941  * macro interpretation. The results are also unpredictable if the lock was not
00942  * previously share-locked by the thread calling ReleaseSharedLock(). 
00943  * \par Error Codes 
00944  * ---No value is returned. 
00945  * 
00946  *      \subsubsection sec2-3-2-8 Section 2.3.2.8: CheckLock _ Determine state
00947  *      of a lock 
00948  * 
00949  * \par
00950  * void CheckLock(IN struct Lock *lock) 
00951  * \par Description 
00952  * This macro produces an integer that specifies the status of the indicated
00953  * lock. The value will be -1 if the lock is write-locked, 0 if unlocked, or
00954  * otherwise a positive integer that indicates the number of readers (threads
00955  * holding read locks). Since this is a macro and not a function call, results
00956  * are not predictable if the value of the lock parameter is a side-effect
00957  * producing expression, as it will be evaluated multiple times in the course
00958  * of the macro interpretation. 
00959  * \par Error Codes 
00960  * ---No value is returned. 
00961  * 
00962  *      \subsubsection sec2-3-2-9 Section 2.3.2.9: BoostLock _ Boost a shared
00963  *      lock 
00964  * 
00965  * \par
00966  * void BoostLock(IN struct Lock *lock) 
00967  * \par Description 
00968  * This macro promotes ("boosts") a shared lock into a write lock. Such a boost
00969  * operation guarantees that no other writer can get into the critical section
00970  * in the process. Since this is a macro and not a function call, results are
00971  * not predictable if the value of the lock parameter is a side-effect
00972  * producing expression, as it will be evaluated multiple times in the course
00973  * of the macro interpretation. 
00974  * \par Error Codes 
00975  * ---No value is returned. 
00976  * 
00977  *      \subsubsection sec2-3-2-10 Section 2.3.2.10: UnboostLock _ Unboost a
00978  *      shared lock 
00979  * 
00980  * \par
00981  * void UnboostLock(IN struct Lock *lock) 
00982  * \par Description 
00983  * This macro demotes a boosted shared lock back down into a regular shared
00984  * lock. Such an unboost operation guarantees that no other writer can get into
00985  * the critical section in the process. Since this is a macro and not a
00986  * function call, results are not predictable if the value of the lock
00987  * parameter is a side-effect producing expression, as it will be evaluated
00988  * multiple times in the course of the macro interpretation. 
00989  * \par Error Codes 
00990  * ---No value is returned. 
00991  * 
00992  *      \subsection sec2-3-3 Section 2.3.3: IOMGR 
00993  * 
00994  * \par
00995  * This section covers the calling interfaces to the I/O management package. 
00996  * 
00997  *      \subsubsection sec2-3-3-1 Section: 2.3.3.1: IOMGR Initialize _
00998  *      Initialize the package 
00999  * 
01000  * \par
01001  * int IOMGR Initialize() 
01002  * \par Description 
01003  * This function initializes the IOMGR package. Its main task is to create the
01004  * IOMGR thread itself, which runs at the lowest possible priority (0). The
01005  * remainder of the lightweight processes must be running at priority 1 or
01006  * greater (up to a maximum of LWP MAX PRIORITY (4)) for the IOMGR package to
01007  * function correctly. 
01008  * \par Error Codes 
01009  * -1 The LWP and/or timer package haven't been initialized. 
01010  * \n <misc> Any errors that may be returned by the LWP CreateProcess()
01011  * routine. 
01012  * 
01013  *      \subsubsection sec2-3-3-2 Section 2.3.3.2: IOMGR finalize _ Clean up
01014  *      the IOMGR facility 
01015  * 
01016  * \par
01017  * int IOMGR finalize() 
01018  * \par Description 
01019  * This routine cleans up after the IOMGR package when it is no longer needed.
01020  * It releases all storage and destroys the IOMGR thread itself. 
01021  * \par Error Codes 
01022  * <misc> Any errors that may be returned by the LWP DestroyProcess() routine. 
01023  * 
01024  *      \subsubsection sec2-3-3-3 Section 2.3.3.3: IOMGR Select _ Perform a
01025  *      thread-level select() 
01026  * 
01027  * \par
01028  * int IOMGR Select (IN int numfds; IN int *rfds; IN int *wfds; IN int *xfds;
01029  * IN truct timeval *timeout) 
01030  * \par Description 
01031  * This routine performs an LWP version of unix select() operation. The
01032  * parameters have the same meanings as with the unix call. However, the return
01033  * values will be simplified (see below). If this is a polling select (i.e.,
01034  * the value of timeout is null), it is done and the IOMGR Select() function
01035  * returns to the user with the results. Otherwise, the calling thread is put
01036  * to sleep. If at some point the IOMGR thread is the only runnable process, it
01037  * will awaken and collect all select requests. The IOMGR will then perform a
01038  * single select and awaken the appropriate processes. This will force a return
01039  * from the affected IOMGR Select() calls. 
01040  * \par Error Codes 
01041  * -1 An error occurred.
01042  * \n 0 A timeout occurred.
01043  * \n 1 Some number of file descriptors are ready. 
01044  * 
01045  *      \subsubsection sec2-3-3-4 Section 2.3.3.4: IOMGR Signal _ Associate
01046  *      unix and LWP signals 
01047  * 
01048  * \par
01049  * int IOMGR Signal(IN int signo; IN char *event) 
01050  * \par Description 
01051  * This function associates an LWP signal with a unix signal. After this call,
01052  * when the given unix signal signo is delivered to the (heavyweight unix)
01053  * process, the IOMGR thread will deliver an LWP signal to the event via LWP
01054  * NoYieldSignal(). This wakes up any lightweight processes waiting on the
01055  * event. Multiple deliveries of the signal may be coalesced into one LWP
01056  * wakeup. The call to LWP NoYieldSignal() will happen synchronously. It is
01057  * safe for an LWP to check for some condition and then go to sleep waiting for
01058  * a unix signal without having to worry about delivery of the signal happening
01059  * between the check and the call to LWP WaitProcess(). 
01060  * \par Error Codes 
01061  * LWP EBADSIG The signo value is out of range. 
01062  * \n LWP EBADEVENT The event pointer is null. 
01063  * 
01064  *      \subsubsection sec2-3-3-5 Section 2.3.3.5: IOMGR CancelSignal _ Cancel
01065  *      unix and LWP signal association 
01066  * 
01067  * \par
01068  * int IOMGR CancelSignal(IN int signo) 
01069  * \par Description 
01070  * This routine cancels the association between a unix signal and an LWP event.
01071  * After calling this function, the unix signal signo will be handled however
01072  * it was handled before the corresponding call to IOMGR Signal(). 
01073  * \par Error Codes 
01074  * LWP EBADSIG The signo value is out of range. 
01075  * 
01076  *      \subsubsection sec2-3-3-6 Section 2.3.3.6: IOMGR Sleep _ Sleep for a
01077  *      given period 
01078  * 
01079  * \par
01080  * void IOMGR Sleep(IN unsigned seconds) 
01081  * \par Description 
01082  * This function calls IOMGR Select() with zero file descriptors and a timeout
01083  * structure set up to cause the thread to sleep for the given number of
01084  * seconds. 
01085  * \par Error Codes 
01086  * ---No value is returned. 
01087  * 
01088  *      \subsection sec2-3-4 Section 2.3.4: Timer 
01089  * 
01090  * \par
01091  * This section covers the calling interface to the timer package associated
01092  * with the LWP facility. 
01093  * 
01094  *      \subsubsection sec2-3-4-1 Section 2.3.4.1: TM Init _ Initialize a timer
01095  *      list 
01096  * 
01097  * \par
01098  * int TM Init(IN struct TM Elem **list) 
01099  * \par Description 
01100  * This function causes the specified timer list to be initialized. TM Init()
01101  * must be called before any other timer operations are applied to the list. 
01102  * \par Error Codes 
01103  * -1 A null timer list could not be produced. 
01104  * 
01105  *      \subsubsection sec2-3-4-2 Section 2.3.4.2: TM final _ Clean up a timer
01106  *      list 
01107  * 
01108  * \par
01109  * int TM final(IN struct TM Elem **list) 
01110  * \par Description 
01111  * This routine is called when the given empty timer list is no longer needed.
01112  * All storage associated with the list is released. 
01113  * \par Error Codes 
01114  * -1 The list parameter is invalid. 
01115  * 
01116  *      \subsubsection sec2-3-4-3 Section 2.3.4.3: TM Insert _ Insert an object
01117  *      into a timer list
01118  * 
01119  * \par
01120  * void TM Insert(IN struct TM Elem **list; IN struct TM Elem *elem)
01121  * \par Description
01122  * This routine enters an new element, elem, into the list denoted by list.
01123  * Before the new element is queued, its TimeLeft field (the amount of time
01124  * before the object comes due) is set to the value stored in its TotalTime
01125  * field. In order to keep TimeLeft fields current, the TM Rescan() function
01126  * may be used. 
01127  * \par Error Codes 
01128  * ---No return value is generated. 
01129  * 
01130  *      \subsubsection sec2-3-4-4 Section 2.3.4.4: TM Rescan _ Update all
01131  *      timers in the list 
01132  * 
01133  * \par
01134  * int TM Rescan(IN struct TM Elem *list) 
01135  * \par Description 
01136  * This function updates the TimeLeft fields of all timers on the given list.
01137  * This is done by checking the time-of-day clock. Note: this is the only
01138  * routine other than TM Init() that updates the TimeLeft field in the elements
01139  * on the list. 
01140  * \par
01141  * Instead of returning a value indicating success or failure, TM Rescan()
01142  * returns the number of entries that were discovered to have timed out. 
01143  * \par Error Codes 
01144  * ---Instead of error codes, the number of entries that were discovered to
01145  *  have timed out is returned. 
01146  * 
01147  *      \subsubsection sec2-3-4-5 Section 2.3.4.5: TM GetExpired _ Returns an
01148  *      expired timer 
01149  * 
01150  * \par
01151  * struct TM Elem *TM GetExpired(IN struct TM Elem *list) 
01152  * \par Description 
01153  * This routine searches the specified timer list and returns a pointer to an
01154  * expired timer element from that list. An expired timer is one whose TimeLeft
01155  * field is less than or equal to zero. If there are no expired timers, a null
01156  * element pointer is returned. 
01157  * \par Error Codes 
01158  * ---Instead of error codes, an expired timer pointer is returned, or a null
01159  *  timer pointer if there are no expired timer objects. 
01160  * 
01161  *      \subsubsection sec2-3-4-6 Section 2.3.4.6: TM GetEarliest _ Returns
01162  *      earliest unexpired timer 
01163  * 
01164  * \par
01165  * struct TM Elem *TM GetEarliest(IN struct TM Elem *list) 
01166  * \par Description 
01167  * This function returns a pointer to the timer element that will be next to
01168  * expire on the given list. This is defined to be the timer element with the
01169  * smallest (positive) TimeLeft field. If there are no timers on the list, or
01170  * if they are all expired, this function will return a null pointer. 
01171  * \par Error Codes 
01172  * ---Instead of error codes, a pointer to the next timer element to expireis
01173  *  returned, or a null timer object pointer if they are all expired. 
01174  * 
01175  *      \subsubsection sec2-3-4-7 Section 2.3.4.7: TM eql _ Test for equality
01176  *      of two timestamps 
01177  * 
01178  * \par
01179  * bool TM eql(IN struct timemval *t1; IN struct timemval *t2) 
01180  * \par Description 
01181  * This function compares the given timestamps, t1 and t2, for equality. Note
01182  * that the function return value, bool, has been set via typedef to be
01183  * equivalent to unsigned char. 
01184  * \par Error Codes 
01185  * 0 If the two timestamps differ. 
01186  * \n 1 If the two timestamps are identical. 
01187  * 
01188  *      \subsection sec2-3-5 Section 2.3.5: Fast Time 
01189  * \par
01190  * This section covers the calling interface to the fast time package
01191  * associated with the LWP facility. 
01192  * 
01193  *      \subsubsection sec2-3-5-1 Section 2.3.5.1: FT Init _ Initialize the
01194  *      fast time package 
01195  * 
01196  * \par
01197  * int FT Init(IN int printErrors; IN int notReally) 
01198  * \par Description 
01199  * This routine initializes the fast time package, mapping in the kernel page
01200  * containing the time-of-day variable. The printErrors argument, if non-zero,
01201  * will cause any errors in initalization to be printed to stderr. The
01202  * notReally parameter specifies whether initialization is really to be done.
01203  * Other calls in this package will do auto-initialization, and hence the
01204  * option is offered here. 
01205  * \par Error Codes 
01206  * -1 Indicates that future calls to FT GetTimeOfDay() will still work, but
01207  *  will not be able to access the information directly, having to make a
01208  *  kernel call every time. 
01209  * 
01210  *      \subsubsection sec2-3-5-2 Section 2.3.5.2: FT GetTimeOfDay _ Initialize
01211  *      the fast time package 
01212  * 
01213  * \par
01214  * int FT GetTimeOfDay(IN struct timeval *tv; IN struct timezone *tz) 
01215  * \par Description 
01216  * This routine is meant to mimic the parameters and behavior of the unix
01217  * gettimeofday() function. However, as implemented, it simply calls
01218  * gettimeofday() and then does some bound-checking to make sure the value is
01219  * reasonable. 
01220  * \par Error Codes 
01221  * <misc> Whatever value was returned by gettimeofday() internally. 
01222  * 
01223  *      \subsection sec2-3-6 Section 2.3.6: Preemption 
01224  * \par
01225  * This section covers the calling interface to the preemption package
01226  * associated with the LWP facility. 
01227  * 
01228  *      \subsubsection sec2-3-6-1 Section 2.3.6.1: PRE InitPreempt _ Initialize
01229  *      the preemption package 
01230  * 
01231  * \par
01232  * int PRE InitPreempt(IN struct timeval *slice) 
01233  * \par Description 
01234  * This function must be called to initialize the preemption package. It must
01235  * appear sometime after the call to LWP InitializeProcessSupport() and
01236  * sometime before the first call to any other preemption routine. The slice
01237  * argument specifies the time slice size to use. If the slice pointer is set
01238  * to null in the call, then the default time slice, DEFAULTSLICE (10
01239  * milliseconds), will be used. This routine uses the unix interval timer and
01240  * handling of the unix alarm signal, SIGALRM, to implement this timeslicing. 
01241  * \par Error Codes 
01242  * LWP EINIT The LWP package hasn't been initialized. 
01243  * \n LWP ESYSTEM Operations on the signal vector or the interval timer have
01244  * failed. 
01245  * 
01246  *      \subsubsection sec2-3-6-2 Section 2.3.6.2: PRE EndPreempt _ finalize
01247  *      the preemption package 
01248  * 
01249  * \par
01250  * int PRE EndPreempt() 
01251  * \par Description 
01252  * This routine finalizes use of the preemption package. No further preemptions
01253  * will be made. Note that it is not necessary to make this call before exit.
01254  * PRE EndPreempt() is provided only for those applications that wish to
01255  * continue after turning off preemption. 
01256  * \par Error Codes 
01257  * LWP EINIT The LWP package hasn't been initialized. 
01258  * \n LWP ESYSTEM Operations on the signal vector or the interval timer have
01259  * failed. 
01260  * 
01261  *      \subsubsection sec2-3-6-3 Section 2.3.6.3: PRE PreemptMe _ Mark thread
01262  *      as preemptible 
01263  * 
01264  * \par
01265  * int PRE PreemptMe() 
01266  * \par Description 
01267  * This macro is used to signify the current thread as a candidate for
01268  * preemption. The LWP InitializeProcessSupport() routine must have been called
01269  * before PRE PreemptMe(). 
01270  * \par Error Codes 
01271  * ---No return code is generated. 
01272  * 
01273  *      \subsubsection sec2-3-6-4 Section 2.3.6.4: PRE BeginCritical _ Enter
01274  *      thread critical section 
01275  * 
01276  * \par
01277  * int PRE BeginCritical() 
01278  * \par Description 
01279  * This macro places the current thread in a critical section. Upon return, and
01280  * for as long as the thread is in the critical section, involuntary
01281  * preemptions of this LWP will no longer occur. 
01282  * \par Error Codes 
01283  * ---No return code is generated. 
01284  * 
01285  *      \subsubsection sec2-3-6-5 Section 2.3.6.5: PRE EndCritical _ Exit
01286  *      thread critical section 
01287  * 
01288  * \par
01289  * int PRE EndCritical() 
01290  * \par Description 
01291  * This macro causes the executing thread to leave a critical section
01292  * previously entered via PRE BeginCritical(). If involuntary preemptions were
01293  * possible before the matching PRE BeginCritical(), they are once again
01294  * possible. 
01295  * \par Error Codes 
01296  * ---No return code is generated. 
01297  * 
01298  *      \page chap3 Chapter 3 -- Rxkad 
01299  * 
01300  * 
01301  *      \section sec3-1 Section 3.1: Introduction 
01302  * 
01303  * \par
01304  * The rxkad security module is offered as one of the built-in Rx
01305  * authentication models. It is based on the Kerberos system developed by MIT's
01306  * Project Athena. Readers wishing detailed information regarding Kerberos
01307  * design and implementation are directed to [2]. This chapter is devoted to
01308  * defining how Kerberos authentication services are made available as Rx
01309  * components, and assumes the reader has some familiarity with Kerberos.
01310  * Included are descriptions of how client-side and server-side Rx security
01311  * objects (struct rx securityClass; see Section 5.3.1.1) implementing this
01312  * protocol may be generated by an Rx application. Also, a description appears
01313  * of the set of routines available in the associated struct rx securityOps
01314  * structures, as covered in Section 5.3.1.2. It is strongly recommended that
01315  * the reader become familiar with this section on struct rx securityOps before
01316  * reading on. 
01317  * 
01318  *      \section sec3-2 Section 3.2: Definitions 
01319  * 
01320  * \par
01321  * An important set of definitions related to the rxkad security package is
01322  * provided by the rxkad.h include file. Determined here are various values for
01323  * ticket lifetimes, along with structures for encryption keys and Kerberos
01324  * principals. Declarations for the two routines required to generate the
01325  * different rxkad security objects also appear here. The two functions are
01326  * named rxkad NewServerSecurityObject() and rxkad NewClientSecurityObject().
01327  * In addition, type field values, encryption levels, security index
01328  * operations, and statistics structures may be found in this file. 
01329  *      \section sec3-3 Section 3.3: Exported Objects 
01330  * \par
01331  * To be usable as an Rx security module, the rxkad facility exports routines
01332  * to create server-side and client-side security objects. The server
01333  * authentication object is incorporated into the server code when calling rx
01334  * NewService(). The client authentication object is incorporated into the
01335  * client code every time a connection is established via rx NewConnection().
01336  * Also, in order to implement these security objects, the rxkad module must
01337  * provide definitions for some subset of the generic security operations as
01338  * defined in the appropriate struct rx securityOps variable. 
01339  * 
01340  *      \subsection sec3-3-1 Section 3.3.1: Server-Side Mechanisms 
01341  * 
01342  *      \subsubsection sec3-3-1-1 Section 3.3.1.1: Security Operations 
01343  * 
01344  * \par
01345  * The server side of the rxkad module fills in all but two of the possible
01346  * routines associated with an Rx security object, as described in Section
01347  * 5.3.1.2. 
01348  * 
01349  * \code
01350  * static struct rx_securityOps rxkad_server_ops = { 
01351  *      rxkad_Close,
01352  *      rxkad_NewConnection,
01353  *      rxkad_PreparePacket, /* Once per packet creation */
01354  *      0, /* Send packet (once per retrans) */
01355  *      rxkad_CheckAuthentication,
01356  *      rxkad_CreateChallenge,
01357  *      rxkad_GetChallenge,
01358  *      0,
01359  *      rxkad_CheckResponse, /* Check data packet */
01360  *      rxkad_DestroyConnection,
01361  *      rxkad_GetStats,
01362  * };
01363  * \endcode
01364  * 
01365  * \par
01366  * The rxkad service does not need to take any special action each time a
01367  * packet belonging to a call in an rxkad Rx connection is physically
01368  * transmitted. Thus, a routine is not supplied for the op SendPacket()
01369  * function slot. Similarly, no preparatory work needs to be done previous to
01370  * the reception of a response packet from a security challenge, so the op
01371  * GetResponse() function slot is also empty. 
01372  * 
01373  *      \subsubsection sec3-3-1-2 Section 3.3.1.2: Security Object 
01374  * 
01375  * \par
01376  * The exported routine used to generate an rxkad-specific server-side security
01377  * class object is named rxdad NewServerSecurityObject(). It is declared with
01378  * four parameters, as follows: 
01379  * 
01380  * \code
01381  * struct rx_securityClass * 
01382  * rxkad_NewServerSecurityObject(a_level, a_getKeyRockP, a_getKeyP, a_userOKP) 
01383  * rxkad_level a_level; /* Minimum level */
01384  * char *a_getKeyRockP; /* Rock for get_key implementor */
01385  * int (*a_getKeyP)(); /* Passed kvno & addr(key) to fill */
01386  * int (*a_userOKP)(); /* Passed name, inst, cell => bool */
01387  * \endcode
01388  * 
01389  * \par
01390  * The first argument specifies the desired level of encryption, and may take
01391  * on the following values (as defined in rxkad.h): 
01392  * \li rxkad clear: Specifies that packets are to be sent entirely in the
01393  * clear, without any encryption whatsoever. 
01394  * \li rxkad auth: Specifies that packet sequence numbers are to be encrypted. 
01395  * \li rxkad crypt: Specifies that the entire data packet is to be encrypted. 
01396  * 
01397  * \par
01398  * The second and third parameters represent, respectively, a pointer to a
01399  * private data area, sometimes called a "rock", and a procedure reference that
01400  * is called with the key version number accompanying the Kerberos ticket and
01401  * returns a pointer to the server's decryption key. The fourth argument, if
01402  * not null, is a pointer to a function that will be called for every new
01403  * connection with the client's name, instance, and cell. This routine should
01404  * return zero if the user is not acceptable to the server. 
01405  * 
01406  *      \subsection sec3-3-2 Section 3.3.2: Client-Side Mechanisms 
01407  * 
01408  *      \subsubsection sec3-3-2-1 Section 3.3.2.1: Security Operations 
01409  * 
01410  * \par
01411  * The client side of the rxkad module fills in relatively few of the routines
01412  * associated with an Rx security object, as demonstrated below. The general Rx
01413  * security object, of which this is an instance, is described in detail in
01414  * Section 5.3.1.2. 
01415  * 
01416  * \code
01417  * static struct rx_securityOps rxkad_client_ops = { 
01418  *      rxkad_Close, 
01419  *      rxkad_NewConnection, /* Every new connection */
01420  *      rxkad_PreparePacket, /* Once per packet creation */
01421  *      0, /* Send packet (once per retrans) */
01422  *      0,
01423  *      0,
01424  *      0,
01425  *      rxkad_GetResponse, /* Respond to challenge packet */
01426  *      0,
01427  *      rxkad_CheckPacket, /* Check data packet */
01428  *      rxkad_DestroyConnection,
01429  *      rxkad_GetStats,
01430  *      0,
01431  *      0,
01432  *      0,
01433  * };
01434  * \endcode
01435  * 
01436  * \par
01437  * As expected, routines are defined for use when someone destroys a security
01438  * object (rxkad Close()) and when an Rx connection using the rxkad model
01439  * creates a new connection (rxkad NewConnection()) or deletes an existing one
01440  * (rxkad DestroyConnection()). Security-specific operations must also be
01441  * performed in behalf of rxkad when packets are created (rxkad
01442  * PreparePacket()) and received (rxkad CheckPacket()). finally, the client
01443  * side of an rxkad security object must also be capable of constructing
01444  * responses to security challenges from the server (rxkad GetResponse()) and
01445  * be willing to reveal statistics on its own operation (rxkad GetStats()). 
01446  * 
01447  *      \subsubsection sec3-3-2-2 Section 3.3.2.2: Security Object 
01448  * 
01449  * \par
01450  * The exported routine used to generate an rxkad-specific client-side security
01451  * class object is named rxkad NewClientSecurityObject(). It is declared with
01452  * five parameters, specified below: 
01453  * 
01454  * \code
01455  * struct rx_securityClass * rxkad_NewClientSecurityObject(
01456  *                              a_level, 
01457  *                              a_sessionKeyP, 
01458  *                              a_kvno, 
01459  *                              a_ticketLen, 
01460  *                              a_ticketP
01461  *                              ) 
01462  * rxkad_level a_level; 
01463  * struct ktc_encryptionKey *a_sessionKeyP; 
01464  * long a_kvno; 
01465  * int a_ticketLen; 
01466  * char *a_ticketP; 
01467  * \endcode
01468  * 
01469  * \par
01470  * The first parameter, a level, specifies the level of encryption desired for
01471  * this security object, with legal choices being identical to those defined
01472  * for the server-side security object described in Section 3.3.1.2. The second
01473  * parameter, a sessionKeyP, provides the session key to use. The ktc
01474  * encryptionKey structure is defined in the rxkad.h include file, and consists
01475  * of an array of 8 characters. The third parameter, a kvno, provides the key
01476  * version number associated with a sessionKeyP. The fourth argument, a
01477  * ticketLen, communicates the length in bytes of the data stored in the fifth
01478  * parameter, a ticketP, which points to the Kerberos ticket to use for the
01479  * principal for which the security object will operate. 
01480  * 
01481  *      \page chap4 Chapter 4 -- Rx Support Packages 
01482  * 
01483  *      \section sec4-1 Section 4.1: Introduction 
01484  * \par
01485  * This chapter documents three packages defined directly in support of the Rx
01486  * facility. 
01487  * \li rx queue: Doubly-linked queue package. 
01488  * \li rx clock: Clock package, using the 4.3BSD interval timer. 
01489  * \li rx event: Future events package. 
01490  * \par
01491  * References to constants, structures, and functions defined by these support
01492  * packages will appear in the following API chapter. 
01493  * 
01494  *      \section sec4-2 Section 4.2: The rx queue Package 
01495  * 
01496  * \par
01497  * This package provides a doubly-linked queue structure, along with a full
01498  * suite of related operations. The main concern behind the coding of this
01499  * facility was efficiency. All functions are implemented as macros, and it is
01500  * suggested that only simple expressions be used for all parameters. 
01501  * \par
01502  * The rx queue facility is defined by the rx queue.h include file. Some macros
01503  * visible in this file are intended for rx queue internal use only. An
01504  * understanding of these "hidden" macros is important, so they will also be
01505  * described by this document. 
01506  * 
01507  *      \subsection sec4-2-1 Section 4.2.1: struct queue 
01508  * 
01509  * \par
01510  * The queue structure provides the linkage information required to maintain a
01511  * queue of objects. The queue structure is prepended to any user-defined data
01512  * type which is to be organized in this fashion. 
01513  * \n \b fields 
01514  * \li struct queue *prev - Pointer to the previous queue header. 
01515  * \li struct queue *next - Pointer to the next queue header. 
01516  * \par
01517  * Note that a null Rx queue consists of a single struct queue object whose
01518  * next and previous pointers refer to itself. 
01519  * 
01520  *      \subsection sec4-2-2 Section 4.2.2: Internal Operations 
01521  * 
01522  * \par
01523  * This section describes the internal operations defined for Rx queues. They
01524  * will be referenced by the external operations documented in Section 4.2.3. 
01525  * 
01526  *      \subsection sec4-2-2-1 Section 4.2.2.1: Q(): Coerce type to a queue
01527  *      element 
01528  * 
01529  * \par
01530  * \#define _Q(x) ((struct queue *)(x)) 
01531  * \par
01532  * This operation coerces the user structure named by x to a queue element. Any
01533  * user structure using the rx queue package must have a struct queue as its
01534  * first field. 
01535  * 
01536  *      \subsubsection sec4-2-2-2 Section 4.2.2.2: QA(): Add a queue element
01537  *      before/after another element 
01538  * 
01539  * \par
01540  * \#define _QA(q,i,a,b) (((i->a=q->a)->b=i)->b=q, q->a=i) 
01541  * \par
01542  * This operation adds the queue element referenced by i either before or after
01543  * a queue element represented by q. If the (a, b) argument pair corresponds to
01544  * an element's (next, prev) fields, the new element at i will be linked after
01545  * q. If the (a, b) argument pair corresponds to an element's (prev, next)
01546  * fields, the new element at i will be linked before q. 
01547  * 
01548  *      \subsubsection sec4-2-2-3 QR(): Remove a queue element 
01549  * 
01550  * \par
01551  * \#define _QR(i) ((_Q(i)->prev->next=_Q(i)->next)->prev=_Q(i)->prev) 
01552  * \par
01553  * This operation removes the queue element referenced by i from its queue. The
01554  * prev and next fields within queue element i itself is not updated to reflect
01555  * the fact that it is no longer part of the queue. 
01556  * 
01557  *      \subsubsection sec4-2-2-4 QS(): Splice two queues together 
01558  * 
01559  * \par
01560  * \#define _QS(q1,q2,a,b) if (queue_IsEmpty(q2)); else
01561  * ((((q2->a->b=q1)->a->b=q2->b)->a=q1->a, q1->a=q2->a), queue_Init(q2)) 
01562  * \par
01563  * This operation takes the queues identified by q1 and q2 and splices them
01564  * together into a single queue. The order in which the two queues are appended
01565  * is determined by the a and b arguments. If the (a, b) argument pair
01566  * corresponds to q1's (next, prev) fields, then q2 is appended to q1. If the
01567  * (a, b) argument pair corresponds to q1's (prev, next) fields, then q is
01568  * prepended to q2. 
01569  * \par
01570  * This internal QS() routine uses two exported queue operations, namely queue
01571  * Init() and queue IsEmpty(), defined in Sections 4.2.3.1 and 4.2.3.16
01572  * respectively below. 
01573  * 
01574  *      \subsection sec4-2-3 Section 4.2.3: External Operations 
01575  * 
01576  *      \subsubsection sec4-2-3-1 Section 4.2.3.1: queue Init(): Initialize a
01577  *      queue header 
01578  * 
01579  * \par
01580  * \#define queue_Init(q) (_Q(q))->prev = (_Q(q))->next = (_Q(q)) 
01581  * \par
01582  * The queue header referred to by the q argument is initialized so that it
01583  * describes a null (empty) queue. A queue head is simply a queue element. 
01584  * 
01585  *      \subsubsection sec4-2-3-2 Section 4.2.3.2: queue Prepend(): Put element
01586  *      at the head of a queue 
01587  * 
01588  * \par
01589  * \#define queue_Prepend(q,i) _QA(_Q(q),_Q(i),next,prev) 
01590  * \par
01591  * Place queue element i at the head of the queue denoted by q. The new queue
01592  * element, i, should not currently be on any queue. 
01593  * 
01594  *      \subsubsection sec4-2-3-3 Section 4.2.3.3: queue Append(): Put an
01595  *      element a the tail of a queue 
01596  * 
01597  * \par
01598  * \#define queue_Append(q,i) _QA(_Q(q),_Q(i),prev,next) 
01599  * \par
01600  * Place queue element i at the tail of the queue denoted by q. The new queue
01601  * element, i, should not currently be on any queue. 
01602  * 
01603  *      \subsection sec4-2-3-4 Section 4.2.3.4: queue InsertBefore(): Insert a
01604  *      queue element before another element 
01605  * 
01606  * \par
01607  * \#define queue_InsertBefore(i1,i2) _QA(_Q(i1),_Q(i2),prev,next) 
01608  * \par
01609  * Insert queue element i2 before element i1 in i1's queue. The new queue
01610  * element, i2, should not currently be on any queue. 
01611  * 
01612  *      \subsubsection sec4-2-3-5 Section 4.2.3.5: queue InsertAfter(): Insert
01613  *      a queue element after another element 
01614  * 
01615  * \par
01616  * \#define queue_InsertAfter(i1,i2) _QA(_Q(i1),_Q(i2),next,prev) 
01617  * \par
01618  * Insert queue element i2 after element i1 in i1's queue. The new queue
01619  * element, i2, should not currently be on any queue. 
01620  * 
01621  *      \subsubsection sec4-2-3-6 Section: 4.2.3.6: queue SplicePrepend():
01622  *      Splice one queue before another 
01623  * 
01624  * \par
01625  * \#define queue_SplicePrepend(q1,q2) _QS(_Q(q1),_Q(q2),next,prev) 
01626  * \par
01627  * Splice the members of the queue located at q2 to the beginning of the queue
01628  * located at q1, reinitializing queue q2. 
01629  * 
01630  *      \subsubsection sec4-2-3-7 Section 4.2.3.7: queue SpliceAppend(): Splice
01631  *      one queue after another 
01632  * 
01633  * \par
01634  * \#define queue_SpliceAppend(q1,q2) _QS(_Q(q1),_Q(q2),prev,next) 
01635  * \par
01636  * Splice the members of the queue located at q2 to the end of the queue
01637  * located at q1, reinitializing queue q2. Note that the implementation of
01638  * queue SpliceAppend() is identical to that of queue SplicePrepend() except
01639  * for the order of the next and prev arguments to the internal queue splicer,
01640  * QS(). 
01641  * 
01642  *      \subsubsection sec4-2-3-8 Section 4.2.3.8: queue Replace(): Replace the
01643  *      contents of a queue with that of another 
01644  * 
01645  * \par
01646  * \#define queue_Replace(q1,q2) (*_Q(q1) = *_Q(q2), 
01647  * \n _Q(q1)->next->prev = _Q(q1)->prev->next = _Q(q1), 
01648  * \n queue_Init(q2)) 
01649  * \par
01650  * Replace the contents of the queue located at q1 with the contents of the
01651  * queue located at q2. The prev and next fields from q2 are copied into the
01652  * queue object referenced by q1, and the appropriate element pointers are
01653  * reassigned. After the replacement has occurred, the queue header at q2 is
01654  * reinitialized. 
01655  * 
01656  *      \subsubsection sec4-2-3-9 Section 4.2.3.9: queue Remove(): Remove an
01657  *      element from its queue 
01658  * 
01659  * \par
01660  * \#define queue_Remove(i) (_QR(i), _Q(i)->next = 0) 
01661  * \par
01662  * This function removes the queue element located at i from its queue. The
01663  * next field for the removed entry is zeroed. Note that multiple removals of
01664  * the same queue item are not supported. 
01665  * 
01666  *      \subsubsection sec4-2-3-10 Section 4.2.3.10: queue MoveAppend(): Move
01667  *      an element from its queue to the end of another queue 
01668  * 
01669  * \par
01670  * \#define queue_MoveAppend(q,i) (_QR(i), queue_Append(q,i)) 
01671  * \par
01672  * This macro removes the queue element located at i from its current queue.
01673  * Once removed, the element at i is appended to the end of the queue located
01674  * at q. 
01675  * 
01676  *      \subsubsection sec4-2-3-11 Section 4.2.3.11: queue MovePrepend(): Move
01677  *      an element from its queue to the head of another queue 
01678  * 
01679  * \par
01680  * \#define queue_MovePrepend(q,i) (_QR(i), queue_Prepend(q,i)) 
01681  * \par
01682  * This macro removes the queue element located at i from its current queue.
01683  * Once removed, the element at i is inserted at the head fo the queue located
01684  * at q. 
01685  * 
01686  *      \subsubsection sec4-2-3-12 Section 4.2.3.12: queue first(): Return the
01687  *      first element of a queue, coerced to a particular type 
01688  * 
01689  * \par
01690  * \#define queue_first(q,s) ((struct s *)_Q(q)->next) 
01691  * \par
01692  * Return a pointer to the first element of the queue located at q. The
01693  * returned pointer value is coerced to conform to the given s structure. Note
01694  * that a properly coerced pointer to the queue head is returned if q is empty. 
01695  * 
01696  *      \subsubsection sec4-2-3-13 Section 4.2.3.13: queue Last(): Return the
01697  *      last element of a queue, coerced to a particular type 
01698  * 
01699  * \par
01700  * \#define queue_Last(q,s) ((struct s *)_Q(q)->prev) 
01701  * \par
01702  * Return a pointer to the last element of the queue located at q. The returned
01703  * pointer value is coerced to conform to the given s structure. Note that a
01704  * properly coerced pointer to the queue head is returned if q is empty. 
01705  * 
01706  *      \subsubsection sec4-2-3-14 Section 4.2.3.14: queue Next(): Return the
01707  *      next element of a queue, coerced to a particular type 
01708  * 
01709  * \par
01710  * \#define queue_Next(i,s) ((struct s *)_Q(i)->next) 
01711  * \par
01712  * Return a pointer to the queue element occuring after the element located at
01713  * i. The returned pointer value is coerced to conform to the given s
01714  * structure. Note that a properly coerced pointer to the queue head is
01715  * returned if item i is the last in its queue. 
01716  * 
01717  *      \subsubsection sec4-2-3-15 Section 4.2.3.15: queue Prev(): Return the
01718  *      next element of a queue, coerced to a particular type 
01719  * 
01720  * \par
01721  * \#define queue_Prev(i,s) ((struct s *)_Q(i)->prev) 
01722  * \par
01723  * Return a pointer to the queue element occuring before the element located at
01724  * i. The returned pointer value is coerced to conform to the given s
01725  * structure. Note that a properly coerced pointer to the queue head is
01726  * returned if item i is the first in its queue. 
01727  * 
01728  *      \subsubsection sec4-2-3-16 Section 4.2.3.16: queue IsEmpty(): Is the
01729  *      given queue empty? 
01730  * 
01731  * \par
01732  * \#define queue_IsEmpty(q) (_Q(q)->next == _Q(q)) 
01733  * \par
01734  * Return a non-zero value if the queue located at q does not have any elements
01735  * in it. In this case, the queue consists solely of the queue header at q
01736  * whose next and prev fields reference itself. 
01737  * 
01738  *      \subsubsection sec4-2-3-17 Section 4.2.3.17: queue IsNotEmpty(): Is the
01739  *      given queue not empty? 
01740  * 
01741  * \par
01742  * \#define queue_IsNotEmpty(q) (_Q(q)->next != _Q(q)) 
01743  * \par
01744  * Return a non-zero value if the queue located at q has at least one element
01745  * in it other than the queue header itself. 
01746  * 
01747  *      \subsubsection sec4-2-3-18 Section 4.2.3.18: queue IsOnQueue(): Is an
01748  *      element currently queued? 
01749  * 
01750  * \par
01751  * \#define queue_IsOnQueue(i) (_Q(i)->next != 0) 
01752  * \par
01753  * This macro returns a non-zero value if the queue item located at i is
01754  * currently a member of a queue. This is determined by examining its next
01755  * field. If it is non-null, the element is considered to be queued. Note that
01756  * any element operated on by queue Remove() (Section 4.2.3.9) will have had
01757  * its next field zeroed. Hence, it would cause a non-zero return from this
01758  * call. 
01759  * 
01760  *      \subsubsection sec4-2-3-19 Section 4.2.3.19: queue Isfirst(): Is an
01761  *      element the first on a queue? 
01762  * 
01763  * \par
01764  * \#define queue_Isfirst(q,i) (_Q(q)->first == _Q(i)) 
01765  * \par
01766  * This macro returns a non-zero value if the queue item located at i is the
01767  * first element in the queue denoted by q. 
01768  * 
01769  *      \subsubsection sec4-2-3-20 Section 4.2.3.20: queue IsLast(): Is an
01770  *      element the last on a queue? 
01771  * 
01772  * \par
01773  * \#define queue_IsLast(q,i) (_Q(q)->prev == _Q(i)) 
01774  * \par
01775  * This macro returns a non-zero value if the queue item located at i is the
01776  * last element in the queue denoted by q. 
01777  * 
01778  *      \subsubsection sec4-2-3-21 Section 4.2.3.21: queue IsEnd(): Is an
01779  *      element the end of a queue? 
01780  * 
01781  * \par
01782  * \#define queue_IsEnd(q,i) (_Q(q) == _Q(i)) 
01783  * \par
01784  * This macro returns a non-zero value if the queue item located at i is the
01785  * end of the queue located at q. Basically, it determines whether a queue
01786  * element in question is also the queue header structure itself, and thus does
01787  * not represent an actual queue element. This function is useful for
01788  * terminating an iterative sweep through a queue, identifying when the search
01789  * has wrapped to the queue header. 
01790  * 
01791  *      \subsubsection sec4-2-3-22 Section 4.2.3.22: queue Scan(): for loop
01792  *      test for scanning a queue in a forward direction 
01793  * 
01794  * \par
01795  * \#define queue_Scan(q, qe, next, s) 
01796  * \n (qe) = queue_first(q, s), next = queue_Next(qe, s); 
01797  * \n !queue_IsEnd(q, qe); 
01798  * \n (qe) = (next), next = queue_Next(qe, s) 
01799  * \par
01800  * This macro may be used as the body of a for loop test intended to scan
01801  * through each element in the queue located at q. The qe argument is used as
01802  * the for loop variable. The next argument is used to store the next value for
01803  * qe in the upcoming loop iteration. The s argument provides the name of the
01804  * structure to which each queue element is to be coerced. Thus, the values
01805  * provided for the qe and next arguments must be of type (struct s *). 
01806  * \par
01807  * An example of how queue Scan() may be used appears in the code fragment
01808  * below. It declares a structure named mystruct, which is suitable for
01809  * queueing. This queueable structure is composed of the queue pointers
01810  * themselves followed by an integer value. The actual queue header is kept in
01811  * demoQueue, and the currItemP and nextItemP variables are used to step
01812  * through the demoQueue. The queue Scan() macro is used in the for loop to
01813  * generate references in currItemP to each queue element in turn for each
01814  * iteration. The loop is used to increment every queued structure's myval
01815  * field by one. 
01816  * 
01817  * \code
01818  * struct mystruct { 
01819  *      struct queue q; 
01820  *      int myval; 
01821  * }; 
01822  * struct queue demoQueue; 
01823  * struct mystruct *currItemP, *nextItemP; 
01824  * ... 
01825  * for (queue_Scan(&demoQueue, currItemP, nextItemP, mystruct)) { 
01826  *      currItemP->myval++; 
01827  * } 
01828  * \endcode
01829  * 
01830  * \par
01831  * Note that extra initializers can be added before the body of the queue
01832  * Scan() invocation above, and extra expressions can be added afterwards. 
01833  * 
01834  *      \subsubsection sec4-2-3-23 Section 4.2.3.23: queue ScanBackwards(): for
01835  *      loop test for scanning a queue in a reverse direction 
01836  * 
01837  * \par
01838  * #define queue_ScanBackwards(q, qe, prev, s) 
01839  * \n (qe) = queue_Last(q, s), prev = queue_Prev(qe, s); 
01840  * \n !queue_IsEnd(q, qe); 
01841  * \n (qe) = prev, prev = queue_Prev(qe, s) 
01842  * \par
01843  * This macro is identical to the queue Scan() macro described above in Section
01844  * 4.2.3.22 except for the fact that the given queue is scanned backwards,
01845  * starting at the last item in the queue. 
01846  * 
01847  *      \section sec4-3 Section 4.3: The rx clock Package 
01848  * 
01849  * \par
01850  * This package maintains a clock which is independent of the time of day. It
01851  * uses the unix 4.3BSD interval timer (e.g., getitimer(), setitimer()) in
01852  * TIMER REAL mode. Its definition and interface may be found in the rx clock.h
01853  * include file. 
01854  * 
01855  *      \subsection sec4-3-1 Section 4.3.1: struct clock 
01856  * 
01857  * \par
01858  * This structure is used to represent a clock value as understood by this
01859  * package. It consists of two fields, storing the number of seconds and
01860  * microseconds that have elapsed since the associated clock Init() routine has
01861  * been called. 
01862  * \par
01863  * \b fields 
01864  * \n long sec -Seconds since call to clock Init(). 
01865  * \n long usec -Microseconds since call to clock Init(). 
01866  * 
01867  *      \subsection sec4-3-2 Section 4.3.12: clock nUpdates 
01868  * 
01869  * \par
01870  * The integer-valued clock nUpdates is a variable exported by the rx clock
01871  * facility. It records the number of times the clock value is actually
01872  * updated. It is bumped each time the clock UpdateTime() routine is called, as
01873  * described in Section 4.3.3.2. 
01874  * 
01875  *      \subsection sec4-3-3 Section 4.3.3: Operations 
01876  * 
01877  *      \subsubsection sec4-3-3-1 Section 4.3.3.1: clock Init(): Initialize the
01878  *      clock package 
01879  * 
01880  * \par
01881  * This routine uses the unix setitimer() call to initialize the unix interval
01882  * timer. If the setitimer() call fails, an error message will appear on
01883  * stderr, and an exit(1) will be executed. 
01884  * 
01885  *      \subsubsection sec4-3-3-2 Section 4.3.3.2: clock UpdateTime(): Compute
01886  *      the current time 
01887  * 
01888  * \par
01889  * The clock UpdateTime() function calls the unix getitimer() routine in order
01890  * to update the current time. The exported clock nUpdates variable is
01891  * incremented each time the clock UpdateTime() routine is called. 
01892  * 
01893  *      \subsubsection sec4-3-3-3 Section 4.3.3.3: clock GetTime(): Return the
01894  *      current clock time 
01895  * 
01896  * \par
01897  * This macro updates the current time if necessary, and returns the current
01898  * time into the cv argument, which is declared to be of type (struct clock *). 
01899  * 4.3.3.4 clock Sec(): Get the current clock time, truncated to seconds 
01900  * This macro returns the long value of the sec field of the current time. The
01901  * recorded time is updated if necessary before the above value is returned. 
01902  * 
01903  *      \subsubsection sec4-3-3-5 Section 4.3.3.5: clock ElapsedTime(): Measure
01904  *      milliseconds between two given clock values 
01905  * 
01906  * \par
01907  * This macro returns the elapsed time in milliseconds between the two clock
01908  * structure pointers provided as arguments, cv1 and cv2. 
01909  * 
01910  *      \subsubsection sec4-3-3-6 Section 4.3.3.6: clock Advance(): Advance the
01911  *      recorded clock time by a specified clock value 
01912  * 
01913  * \par
01914  * This macro takes a single (struct clock *) pointer argument, cv, and adds
01915  * this clock value to the internal clock value maintined by the package. 
01916  * 
01917  *      \subsubsection sec4-3-3-7 Section 4.3.3.7: clock Gt(): Is a clock value
01918  *      greater than another? 
01919  * 
01920  * \par
01921  * This macro takes two parameters of type (struct clock *), a and b. It
01922  * returns a nonzero value if the a parameter points to a clock value which is
01923  * later than the one pointed to by b. 
01924  * 
01925  *      \subsubsection sec4-3-3-8 Section 4.3.3.8: clock Ge(): Is a clock value
01926  *      greater than or equal to another? 
01927  * 
01928  * \par
01929  * This macro takes two parameters of type (struct clock *), a and b. It
01930  * returns a nonzero value if the a parameter points to a clock value which is
01931  * greater than or equal to the one pointed to by b. 
01932  * 
01933  *      \subsubsection sec4-3-3-9 Section 4.3.3.9: clock Gt(): Are two clock
01934  *      values equal? 
01935  * 
01936  * \par
01937  * This macro takes two parameters of type (struct clock *), a and b. It
01938  * returns a non-zero value if the clock values pointed to by a and b are
01939  * equal. 
01940  * 
01941  *      \subsubsection sec4.3.3.10 Section 4.3.3.10: clock Le(): Is a clock
01942  *      value less than or equal to another? 
01943  * 
01944  * \par
01945  * This macro takes two parameters of type (struct clock *), a and b. It
01946  * returns a nonzero value if the a parameter points to a clock value which is
01947  * less than or equal to the one pointed to by b. 
01948  * 
01949  *      \subsubsection sec4-3-3-11 Section 4.3.3.11: clock Lt(): Is a clock
01950  *      value less than another? 
01951  * 
01952  * \par
01953  * This macro takes two parameters of type (struct clock *), a and b. It
01954  * returns a nonzero value if the a parameter points to a clock value which is
01955  * less than the one pointed to by b. 
01956  * 
01957  *      \subsubsection sec4-3-3-12 Section 4.3.3.12: clock IsZero(): Is a clock
01958  *      value zero? 
01959  * 
01960  * \par
01961  * This macro takes a single parameter of type (struct clock *), c. It returns
01962  * a non-zero value if the c parameter points to a clock value which is equal
01963  * to zero. 
01964  * 
01965  *      \subsubsection sec4-3-3-13 Section 4.3.3.13: clock Zero(): Set a clock
01966  *      value to zero 
01967  * 
01968  * \par
01969  * This macro takes a single parameter of type (struct clock *), c. It sets the
01970  * given clock value to zero. 
01971  *      \subsubsection sec4-3-3-14 Section 4.3.3.14: clock Add(): Add two clock
01972  *      values together 
01973  * \par
01974  * This macro takes two parameters of type (struct clock *), c1 and c2. It adds
01975  * the value of the time in c2 to c1. Both clock values must be positive. 
01976  * 
01977  *      \subsubsection sec4-3-3-15 Section 4.3.3.15: clock Sub(): Subtract two
01978  *      clock values 
01979  * 
01980  * \par
01981  * This macro takes two parameters of type (struct clock *), c1 and c2. It
01982  * subtracts the value of the time in c2 from c1. The time pointed to by c2
01983  * should be less than the time pointed to by c1. 
01984  * 
01985  *      \subsubsection sec4-3-3-16 Section 4.3.3.16: clock Float(): Convert a
01986  *      clock time into floating point 
01987  * 
01988  * \par
01989  * This macro takes a single parameter of type (struct clock *), c. It
01990  * expresses the given clock value as a floating point number. 
01991  * 
01992  *      \section sec4-4 Section 4.4: The rx event Package 
01993  * 
01994  * \par
01995  * This package maintains an event facility. An event is defined to be
01996  * something that happens at or after a specified clock time, unless cancelled
01997  * prematurely. The clock times used are those provided by the rx clock
01998  * facility described in Section 4.3 above. A user routine associated with an
01999  * event is called with the appropriate arguments when that event occurs. There
02000  * are some restrictions on user routines associated with such events. first,
02001  * this user-supplied routine should not cause process preemption. Also, the
02002  * event passed to the user routine is still resident on the event queue at the
02003  * time of invocation. The user must not remove this event explicitly (via an
02004  * event Cancel(), see below). Rather, the user routine may remove or schedule
02005  * any other event at this time. 
02006  * \par
02007  * The events recorded by this package are kept queued in order of expiration
02008  * time, so that the first entry in the queue corresponds to the event which is
02009  * the first to expire. This interface is defined by the rx event.h include
02010  * file. 
02011  * 
02012  *      \subsection sec4-4-1 Section 4.4.1: struct rxevent 
02013  * 
02014  * \par
02015  * This structure defines the format of an Rx event record. 
02016  * \par
02017  * \b fields 
02018  * \n struct queue junk -The queue to which this event belongs. 
02019  * \n struct clock eventTime -The clock time recording when this event comes
02020  * due. 
02021  * \n int (*func)() -The user-supplied function to call upon expiration. 
02022  * \n char *arg -The first argument to the (*func)() function above. 
02023  * \n char *arg1 -The second argument to the (*func)() function above. 
02024  * 
02025  *      \subsection sec4-4-2 Section 4.4.2: Operations 
02026  * 
02027  * \par
02028  * This section covers the interface routines provided for the Rx event
02029  * package. 
02030  * 
02031  *      \subsubsection sec4-4-2-1 Section 4.4.2.1: rxevent Init(): Initialize
02032  *      the event package 
02033  * 
02034  * \par
02035  * The rxevent Init() routine takes two arguments. The first, nEvents, is an
02036  * integer-valued parameter which specifies the number of event structures to
02037  * allocate at one time. This specifies the appropriate granularity of memory
02038  * allocation by the event package. The second parameter, scheduler, is a
02039  * pointer to an integer-valued function. This function is to be called when an
02040  * event is posted (added to the set of events managed by the package) that is
02041  * scheduled to expire before any other existing event. 
02042  * \par
02043  * This routine sets up future event allocation block sizes, initializes the
02044  * queues used to manage active and free event structures, and recalls that an
02045  * initialization has occurred. Thus, this function may be safely called
02046  * multiple times. 
02047  * 
02048  *      \subsubsection sec4-4-2-2 Section 4.4.2.2: rxevent Post(): Schedule an
02049  *      event 
02050  * 
02051  * \par
02052  * This function constructs a new event based on the information included in
02053  * its parameters and then schedules it. The rxevent Post() routine takes four
02054  * parameters. The first is named when, and is of type (struct clock *). It
02055  * specifies the clock time at which the event is to occur. The second
02056  * parameter is named func and is a pointer to the integer-valued function to
02057  * associate with the event that will be created. When the event comes due,
02058  * this function will be executed by the event package. The next two arguments
02059  * to rxevent Post() are named arg and arg1, and are both of type (char *).
02060  * They serve as the two arguments thath will be supplied to the func routine
02061  * when the event comes due. 
02062  * \par
02063  * If the given event is set to take place before any other event currently
02064  * posted, the scheduler routine established when the rxevent Init() routine
02065  * was called will be executed. This gives the application a chance to react to
02066  * this new event in a reasonable way. One might expect that this scheduler
02067  * routine will alter sleep times used by the application to make sure that it
02068  * executes in time to handle the new event. 
02069  * 
02070  *      \subsubsection sec4-4-2-3 Section 4.4.2.3: rxevent Cancel 1(): Cancel
02071  *      an event (internal use) 
02072  * 
02073  * \par
02074  * This routine removes an event from the set managed by this package. It takes
02075  * a single parameter named ev of type (struct rxevent *). The ev argument
02076  * identifies the pending event to be cancelled. 
02077  * \par
02078  * The rxevent Cancel 1() routine should never be called directly. Rather, it
02079  * should be accessed through the rxevent Cancel() macro, described in Section
02080  * 4.4.2.4 below. 
02081  * 
02082  *      \subsubsection sec4-4-2-4 Section 4.4.2.4: rxevent Cancel(): Cancel an
02083  *      event (external use) 
02084  * 
02085  * \par
02086  * This macro is the proper way to call the rxevent Cancel 1() routine
02087  * described in Section 4.4.2.3 above. Like rxevent Cancel 1(), it takes a
02088  * single argument. This event ptr argument is of type (struct rxevent *), and
02089  * identi#es the pending event to be cancelled. This macro #rst checks to see
02090  * if event ptr is null. If not, it calls rxevent Cancel 1() to perform the
02091  * real work. The event ptr argument is zeroed after the cancellation operation
02092  * completes. 
02093  * 
02094  *      \subsubsection sec4-4-2-5 Section 4.4.2.4: rxevent RaiseEvents():
02095  *      Initialize the event package 
02096  * 
02097  * \par
02098  * This function processes all events that have expired relative to the current
02099  * clock time maintained by the event package. Each qualifying event is removed
02100  * from the queue in order, and its user-supplied routine (func()) is executed
02101  * with the associated arguments. 
02102  * \par
02103  * The rxevent RaiseEvents() routine takes a single output parameter named
02104  * next, defined to be of type (struct clock *). Upon completion of rxevent
02105  * RaiseEvents(), the relative time to the next event due to expire is placed
02106  * in next. This knowledge may be used to calculate the amount of sleep time
02107  * before more event processing is needed. If there is no recorded event which
02108  * is still pending at this point, rxevent RaiseEvents() returns a zeroed clock
02109  * value into next. 
02110  * 
02111  *      \subsubsection sec4-4-2-6 Section 4.4.2.6: rxevent TimeToNextEvent():
02112  *      Get amount of time until the next event expires 
02113  * 
02114  * \par
02115  * This function returns the time between the current clock value as maintained
02116  * by the event package and the the next event's expiration time. This
02117  * information is placed in the single output argument,interval, defined to be
02118  * of type (struct clock *). The rxevent TimeToNextEvent() function returns
02119  * integer-valued quantities. If there are no scheduled events, a zero is
02120  * returned. If there are one or more scheduled events, a 1 is returned. If
02121  * zero is returned, the interval argument is not updated. 
02122  * 
02123  *      \page chap5 Chapter 5 -- Programming Interface 
02124  * 
02125  *      \section sec5-1 Section 5.1: Introduction 
02126  * 
02127  * \par
02128  * This chapter documents the API for the Rx facility. Included are
02129  * descriptions of all the constants, structures, exported variables, macros,
02130  * and interface functions available to the application programmer. This
02131  * interface is identical regardless of whether the application lives within
02132  * the unix kernel or above it. 
02133  * \par
02134  * This chapter actually provides more information than what may be strictly
02135  * considered the Rx API. Many objects that were intended to be opaque and for
02136  * Rx internal use only are also described here. The reason driving the
02137  * inclusion of this "extra" information is that such exported Rx interface
02138  * files as rx.h make these objects visible to application programmers. It is
02139  * prefereable to describe these objects here than to ignore them and leave
02140  * application programmers wondering as to their meaning. 
02141  * \par
02142  * An example application illustrating the use of this interface, showcasing
02143  * code from both server and client sides, appears in the following chapter. 
02144  * 
02145  *      \section sec5-2 Section 5.2: Constants 
02146  * 
02147  * \par
02148  * This section covers the basic constant definitions of interest to the Rx
02149  * application programmer. Each subsection is devoted to describing the
02150  * constants falling into the following categories: 
02151  * \li Configuration quantities 
02152  * \li Waiting options 
02153  * \li Connection ID operations 
02154  * \li Connection flags 
02155  * \li Connection types 
02156  * \li Call states 
02157  * \li Call flags 
02158  * \li Call modes 
02159  * \li Packet header flags 
02160  * \li Packet sizes 
02161  * \li Packet types 
02162  * \li Packet classes 
02163  * \li Conditions prompting ack packets 
02164  * \li Ack types 
02165  * \li Error codes 
02166  * \li Debugging values 
02167  * \par
02168  * An attempt has been made to relate these constant definitions to the objects
02169  * or routines that utilize them. 
02170  * 
02171  *      \subsection sec5-2-1 Section 5.2.1: Configuration Quantities 
02172  * 
02173  * \par
02174  * These definitions provide some basic Rx configuration parameters, including
02175  * the number of simultaneous calls that may be handled on a single connection,
02176  * lightweight thread parameters, and timeouts for various operations. 
02177  * 
02178  * \par Name 
02179  * RX IDLE DEAD TIME
02180  * \par Value 
02181  * 60
02182  * \par Description
02183  * Default idle dead time for connections, in seconds.
02184  * 
02185  * \par Name 
02186  * RX MAX SERVICES
02187  * \par Value 
02188  * 20
02189  * \par Description
02190  * The maximum number of Rx services that may be installed within one
02191  * application.
02192  * 
02193  * \par Name 
02194  * RX PROCESS MAXCALLS
02195  * \par Value 
02196  * 4
02197  * \par Description
02198  * The maximum number of asynchronous calls active simultaneously on any given
02199  * Rx connection.  This value must be set to a power of two.
02200  * 
02201  * \par Name 
02202  * RX DEFAULT STACK SIZE
02203  * \par Value 
02204  * 16,000
02205  * \par Description
02206  * Default lightweight thread stack size, measured in bytes.  This value may be
02207  * overridden by calling the rx_SetStackSize() macro.
02208  * 
02209  * \par Name 
02210  * RX PROCESS PRIORITY
02211  * \par Value 
02212  * LWP NORMAL PRIORITY
02213  * \par Description
02214  * This is the priority under which an Rx thread should run.  There should not
02215  * generally be any reason to change this setting.
02216  * 
02217  * \par Name 
02218  * RX CHALLENGE TIMEOUT
02219  * \par Value 
02220  * 2
02221  * \par Description
02222  * The number of seconds before another authentication request packet is
02223  * generated.
02224  * 
02225  * \par Name 
02226  * RX MAXACKS
02227  * \par Value 
02228  * 255
02229  * \par Description
02230  * Maximum number of individual acknowledgements that may be carried in an Rx
02231  * acknowledgement packet.
02232  * 
02233  *      \subsection sec5-2-2 Section 5.2.2: Waiting Options 
02234  * 
02235  * \par
02236  * These definitions provide readable values indicating whether an operation
02237  * should block when packet buffer resources are not available. 
02238  * 
02239  * \par Name 
02240  * RX DONTWAIT
02241  * \par Value 
02242  * 0
02243  * \par Description
02244  * Wait until the associated operation completes.
02245  * 
02246  * \par Name 
02247  * RX WAIT
02248  * \par Value 
02249  * 1
02250  * \par Description
02251  * Don't wait if the associated operation would block.
02252  * 
02253  *      \subsection sec5-2-3 Section 5.2.3: Connection ID Operations 
02254  * 
02255  * \par
02256  * These values assist in extracting the call channel number from a connection
02257  * identifier. A call channel is the index of a particular asynchronous call
02258  * structure within a single Rx connection. 
02259  * 
02260  * \par Name 
02261  * RX CIDSHIFT
02262  * \par Value 
02263  * 2
02264  * \par Description
02265  * Number of bits to right-shift to isolate a connection ID.  Must be set to
02266  * the log (base two) of RX MAXCALLS.
02267  * 
02268  * \par Name 
02269  * RX CHANNELMASK
02270  * \par Value 
02271  * (RX MAXCALLS-1)
02272  * \par Description
02273  * Mask used to isolate a call channel from a connection ID field.
02274  * 
02275  * \par Name 
02276  * RX CIDMASK
02277  * \par Value 
02278  * (~RX CHANNELMASK)
02279  * \par Description
02280  * Mask used to isolate the connection ID from its field, masking out the call
02281  * channel information.
02282  * 
02283  *      \subsection sec5-2-4 Section 5.2.4: Connection Flags 
02284  * 
02285  * \par
02286  * The values defined here appear in the flags field of Rx connections, as
02287  * defined by the rx connection structure described in Section 5.3.2.2. 
02288  * 
02289  * \par Name 
02290  * RX CONN MAKECALL WAITING
02291  * \par Value 
02292  * 1
02293  * \par Description
02294  * rx MakeCall() is waiting for a channel.
02295  * 
02296  * \par Name 
02297  * RX CONN DESTROY ME
02298  * \par Value 
02299  * 2
02300  * \par Description
02301  * Destroy this (client) connection after its last call completes.
02302  * 
02303  * \par Name 
02304  * RX CONN USING PACKET CKSUM
02305  * \par Value 
02306  * 4
02307  * \par Description
02308  * This packet is using security-related check-summing (a non-zero header,
02309  * spare field has been seen.)
02310  * 
02311  *      \subsection sec5-2-5 Section 5.2.5: Connection Types 
02312  * 
02313  * \par
02314  * Rx stores different information in its connection structures, depending on
02315  * whether the given connection represents the server side (the one providing
02316  * the service) or the client side (the one requesting the service) of the
02317  * protocol. The type field within the connection structure (described in
02318  * Section 5.3.2.2) takes on the following values to differentiate the two
02319  * types of connections, and identifies the fields that are active within the
02320  * connection structure. 
02321  * 
02322  * \par Name 
02323  * RX CLIENT CONNECTION
02324  * \par Value 
02325  * 0
02326  * \par Description
02327  * This is a client-side connection.
02328  * 
02329  * \par Name 
02330  * CONNECTION
02331  * \par Value 
02332  * 1
02333  * \par Description
02334  * This is a server-side connection.
02335  * 
02336  *      \subsection sec5-2-6 Section 5.2.6: Call States 
02337  * 
02338  * \par
02339  * An Rx call on a particular connection may be in one of several states at any
02340  * instant in time. The following definitions identify the range of states that
02341  * a call may assume. 
02342  * 
02343  * \par Name 
02344  * RX STATE NOTINIT
02345  * \par Value 
02346  * 0
02347  * \par Description
02348  * The call structure has never been used, and is thus still completely
02349  * uninitialized.
02350  * 
02351  * \par Name 
02352  * RX STATE PRECALL
02353  * \par Value 
02354  * 1
02355  * \par Description
02356  * A call is not yet in progress, but packets have arrived for it anyway.  This
02357  * only applies to calls within server-side connections.
02358  * 
02359  * \par Name 
02360  * RX STATE ACTIVE
02361  * \par Value 
02362  * 2
02363  * \par Description
02364  * This call is fully active, having an attached lightweight thread operating
02365  * on its behalf.
02366  * 
02367  * \par Name 
02368  * RX STATE DAILY
02369  * \par Value 
02370  * 3
02371  * \par Description
02372  * The call structure is "dallying" after its lightweight thread has completed
02373  * its most recent call.  This is a "hot-standby" condition, where the call
02374  * structure preserves state from the previous call and thus optimizes the
02375  * arrival of further, related calls.
02376  * 
02377  *      \subsection sec5-2-7 Section 5.2.7: Call Flags: 
02378  * 
02379  * \par
02380  * These values are used within the flags field of a variable declared to be of
02381  * type struct rx call, as described in Section 5.3.2.4. They provide
02382  * additional information as to the state of the given Rx call, such as the
02383  * type of event for which it is waiting (if any) and whether or not all
02384  * incoming packets have been received in support of the call. 
02385  * 
02386  * \par Name 
02387  * RX CALL READER WAIT
02388  * \par Value 
02389  * 1
02390  * \par Description
02391  * Reader is waiting for next packet.
02392  * 
02393  * \par Name 
02394  * RX CALL WAIT WINDOW ALLOC
02395  * \par Value 
02396  * 2
02397  * \par Description
02398  * Sender is waiting for a window so that it can allocate buffers.
02399  * 
02400  * \par Name 
02401  * RX CALL WAIT WINDOW SEND
02402  * \par Value 
02403  * 4
02404  * \par Description
02405  * Sender is waiting for a window so that it can send buffers.
02406  * 
02407  * \par Name 
02408  * RX CALL WAIT PACKETS
02409  * \par Value 
02410  * 8
02411  * \par Description
02412  * Sender is waiting for packet buffers.
02413  * 
02414  * \par Name 
02415  * RX CALL RECEIVE DONE
02416  * \par Value 
02417  * 16
02418  * \par Description
02419  * The call is waiting for a lightweight thread to be assigned to the operation
02420  * it has just received.
02421  * 
02422  * \par Name 
02423  * RX CALL RECEIVE DONE 
02424  * \par Value 
02425  * 32
02426  * \par Description
02427  * All packets have been received on this call.
02428  * 
02429  * \par Name 
02430  * RX CALL CLEARED
02431  * \par Value 
02432  * 64
02433  * \par Description
02434  * The receive queue has been cleared when in precall state.
02435  * 
02436  *      \subsection sec5-2-8 Section 5.2.8: Call Modes 
02437  * 
02438  * \par
02439  * These values define the modes of an Rx call when it is in the RX STATE
02440  * ACTIVE state, having a lightweight thread assigned to it. 
02441  * 
02442  * \par Name 
02443  * RX MODE SENDING
02444  * \par Value 
02445  * 1
02446  * \par Description
02447  * We are sending or ready to send.
02448  * 
02449  * \par Name 
02450  * RX MODE RECEIVING
02451  * \par Value 
02452  * 2
02453  * \par Description
02454  * We are receiving or ready to receive.
02455  * 
02456  * \par Name 
02457  * RX MODE ERROR
02458  * \par Value 
02459  * 3
02460  * \par Description
02461  * Something went wrong in the current conversation.
02462  * 
02463  * \par Name 
02464  * RX MODE EOF
02465  * \par Value 
02466  * 4
02467  * \par Description
02468  * The server side has flushed (or the client side has read) the last reply
02469  * packet.
02470  * 
02471  *      \subsection sec5-2-9 Section 5.2.9: Packet Header Flags 
02472  * 
02473  * \par
02474  * Rx packets carry a flag field in their headers, providing additional
02475  * information regarding the packet's contents. The Rx packet header's flag
02476  * field's bits may take the following values: 
02477  * 
02478  * \par Name 
02479  * RX CLIENT INITIATED
02480  * \par Value 
02481  * 1
02482  * \par Description
02483  * Signifies that a packet has been sent/received from the client side of the
02484  * call.
02485  * 
02486  * \par Name 
02487  * RX REQUEST ACK
02488  * \par Value 
02489  * 2
02490  * \par Description
02491  * The Rx calls' peer entity requests an acknowledgement.
02492  * 
02493  * \par Name 
02494  * RX LAST PACKET
02495  * \par Value 
02496  * 4
02497  * \par Description
02498  * This is the final packet from this side of the call.
02499  * 
02500  * \par Name 
02501  * RX MORE PACKETS
02502  * \par Value 
02503  * 8
02504  * \par Description
02505  * There are more packets following this, i.e., the next sequence number seen
02506  * by the receiver should be greater than this one, rather than a
02507  * retransmission of an earlier sequence number.
02508  * 
02509  * \par Name 
02510  * RX PRESET FLAGS
02511  * \par Value 
02512  * (RX CLIENT INITIATED | RX LAST PACKET)
02513  * \par Description
02514  * This flag is preset once per Rx packet.  It doesn't change on retransmission
02515  * of the packet.
02516  * 
02517  *      \subsection sec5-3-10 Section 5.2.10: Packet Sizes 
02518  * 
02519  * \par
02520  * These values provide sizing information on the various regions within Rx
02521  * packets. These packet sections include the IP/UDP headers and bodies as well
02522  * Rx header and bodies. Also covered are such values as different maximum
02523  * packet sizes depending on whether they are targeted to peers on the same
02524  * local network or a more far-flung network. Note that the MTU term appearing
02525  * below is an abbreviation for Maximum Transmission Unit. 
02526  * 
02527  * \par Name 
02528  * RX IPUDP SIZE
02529  * \par Value 
02530  * 28
02531  * \par Description
02532  * The number of bytes taken up by IP/UDP headers.
02533  * 
02534  * \par Name 
02535  * RX MAX PACKET SIZE
02536  * \par Value 
02537  * (1500 - RX IPUDP SIZE)
02538  * \par Description
02539  * This is the Ethernet MTU minus IP and UDP header sizes.
02540  * 
02541  * \par Name 
02542  * RX HEADER SIZE
02543  * \par Value 
02544  * sizeof (struct rx header)
02545  * \par Description
02546  * The number of bytes in an Rx packet header.
02547  * 
02548  * \par Name 
02549  * RX MAX PACKET DATA SIZE
02550  * \par Value 
02551  * (RX MAX PACKET SIZE RX - HEADER SIZE)
02552  * \par Description
02553  * Maximum size in bytes of the user data in a packet.
02554  * 
02555  * \par Name 
02556  * RX LOCAL PACKET SIZE
02557  * \par Value 
02558  * RX MAX PACKET SIZE
02559  * \par Description
02560  * Packet size in bytes to use when being sent to a host on the same net.
02561  * 
02562  * \par Name 
02563  * RX REMOTE PACKET SIZE
02564  * \par Value 
02565  * (576 - RX IPUDP SIZE)
02566  * \par Description
02567  * Packet size in bytes to use when being sent to a host on a different net.
02568  * 
02569  *      \subsection sec5-2-11 Section 5.2.11: Packet Types 
02570  * 
02571  * \par
02572  * The following values are used in the packetType field within a struct rx
02573  * packet, and define the different roles assumed by Rx packets. These roles
02574  * include user data packets, different flavors of acknowledgements, busies,
02575  * aborts, authentication challenges and responses, and debugging vehicles. 
02576  * 
02577  * \par Name 
02578  * RX PACKET TYPE DATA
02579  * \par Value 
02580  * 1
02581  * \par Description
02582  * A user data packet.
02583  * 
02584  * \par Name 
02585  * RX PACKET TYPE ACK
02586  * \par Value 
02587  * 2
02588  * \par Description
02589  * Acknowledgement packet.
02590  * 
02591  * \par Name 
02592  * RX PACKET TYPE BUSY
02593  * \par Value 
02594  * 3
02595  * \par Description
02596  * Busy packet.  The server-side entity cannot accept the call at the moment,
02597  * but the requestor is encouraged to try again later.
02598  * 
02599  * \par Name 
02600  * RX PACKET TYPE ABORT 
02601  * \par Value 
02602  * 4
02603  * \par Description
02604  * Abort packet. No response is needed for this packet type.
02605  * 
02606  * \par Name 
02607  * RX PACKET TYPE ACKALL
02608  * \par Value 
02609  * 5
02610  * \par Description
02611  * Acknowledges receipt of all packets on a call.
02612  * 
02613  * \par Name 
02614  * RX PACKET TYPE CHALLENGE
02615  * \par Value 
02616  * 6
02617  * \par Description
02618  * Challenge the client's identity, requesting credentials.
02619  * 
02620  * \par Name 
02621  * RX PACKET TYPE RESPONSE
02622  * \par Value 
02623  * 7
02624  * \par Description
02625  * Response to a RX PACKET TYPE CHALLENGE authentication challenge packet.
02626  * 
02627  * \par Name 
02628  * RX PACKET TYPE DEBUG
02629  * \par Value 
02630  * 8
02631  * \par Description
02632  * Request for debugging information.
02633  * 
02634  * \par Name 
02635  * RX N PACKET TYPES
02636  * \par Value 
02637  * 9
02638  * \par Description
02639  * The number of Rx packet types defined above.  Note that it also includes
02640  * packet type 0 (which is unused) in the count.
02641  * 
02642  * \par
02643  * The RX PACKET TYPES definition provides a mapping of the above values to
02644  * human-readable string names, and is exported by the rx packetTypes variable
02645  * catalogued in Section 5.4.9. 
02646  * 
02647  * \code 
02648  * {
02649  *      "data", 
02650  *      "ack", 
02651  *      "busy", 
02652  *      "abort", 
02653  *      "ackall", 
02654  *      "challenge", 
02655  *      "response", 
02656  *      "debug" 
02657  * } 
02658  * \endcode
02659  * 
02660  *      \subsection sec5-2-12 Section 5.2.12: Packet Classes 
02661  * 
02662  * \par
02663  * These definitions are used internally to manage alloction of Rx packet
02664  * buffers according to quota classifications. Each packet belongs to one of
02665  * the following classes, and its buffer is derived from the corresponding
02666  * pool. 
02667  * 
02668  * \par Name 
02669  * RX PACKET CLASS RECEIVE
02670  * \par Value 
02671  * 0
02672  * \par Description
02673  * Receive packet for user data.
02674  * 
02675  * \par Name 
02676  * RX PACKET CLASS SEND
02677  * \par Value 
02678  * 1
02679  * \par Description
02680  * Send packet for user data.
02681  * 
02682  * \par Name 
02683  * RX PACKET CLASS SPECIAL
02684  * \par Value 
02685  * 2
02686  * \par Description
02687  * A special packet that does not hold user data, such as an acknowledgement or
02688  * authentication challenge.
02689  * 
02690  * \par Name 
02691  * RX N PACKET CLASSES
02692  * \par Value 
02693  * 3
02694  * \par Description
02695  * The number of Rx packet classes defined above.
02696  * 
02697  *      \subsection sec5-2-13 Section 5.2.13: Conditions Prompting Ack Packets 
02698  * 
02699  * \par
02700  * Rx acknowledgement packets are constructed and sent by the protocol
02701  * according to the following reasons. These values appear in the Rx packet
02702  * header of the ack packet itself. 
02703  * 
02704  * \par Name 
02705  * RX ACK REQUESTED
02706  * \par Value 
02707  * 1
02708  * \par Description
02709  * The peer has explicitly requested an ack on this packet.
02710  * 
02711  * \par Name 
02712  * RX ACK DUPLICATE
02713  * \par Value 
02714  * 2
02715  * \par Description
02716  * A duplicate packet has been received.
02717  * 
02718  * \par Name 
02719  * RX ACK OUT OF SEQUENCE
02720  * \par Value 
02721  * 3
02722  * \par Description
02723  * A packet has arrived out of sequence.
02724  * 
02725  * \par Name 
02726  * RX ACK EXCEEDS WINDOW
02727  * \par Value 
02728  * 4
02729  * \par Description
02730  * A packet sequence number higher than maximum value allowed by the call's
02731  * window has been received.
02732  * 
02733  * \par Name 
02734  * RX ACK NOSPACE
02735  * \par Value 
02736  * 5
02737  * \par Description
02738  * No packet buffer space is available.
02739  * 
02740  * \par Name 
02741  * RX ACK PING
02742  * \par Value 
02743  * 6
02744  * \par Description
02745  * Acknowledgement for keep-alive purposes.
02746  * 
02747  * \par Name 
02748  * RX ACK PING RESPONSE
02749  * \par Value 
02750  * 7
02751  * \par Description
02752  * Response to a RX ACK PING packet.
02753  * 
02754  * \par Name 
02755  * RX ACK DELAY
02756  * \par Value 
02757  * 8
02758  * \par Description
02759  * An ack generated due to a period of inactivity after normal packet
02760  * receptions.
02761  * 
02762  *      \subsection 5-2-14 Section 5.2.14: Acknowledgement Types 
02763  * 
02764  * \par
02765  * These are the set of values placed into the acks array in an Rx
02766  * acknowledgement packet, whose data format is defined by struct rx ackPacket.
02767  * These definitions are used to convey positive or negative acknowledgements
02768  * for a given range of packets. 
02769  * 
02770  * \par Name 
02771  * RX ACK TYPE NACK
02772  * \par Value 
02773  * 0
02774  * \par Description
02775  * Receiver doesn't currently have the associated packet; it may never hae been
02776  * received, or received and then later dropped before processing.
02777  * 
02778  * \par Name 
02779  * RX ACK TYPE ACK
02780  * \par Value 
02781  * 1
02782  * \par Description
02783  * Receiver has the associated packet queued, although it may later decide to
02784  * discard it.
02785  * 
02786  *      \subsection sec5-2-15 Section 5.2.15: Error Codes 
02787  * 
02788  * \par
02789  * Rx employs error codes ranging from -1 to -64. The Rxgen stub generator may
02790  * use other error codes less than -64. User programs calling on Rx, on the
02791  * other hand, are expected to return positive error codes. A return value of
02792  * zero is interpreted as an indication that the given operation completed
02793  * successfully. 
02794  * 
02795  * \par Name 
02796  * RX CALL DEAD
02797  * \par Value 
02798  * -1
02799  * \par Description
02800  * A connection has been inactive past Rx's tolerance levels and has been shut
02801  * down.
02802  * 
02803  * \par Name 
02804  * RX INVALID OPERATION
02805  * \par Value 
02806  * -2
02807  * \par Description
02808  * An invalid operation has been attempted, including such protocol errors as
02809  * having a client-side call send data after having received the beginning of a
02810  * reply from its server-side peer.
02811  * 
02812  * \par Name 
02813  * RX CALL TIMEOUT
02814  * \par Value 
02815  * -3
02816  * \par Description
02817  * The (optional) timeout value placed on this call has been exceeded (see
02818  * Sections 5.5.3.4 and 5.6.5).
02819  * 
02820  * \par Name 
02821  * RX EOF
02822  * \par Value 
02823  * -4
02824  * \par Description
02825  * Unexpected end of data on a read operation.
02826  * 
02827  * \par Name 
02828  * RX PROTOCOL ERROR
02829  * \par Value 
02830  * -5
02831  * \par Description
02832  * An unspecified low-level Rx protocol error has occurred.
02833  * 
02834  * \par Name 
02835  * RX USER ABORT
02836  * \par Value 
02837  * -6
02838  * \par Description
02839  * A generic user abort code, used when no more specific error code needs to be
02840  * communicated.  For example, Rx clients employing the multicast feature (see
02841  * Section 1.2.8) take advantage of this error code.
02842  * 
02843  *      \subsection sec5-2-16 Section 5.2.16: Debugging Values 
02844  * 
02845  * \par
02846  * Rx provides a set of data collections that convey information about its
02847  * internal status and performance. The following values have been defined in
02848  * support of this debugging and statistics-collection feature. 
02849  * 
02850  *      \subsubsection sec5-3-16-1 Section 5.2.16.1: Version Information 
02851  * 
02852  * \par
02853  * Various versions of the Rx debugging/statistics interface are in existance,
02854  * each defining different data collections and handling certain bugs. Each Rx
02855  * facility is stamped with a version number of its debugging/statistics
02856  * interface, allowing its clients to tailor their requests to the precise data
02857  * collections that are supported by a particular Rx entity, and to properly
02858  * interpret the data formats received through this interface. All existing Rx
02859  * implementations should be at revision M. 
02860  * 
02861  * \par Name 
02862  * RX DEBUGI VERSION MINIMUM
02863  * \par Value 
02864  * 'L'
02865  * \par Description
02866  * The earliest version of Rx statistics available.
02867  * 
02868  * \par Name 
02869  * RX DEBUGI VERSION
02870  * \par Value 
02871  * 'M'
02872  * \par Description
02873  * The latest version of Rx statistics available.
02874  * 
02875  * \par Name 
02876  * RX DEBUGI VERSION W SECSTATS
02877  * \par Value 
02878  * 'L'
02879  * \par Description
02880  * Identifies the earliest version in which statistics concerning Rx security
02881  * objects is available.
02882  * 
02883  * \par Name 
02884  * RX DEBUGI VERSION W GETALLCONN
02885  * \par Value 
02886  * 'M'
02887  * \par Description
02888  * The first version that supports getting information about all current Rx
02889  * connections, as specified y the RX DEBUGI GETALLCONN debugging request
02890  * packet opcode described below.
02891  * 
02892  * \par Name 
02893  * RX DEBUGI VERSION W RXSTATS
02894  * \par Value 
02895  * 'M'
02896  * \par Description
02897  * The first version that supports getting all the Rx statistics in one
02898  * operation, as specified by the RX DEBUGI RXSTATS debugging request packet
02899  * opcode described below.
02900  * 
02901  * \par Name 
02902  * RX DEBUGI VERSION W UNALIGNED CONN
02903  * \par Value 
02904  * 'L'
02905  * \par Description
02906  * There was an alignment problem discovered when returning Rx connection
02907  * information in older versions of this debugging/statistics interface.  This
02908  * identifies the last version that exhibited this alignment problem.
02909  * 
02910  *      \subsubsection sec5-2-16-2 Section 5.2.16.2: Opcodes 
02911  * 
02912  * \par
02913  * When requesting debugging/statistics information, the caller specifies one
02914  * of the following supported data collections: 
02915  * 
02916  * \par Name 
02917  * RX DEBUGI GETSTATS
02918  * \par Value 
02919  * 1
02920  * \par Description
02921  * Get basic Rx statistics.
02922  * 
02923  * \par Name 
02924  * RX DEBUGI GETCONN
02925  * \par Value 
02926  * 2
02927  * \par Description
02928  * Get information on all Rx connections considered "interesting" (as defined
02929  * below), and no others.
02930  * 
02931  * \par Name 
02932  * RX DEBUGI GETALLCONN
02933  * \par Value 
02934  * 3
02935  * \par Description
02936  * Get information on all existing Rx connection structures, even
02937  * "uninteresting" ones.
02938  * 
02939  * \par Name 
02940  * RX DEBUGI RXSTATS
02941  * \par Value 
02942  * 4
02943  * \par Description
02944  * Get all available Rx stats.
02945  * 
02946  * \par
02947  * An Rx connection is considered "interesting" if it is waiting for a call
02948  * channel to free up or if it has been marked for destruction. If neither is
02949  * true, a connection is still considered interesting if any of its call
02950  * channels is actively handling a call or in its preparatory pre-call state.
02951  * Failing all the above conditions, a connection is still tagged as
02952  * interesting if any of its call channels is in either of the RX MODE SENDING
02953  * or RX MODE RECEIVING modes, which are not allowed when the call is not
02954  * active. 
02955  * 
02956  *      \subsubsection sec5-2-16-3 Section 5.2.16.3: Queuing 
02957  * 
02958  * \par
02959  * These two queueing-related values indicate whether packets are present on
02960  * the incoming and outgoing packet queues for a given Rx call. These values
02961  * are only used in support of debugging and statistics-gathering operations. 
02962  * 
02963  * \par Name 
02964  * RX OTHER IN
02965  * \par Value 
02966  * 1
02967  * \par Description
02968  * Packets available in in queue.
02969  * 
02970  * \par Name 
02971  * RX OTHER OUT 
02972  * \par Value 
02973  * 2
02974  * \par Description
02975  * Packets available in out queue.
02976  * 
02977  *      \section sec5-3 Section 5.3: Structures 
02978  * 
02979  * \par
02980  * This section describes the major exported Rx data structures of interest to
02981  * application programmers. The following categories are utilized for the
02982  * purpose of organizing the structure descriptions: 
02983  * \li Security objects 
02984  * \li Protocol objects 
02985  * \li Packet formats 
02986  * \li Debugging and statistics 
02987  * \li Miscellaneous 
02988  * \par
02989  * Please note that many fields described in this section are declared to be
02990  * VOID. This is defined to be char, and is used to get around some compiler
02991  * limitations. 
02992  *      \subsection sec5-3-1 Section 5.3.1: Security Objects 
02993  * 
02994  * \par
02995  * As explained in Section 1.2.1, Rx provides a modular, extensible security
02996  * model. This allows Rx applications to either use one of the built-in
02997  * security/authentication protocol packages or write and plug in one of their
02998  * own. This section examines the various structural components used by Rx to
02999  * support generic security and authentication modules. 
03000  * 
03001  *      \subsubsection sec5-3-1-1 Section 5.3.1.1: struct rx securityOps 
03002  * 
03003  * \par
03004  * As previously described, each Rx security object must export a fixed set of
03005  * interface functions, providing the full set of operations defined on the
03006  * object. The rx securityOps structure defines the array of functions
03007  * comprising this interface. The Rx facility calls these routines at the
03008  * appropriate times, without knowing the specifics of how any particular
03009  * security object implements the operation. 
03010  * \par
03011  * A complete description of these interface functions, including information
03012  * regarding their exact purpose, parameters, and calling conventions, may be
03013  * found in Section 5.5.7. 
03014  * \par
03015  * \b fields 
03016  * \li int (*op Close)() - React to the disposal of a security object. 
03017  * \li int (*op NewConnection)() - Invoked each time a new Rx connection
03018  * utilizing the associated security object is created. 
03019  * \li int (*op PreparePacket)() - Invoked each time an outgoing Rx packet is
03020  * created and sent on a connection using the given security object. 
03021  * \li int (*op SendPacket)() - Called each time a packet belonging to a call
03022  * in a connection using the security object is physically transmitted. 
03023  * \li int (*op CheckAuthentication)() - This function is executed each time it
03024  * is necessary to check whether authenticated calls are being perfomed on a
03025  * connection using the associated security object. 
03026  * \li int (*op CreateChallenge)() - Invoked each time a server-side challenge
03027  * event is created by Rx, namely when the identity of the principal associated
03028  * with the peer process must be determined. 
03029  * \li int (*op GetChallenge)() - Called each time a client-side packet is
03030  * constructed in response to an authentication challenge. 
03031  * \li int (*op GetResponse)() - Executed each time a response to a challenge
03032  * event must be received on the server side of a connection. 
03033  * \li int (*op CheckResponse)() - Invoked each time a response to an
03034  * authentication has been received, validating the response and pulling out
03035  * the required authentication information. 
03036  * \li int (*op CheckPacket) () - Invoked each time an Rx packet has been
03037  * received, making sure that the packet is properly formatted and that it
03038  * hasn't been altered. 
03039  * \li int (*op DestroyConnection)() - Called each time an Rx connection
03040  * employing the given security object is destroyed. 
03041  * \li int (*op GetStats)() - Executed each time a request for statistics on
03042  * the given security object has been received. 
03043  * \li int (*op Spare1)()-int (*op Spare3)() - Three spare function slots,
03044  * reserved for future use. 
03045  * 
03046  *      \subsubsection sec5-3-1-2 Section 5.2.1.2: struct rx securityClass 
03047  * 
03048  * \par
03049  * Variables of type struct rx securityClass are used to represent
03050  * instantiations of a particular security model employed by Rx. It consists of
03051  * a pointer to the set of interface operations implementing the given security
03052  * object, along with a pointer to private storage as necessary to support its
03053  * operations. These security objects are also reference-counted, tracking the
03054  * number of Rx connections in existance that use the given security object. If
03055  * the reference count drops to zero, the security module may garbage-collect
03056  * the space taken by the unused security object. 
03057  * \par
03058  * \b fields 
03059  * \li struct rx securityOps *ops - Pointer to the array of interface functions
03060  * for the security object. 
03061  * \li VOID *privateData - Pointer to a region of storage used by the security
03062  * object to support its operations. 
03063  * \li int refCount - A reference count on the security object, tracking the
03064  * number of Rx connections employing this model. 
03065  * 
03066  *      \subsubsection sec5-3-1-3 Section 5.3.1.3: struct rx
03067  *      securityObjectStats 
03068  * 
03069  * \par
03070  * This structure is used to report characteristics for an instantiation of a
03071  * security object on a particular Rx connection, as well as performance
03072  * figures for that object. It is used by the debugging portions of the Rx
03073  * package. Every security object defines and manages fields such as level and
03074  * flags differently. 
03075  * \par
03076  * \b fields 
03077  * \li char type - The type of security object being implemented. Existing
03078  * values are: 
03079  * \li 0: The null security package. 
03080  * \li 1: An obsolete Kerberos-like security object. 
03081  * \li 2: The rxkad discipline (see Chapter 3). 
03082  * \li char level - The level at which encryption is utilized. 
03083  * \li char sparec[10] - Used solely for alignment purposes. 
03084  * \li long flags - Status flags regarding aspects of the connection relating
03085  * to the security object. 
03086  * \li u long expires - Absolute time when the authentication information
03087  * cached by the given connection expires. A value of zero indicates that the
03088  * associated authentication information is valid for all time. 
03089  * \li u long packetsReceived - Number of packets received on this particular
03090  * connection, and thus the number of incoming packets handled by the
03091  * associated security object. 
03092  * \li u long packetsSent - Number of packets sent on this particular
03093  * connection, and thus the number of outgoing packets handled by the
03094  * associated security object. 
03095  * \li u long bytesReceived - Overall number of "payload" bytes received (i.e.,
03096  * packet bytes not associated with IP headers, UDP headers, and the security
03097  * module's own header and trailer regions) on this connection. 
03098  * \li u long bytesSent - Overall number of "payload" bytes sent (i.e., packet
03099  * bytes not associated with IP headers, UDP headers, and the security module's
03100  * own header and trailer regions) on this connection. 
03101  * \li short spares[4] - Several shortword spares, reserved for future use. 
03102  * \li long sparel[8] - Several longword spares, reserved for future use. 
03103  * 
03104  *      \subsection sec5-3-2 Section 5.3.2: Protocol Objects 
03105  * 
03106  * \par
03107  * The structures describing the main abstractions and entities provided by Rx,
03108  * namely services, peers, connections and calls are covered in this section. 
03109  * 
03110  *      \subsubsection sec5-3-2-1 Section 5.3.2.1: struct rx service 
03111  * 
03112  * \par
03113  * An Rx-based server exports services, or specific RPC interfaces that
03114  * accomplish certain tasks. Services are identified by (host-address,
03115  * UDP-port, serviceID) triples. An Rx service is installed and initialized on
03116  * a given host through the use of the rx NewService() routine (See Section
03117  * 5.6.3). Incoming calls are stamped with the Rx service type, and must match
03118  * an installed service to be accepted. Internally, Rx services also carry
03119  * string names for purposes of identification. These strings are useful to
03120  * remote debugging and statistics-gathering programs. The use of a service ID
03121  * allows a single server process to export multiple, independently-specified
03122  * Rx RPC services. 
03123  * \par
03124  * Each Rx service contains one or more security classes, as implemented by
03125  * individual security objects. These security objects implement end-to-end
03126  * security protocols. Individual peer-to-peer connections established on
03127  * behalf of an Rx service will select exactly one of the supported security
03128  * objects to define the authentication procedures followed by all calls
03129  * associated with the connection. Applications are not limited to using only
03130  * the core set of built-in security objects offered by Rx. They are free to
03131  * define their own security objects in order to execute the specific protocols
03132  * they require. 
03133  * \par
03134  * It is possible to specify both the minimum and maximum number of lightweight
03135  * processes available to handle simultaneous calls directed to an Rx service.
03136  * In addition, certain procedures may be registered with the service and
03137  * called at set times in the course of handling an RPC request. 
03138  * \par
03139  * \b fields 
03140  * \li u short serviceId - The associated service number. 
03141  * \li u short servicePort - The chosen UDP port for this service. 
03142  * \li char *serviceName - The human-readable service name, expressed as a
03143  * character 
03144  * \li string. osi socket socket - The socket structure or file descriptor used
03145  * by this service. 
03146  * \li u short nSecurityObjects - The number of entries in the array of
03147  * supported security objects. 
03148  * \li struct rx securityClass **securityObjects - The array of pointers to the
03149  * ser
03150  * vice's security class objects. 
03151  * \li long (*executeRequestProc)() - A pointer to the routine to call when an
03152  * RPC request is received for this service. 
03153  * \li VOID (*destroyConnProc)() - A pointer to the routine to call when one of
03154  * the server-side connections associated with this service is destroyed. 
03155  * \li VOID (*newConnProc)() - A pointer to the routine to call when a
03156  * server-side connection associated with this service is created. 
03157  * \li VOID (*beforeProc)() - A pointer to the routine to call before an
03158  * individual RPC call on one of this service's connections is executed. 
03159  * \li VOID (*afterProc)() - A pointer to the routine to call after an
03160  * individual RPC call on one of this service's connections is executed. 
03161  * \li short nRequestsRunning - The number of simultaneous RPC calls currently
03162  * in progress for this service. 
03163  * \li short maxProcs - This field has two meanings. first, maxProcs limits the
03164  * total number of requests that may execute in parallel for any one service.
03165  * It also guarantees that this many requests may be handled in parallel if
03166  * there are no active calls for any other service. 
03167  * \li short minProcs - The minimum number of lightweight threads (hence
03168  * requests) guaranteed to be simultaneously executable. 
03169  * \li short connDeadTime - The number of seconds until a client of this
03170  * service will be declared to be dead, if it is not responding to the RPC
03171  * protocol. 
03172  * \li short idleDeadTime - The number of seconds a server-side connection for
03173  * this service will wait for packet I/O to resume after a quiescent period
03174  * before the connection is marked as dead. 
03175  * 
03176  *      \subsubsection sec5-3-2-2 Section 5.3.2.2: struct rx connection 
03177  * 
03178  * \par
03179  * An Rx connection represents an authenticated communication path, allowing
03180  * multiple asynchronous conversations (calls). Each connection is identified
03181  * by a connection ID. The low-order bits of the connection ID are reserved so
03182  * they may be stamped with the index of a particular call channel. With up to
03183  * RX MAXCALLS concurrent calls (set to 4 in this implementation), the bottom
03184  * two bits are set aside for this purpose. The connection ID is not sufficient
03185  * by itself to uniquely identify an Rx connection. Should a client crash and
03186  * restart, it may reuse a connection ID, causing inconsistent results. In
03187  * addition to the connection ID, the epoch, or start time for the client side
03188  * of the connection, is used to identify a connection. Should the above
03189  * scenario occur, a different epoch value will be chosen by the client,
03190  * differentiating this incarnation from the orphaned connection record on the
03191  * server side. 
03192  * \par
03193  * Each connection is associated with a parent service, which defines a set of
03194  * supported security models. At creation time, an Rx connection selects the
03195  * particular security protocol it will implement, referencing the associated
03196  * service. The connection structure maintains state about the individual calls
03197  * being simultaneously handled. 
03198  * \par
03199  * \b fields 
03200  * \li struct rx connection *next - Used for internal queueing. 
03201  * \li struct rx peer *peer - Pointer to the connection's peer information (see
03202  * below). 
03203  * \li u long epoch - Process start time of the client side of the connection. 
03204  * \li u long cid - Connection identifier. The call channel (i.e., the index
03205  * into the connection's array of call structures) may appear in the bottom
03206  * bits. 
03207  * \li VOID *rock - Pointer to an arbitrary region of memory in support of the
03208  * connection's operation. The contents of this area are opaque to the Rx
03209  * facility in general, but are understood by any special routines used by this
03210  * connection. 
03211  * \li struct rx call *call[RX MAXCALLS] - Pointer to the call channel
03212  * structures, describing up to RX MAXCALLS concurrent calls on this
03213  * connection. 
03214  * \li u long callNumber[RX MAXCALLS] - The set of current call numbers on each
03215  * of the call channels. 
03216  * \li int timeout - Obsolete; no longer used. 
03217  * \li u char flags - Various states of the connection; see Section 5.2.4 for
03218  * individual bit definitions. 
03219  * \li u char type - Whether the connection is a server-side or client-side
03220  * one. See Section 5.2.5 for individual bit definitions. 
03221  * \li u short serviceId - The service ID that should be stamped on requests.
03222  * This field is only used by client-side instances of connection structures. 
03223  * \li struct rx service *service - A pointer to the service structure
03224  * associated with this connection. This field is only used by server-side
03225  * instances of connection structures. 
03226  * \li u long serial - Serial number of the next outgoing packet associated
03227  * with this connection. 
03228  * \li u long lastSerial - Serial number of the last packet received in
03229  * association with this connection. This field is used in computing packet
03230  * skew. 
03231  * \li u short secondsUntilDead - Maximum numer of seconds of silence that
03232  * should be tolerated from the connection's peer before calls will be
03233  * terminated with an RX CALL DEAD error. 
03234  * \li u char secondsUntilPing - The number of seconds between "pings"
03235  * (keep-alive probes) when at least one call is active on this connection. 
03236  * \li u char securityIndex - The index of the security object being used by
03237  * this connection. This number selects a slot in the security class array
03238  * maintained by the service associated with the connection. 
03239  * \li long error - Records the latest error code for calls occurring on this
03240  * connection. 
03241  * \li struct rx securityClass *securityObject - A pointer to the security
03242  * object used by this connection. This should coincide with the slot value
03243  * chosen by the securityIndex field described above. 
03244  * \li VOID *securityData - A pointer to a region dedicated to hosting any
03245  * storage required by the security object being used by this connection. 
03246  * \li u short securityHeaderSize - The length in bytes of the portion of the
03247  * packet header before the user's data that contains the security module's
03248  * information. 
03249  * \li u short securityMaxTrailerSize - The length in bytes of the packet
03250  * trailer, appearing after the user's data, as mandated by the connection's
03251  * security module. 
03252  * \li struct rxevent *challengeEvent -Pointer to an event that is scheduled
03253  * when the server side of the connection is challenging the client to
03254  * authenticate itself. 
03255  * \li int lastSendTime - The last time a packet was sent on this connection. 
03256  * \li long maxSerial - The largest serial number seen on incoming packets. 
03257  * \li u short hardDeadTime - The maximum number of seconds that any call on
03258  * this connection may execute. This serves to throttle runaway calls. 
03259  * 
03260  *      \subsubsection sec5-3-2-3 Section 5.3.2.3: struct rx peer 
03261  * 
03262  * \par
03263  * For each connection, Rx maintains information describing the entity, or
03264  * peer, on the other side of the wire. A peer is identified by a (host,
03265  * UDP-port) pair. Included in the information kept on this remote
03266  * communication endpoint are such network parameters as the maximum packet
03267  * size supported by the host, current readings on round trip time to
03268  * retransmission delays, and packet skew (see Section 1.2.7). There are also
03269  * congestion control fields, ranging from descriptions of the maximum number
03270  * of packets that may be sent to the peer without pausing and retransmission
03271  * statistics. Peer structures are shared between connections whenever
03272  * possible, and hence are reference-counted. A peer object may be
03273  * garbage-collected if it is not actively referenced by any connection
03274  * structure and a sufficient period of time has lapsed since the reference
03275  * count dropped to zero. 
03276  * \par
03277  * \b fields 
03278  * \li struct rx peer *next - Use to access internal lists. 
03279  * \li u long host - Remote IP address, in network byte order 
03280  * \li u short port - Remote UDP port, in network byte order 
03281  * \li short packetSize - Maximum packet size for this host, if known. 
03282  * \li u long idleWhen - When the refCount reference count field (see below)
03283  * went to zero. 
03284  * \li short refCount - Reference count for this structure 
03285  * \li u char burstSize - Reinitialization size for the burst field (below). 
03286  * \li u char burst - Number of packets that can be transmitted immediately
03287  * without pausing. 
03288  * \li struct clock burstWait - Time delay until new burst aimed at this peer
03289  * is allowed. 
03290  * \li struct queue congestionQueue - Queue of RPC call descriptors that are
03291  * waiting for a non-zero burst value. 
03292  * \li int rtt - Round trip time to the peer, measured in milliseconds. 
03293  * \li struct clock timeout - Current retransmission delay to the peer. 
03294  * \li int nSent - Total number of distinct data packets sent, not including
03295  * retransmissions. 
03296  * \li int reSends - Total number of retransmissions for this peer since the
03297  * peer structure instance was created. 
03298  * \li u long inPacketSkew - Maximum skew on incoming packets (see Section
03299  * 1.2.7) 
03300  * \li u long outPacketSkew - Peer-reported maximum skew on outgoing packets
03301  * (see Section 1.2.7). 
03302  * 
03303  *      \subsubsection sec5-3-2-4 Section 5.3.2.4: struct rx call 
03304  * 
03305  * \par
03306  * This structure records the state of an active call proceeding on a given Rx
03307  * connection. As described above, each connection may have up to RX MAXCALLS
03308  * calls active at any one instant, and thus each connection maintains an array
03309  * of RX MAXCALLS rx call structures. The information contained here is
03310  * specific to the given call; "permanent" call state, such as the call number,
03311  * is maintained in the connection structure itself. 
03312  * \par
03313  * \b fields 
03314  * \li struct queue queue item header - Queueing information for this
03315  * structure. 
03316  * \li struct queue tq - Queue of outgoing ("transmit") packets. 
03317  * \li struct queue rq - Queue of incoming ("receive") packets. 
03318  * \li char *bufPtr - Pointer to the next byte to fill or read in the call's
03319  * current packet, depending on whether it is being transmitted or received. 
03320  * \li u short nLeft - Number of bytes left to read in the first packet in the
03321  * reception queue (see field rq). 
03322  * \li u short nFree - Number of bytes still free in the last packet in the
03323  * transmission queue (see field tq). 
03324  * \li struct rx packet *currentPacket - Pointer to the current packet being
03325  * assembled or read. 
03326  * \li struct rx connection *conn - Pointer to the parent connection for this
03327  * call. 
03328  * \li u long *callNumber - Pointer to call number field within the call's
03329  * current packet. 
03330  * \li u char channel - Index within the parent connection's call array that
03331  * describes this call. 
03332  * \li u char dummy1, dummy2 - These are spare fields, reserved for future use. 
03333  * \li u char state - Current call state. The associated bit definitions appear
03334  * in Section 5.2.7. 
03335  * \li u char mode - Current mode of a call that is in RX STATE ACTIVE state.
03336  * The associated bit definitions appear in Section 5.2.8. 
03337  * \li u char flags - Flags pertaining to the state of the given call. The
03338  * associated bit definitions appear in Section 5.2.7. 
03339  * \li u char localStatus - Local user status information, sent out of band.
03340  * This field is currently not in use, set to zero. 
03341  * \li u char remoteStatus - Remote user status information, received out of
03342  * band.  This field is currently not in use, set to zero. 
03343  * \li long error - Error condition for this call. 
03344  * \li u long timeout - High level timeout for this call 
03345  * \li u long rnext - Next packet sequence number expected to be received. 
03346  * \li u long rprev - Sequence number of the previous packet received. This
03347  * number is used to decide the proper sequence number for the next packet to
03348  * arrive, and may be used to generate a negative acknowledgement. 
03349  * \li u long rwind - Width of the packet receive window for this call. The
03350  * peer must not send packets with sequence numbers greater than or equal to
03351  * rnext + rwind. 
03352  * \li u long tfirst - Sequence number of the first unacknowledged transmit
03353  * packet for this call. 
03354  * \li u long tnext - Next sequence number to use for an outgoing packet. 
03355  * \li u long twind - Width of the packet transmit window for this call. Rx
03356  * cannot assign a sequence number to an outgoing packet greater than or equal
03357  * to tfirst + twind. 
03358  * \li struct rxevent *resendEvent - Pointer to a pending retransmission event,
03359  * if any. 
03360  * \li struct rxevent *timeoutEvent - Pointer to a pending timeout event, if
03361  * any. 
03362  * \li struct rxevent *keepAliveEvent - Pointer to a pending keep-alive event,
03363  * if this is an active call. 
03364  * \li struct rxevent *delayedAckEvent - Pointer to a pending delayed
03365  * acknowledgement packet event, if any. Transmission of a delayed
03366  * acknowledgement packet is scheduled after all outgoing packets for a call
03367  * have been sent. If neither a reply nor a new call are received by the time
03368  * the delayedAckEvent activates, the ack packet will be sent. 
03369  * \li int lastSendTime - Last time a packet was sent for this call. 
03370  * \li int lastReceiveTime - Last time a packet was received for this call. 
03371  * \li VOID (*arrivalProc)() - Pointer to the procedure to call when reply is
03372  * received. 
03373  * \li VOID *arrivalProcHandle - Pointer to the handle to pass to the
03374  * arrivalProc as its first argument. 
03375  * \li VOID *arrivalProcArg - Pointer to an additional argument to pass to the
03376  * given arrivalProc. 
03377  * \li u long lastAcked - Sequence number of the last packet "hard-acked" by
03378  * the receiver. A packet is considered to be hard-acked if an acknowledgement
03379  * is generated after the reader has processed it. The Rx facility may
03380  * sometimes "soft-ack" a windowfull of packets before they have been picked up
03381  * by the receiver. 
03382  * \li u long startTime - The time this call started running. 
03383  * \li u long startWait - The time that a server began waiting for input data
03384  * or send quota. 
03385  * 
03386  *      \subsection sec5-3-3 Section 5.3.3: Packet Formats 
03387  * 
03388  * \par
03389  * The following sections cover the different data formats employed by the
03390  * suite of Rx packet types, as enumerated in Section 5.2.11. A description of
03391  * the most commonly-employed Rx packet header appears first, immediately
03392  * followed by a description of the generic packet container and descriptor.
03393  * The formats for Rx acknowledgement packets and debugging/statistics packets
03394  * are also examined. 
03395  * 
03396  *      \subsubsection sec5-3-3-1 Section 5.3.3.1: struct rx header 
03397  * 
03398  * \par
03399  * Every Rx packet has its own header region, physically located after the
03400  * leading IP/UDP headers. This header contains connection, call, security, and
03401  * sequencing information. Along with a type identifier, these fields allow the
03402  * receiver to properly interpret the packet. In addition, every client relates
03403  * its "epoch", or Rx incarnation date, in each packet. This assists in
03404  * identifying protocol problems arising from reuse of connection identifiers
03405  * due to a client restart. Also included in the header is a byte of
03406  * user-defined status information, allowing out-of-band channel of
03407  * communication for the higher-level application using Rx as a transport
03408  * mechanism. 
03409  * \par
03410  * \b fields 
03411  * \li u long epoch - Birth time of the client Rx facility. 
03412  * \li u long cid - Connection identifier, as defined by the client. The last
03413  * RX CIDSHIFT bits in the cid field identify which of the server-side RX
03414  * MAXCALLS call channels is to receive the packet. 
03415  * \li u long callNumber - The current call number on the chosen call channel. 
03416  * \li u long seq - Sequence number of this packet. Sequence numbers start with
03417  * 0 for each new Rx call. 
03418  * \li u long serial - This packet's serial number. A new serial number is
03419  * stamped on each packet transmitted (or retransmitted). 
03420  * \li u char type - What type of Rx packet this is; see Section 5.2.11 for the
03421  * list of legal definitions. 
03422  * \li u char flags - Flags describing this packet; see Section 5.2.9 for the
03423  * list of legal settings. 
03424  * \li u char userStatus - User-defined status information, uninterpreted by
03425  * the Rx facility itself. This field may be easily set or retrieved from Rx
03426  * packets via calls to the rx GetLocalStatus(), rx SetLocalStatus(), rx
03427  * GetRemoteStatus(), and rx SetRemoteStatus() macros. 
03428  * \li u char securityIndex - Index in the associated server-side service class
03429  * of the security object used by this call. 
03430  * \li u short serviceId - The server-provided service ID to which this packet
03431  * is directed. 
03432  * \li u short spare - This field was originally a true spare, but is now used
03433  * by the built-in rxkad security module for packet header checksums. See the
03434  * descriptions of the related rx IsUsingPktChecksum(), rx GetPacketCksum(),
03435  * and rx SetPacketCksum() macros. 
03436  * 
03437  *      \subsubsection sec5-3-3-2 Section 5.3.3.2: struct rx packet 
03438  * 
03439  * \par
03440  * This structure is used to describe an Rx packet, and includes the wire
03441  * version of the packet contents, where all fields exist in network byte
03442  * order. It also includes acknowledgement, length, type, and queueing
03443  * information. 
03444  * \par
03445  * \b fields 
03446  * \li struct queue queueItemHeader - field used for internal queueing. 
03447  * \li u char acked - If non-zero, this field indicates that this packet has
03448  * been tentatively (soft-) acknowledged. Thus, the packet has been accepted by
03449  * the rx peer entity on the other side of the connection, but has not yet
03450  * necessarily been passed to the true reader. The sender is not free to throw
03451  * the packet away, as it might still get dropped by the peer before it is
03452  * delivered to its destination process. 
03453  * \li short length - Length in bytes of the user data section. 
03454  * \li u char packetType - The type of Rx packet described by this record. The
03455  * set of legal choices is available in Section 5.2.11. 
03456  * \li struct clock retryTime - The time when this packet should be
03457  * retransmitted next. 
03458  * \li struct clock timeSent - The last time this packet was transmitted. 
03459  * \li struct rx header header - A copy of the internal Rx packet header. 
03460  * \li wire - The text of the packet as it appears on the wire. This structure
03461  * has the following sub-fields: 
03462  *      \li u long head[RX HEADER SIZE/sizeof(long)] The wire-level contents of
03463  *      IP, UDP, and Rx headers. 
03464  *      \li u long data[RX MAX PACKET DATA SIZE/sizeof(long)] The wire form of
03465  *      the packet's "payload", namely the user data it carries. 
03466  * 
03467  *      \subsubsection sec5-3-3-3 Section 5.3.3.3: struct rx ackPacket 
03468  * 
03469  * \par
03470  * This is the format for the data portion of an Rx acknowledgement packet,
03471  * used to inform a peer entity performing packet transmissions that a subset
03472  * of its packets has been properly received. 
03473  * \par
03474  * \b fields 
03475  * \li u short bufferSpace - Number of packet buffers available. Specifically,
03476  * the number of packet buffers that the ack packet's sender is willing to
03477  * provide for data on this or subsequent calls. This number does not have to
03478  * fully accurate; it is acceptable for the sender to provide an estimate. 
03479  * \li u short maxSkew - The maximum difference seen between the serial number
03480  * of the packet being acknowledged and highest packet yet received. This is an
03481  * indication of the degree to which packets are arriving out of order at the
03482  * receiver. 
03483  * \li u long firstPacket - The serial number of the first packet in the list
03484  * of acknowledged packets, as represented by the acks field below. 
03485  * \li u long previousPacket - The previous packet serial number received. 
03486  * \li u long serial - The serial number of the packet prompted the
03487  * acknowledgement. 
03488  * \li u char reason - The reason given for the acknowledgement; legal values
03489  * for this field are described in Section 5.2.13. 
03490  * \li u char nAcks - Number of acknowledgements active in the acks array
03491  * immediately following. 
03492  * \li u char acks[RX MAXACKS] - Up to RX MAXACKS packet acknowledgements. The
03493  * legal values for each slot in the acks array are described in Section
03494  * 5.2.14. Basically, these fields indicate either positive or negative
03495  * acknowledgements. 
03496  * 
03497  * \par
03498  * All packets with serial numbers prior to firstPacket are implicitly
03499  * acknowledged by this packet, indicating that they have been fully processed
03500  * by the receiver. Thus, the sender need no longer be concerned about them,
03501  * and may release all of the resources that they occupy. Packets with serial
03502  * numbers firstPacket + nAcks and higher are not acknowledged by this ack
03503  * packet. Packets with serial numbers in the range [firstPacket, firstPacket +
03504  * nAcks) are explicitly acknowledged, yet their sender-side resources must not
03505  * yet be released, as there is yet no guarantee that the receiver will not
03506  * throw them away before they can be processed there. 
03507  * \par
03508  * There are some details of importance to be noted. For one, receiving a
03509  * positive acknowlegement via the acks array does not imply that the
03510  * associated packet is immune from being dropped before it is read and
03511  * processed by the receiving entity. It does, however, imply that the sender
03512  * should stop retransmitting the packet until further notice. Also, arrival of
03513  * an ack packet should prompt the transmitter to immediately retransmit all
03514  * packets it holds that have not been explicitly acknowledged and that were
03515  * last transmitted with a serial number less than the highest serial number
03516  * acknowledged by the acks array. 
03517  * Note: The fields in this structure are always kept in wire format, namely in
03518  * network byte order. 
03519  * 
03520  *      \subsection sec5-3-4 Section 5.3.4: Debugging and Statistics 
03521  * 
03522  * \par
03523  * The following structures are defined in support of the debugging and
03524  * statistics-gathering interfaces provided by Rx. 
03525  * 
03526  *      \subsubsection sec5-3-4-1 Section 5.3.4.1: struct rx stats 
03527  * 
03528  * \par
03529  * This structure maintains Rx statistics, and is gathered by such tools as the
03530  * rxdebug program. It must be possible for all of the fields placed in this
03531  * structure to be successfully converted from their on-wire network byte
03532  * orderings to the host-specific ordering. 
03533  * \par
03534  * \b fields 
03535  * \li int packetRequests - Number of packet allocation requests processed. 
03536  * \li int noPackets[RX N PACKET CLASSES] - Number of failed packet requests,
03537  * organized per allocation class. 
03538  * \li int socketGreedy - Whether the SO GREEDY setting succeeded for the Rx
03539  * socket. 
03540  * \li int bogusPacketOnRead - Number of inappropriately short packets
03541  * received. 
03542  * \li int bogusHost - Contains the host address from the last bogus packet
03543  * received. 
03544  * \li int noPacketOnRead - Number of attempts to read a packet off the wire
03545  * when there was actually no packet there. 
03546  * \li int noPacketBuffersOnRead - Number of dropped data packets due to lack
03547  * of packet buffers. 
03548  * \li int selects - Number of selects waiting for a packet arrival or a
03549  * timeout. 
03550  * \li int sendSelects - Number of selects forced when sending packets. 
03551  * \li int packetsRead[RX N PACKET TYPES] - Total number of packets read,
03552  * classified by type. 
03553  * \li int dataPacketsRead - Number of unique data packets read off the wire. 
03554  * \li int ackPacketsRead - Number of ack packets read. 
03555  * \li int dupPacketsRead - Number of duplicate data packets read. 
03556  * \li int spuriousPacketsRead - Number of inappropriate data packets. 
03557  * \li int packetsSent[RX N PACKET TYPES] - Number of packet transmissions,
03558  * broken down by packet type. 
03559  * \li int ackPacketsSent - Number of ack packets sent. 
03560  * \li int pingPacketsSent - Number of ping packets sent. 
03561  * \li int abortPacketsSent - Number of abort packets sent. 
03562  * \li int busyPacketsSent - Number of busy packets sent. 
03563  * \li int dataPacketsSent - Number of unique data packets sent. 
03564  * \li int dataPacketsReSent - Number of retransmissions. 
03565  * \li int dataPacketsPushed - Number of retransmissions pushed early by a
03566  * negative acknowledgement. 
03567  * \li int ignoreAckedPacket - Number of packets not retransmitted because they
03568  * have already been acked. 
03569  * \li int struct clock totalRtt - Total round trip time measured for packets,
03570  * used to compute average time figure. 
03571  * \li struct clock minRtt - Minimum round trip time measured for packets. 
03572  * struct clock maxRtt - Maximum round trip time measured for packets. 
03573  * \li int nRttSamples - Number of round trip samples. 
03574  * \li int nServerConns - Number of server connections. 
03575  * \li int nClientConns - Number of client connections. 
03576  * \li int nPeerStructs - Number of peer structures. 
03577  * \li int nCallStructs - Number of call structures physically allocated (using
03578  * the internal storage allocator routine). 
03579  * \li int nFreeCallStructs - Number of call structures which were pulled from
03580  * the free queue, thus avoiding a call to the internal storage allocator
03581  * routine. 
03582  * \li int spares[10] - Ten integer spare fields, reserved for future use. 
03583  * 
03584  *      \subsubsection sec5-3-4-2 Section 5.3.4.2: struct rx debugIn 
03585  * 
03586  * \par
03587  * This structure defines the data format for a packet requesting one of the
03588  * statistics collections maintained by Rx. 
03589  * \par
03590  * \b fields 
03591  * \li long type - The specific data collection that the caller desires. Legal
03592  * settings for this field are described in Section 5.2.16.2. 
03593  * \li long index - This field is only used when gathering information on Rx
03594  * connections. Choose the index of the server-side connection record of which
03595  * we are inquiring. This field may be used as an iterator, stepping through
03596  * all the connection records, one per debugging request, until they have all
03597  * been examined. 
03598  * 
03599  *      \subsubsection sec5-3-4-3 Section 5.3.4.3: struct rx debugStats 
03600  * 
03601  * \par
03602  * This structure describes the data format for a reply to an RX DEBUGI
03603  * GETSTATS debugging request packet. These fields are given values indicating
03604  * the current state of the Rx facility. 
03605  * \par
03606  * \b fields 
03607  * \li long nFreePackets - Number of packet buffers currently assigned to the
03608  * free pool. 
03609  * \li long packetReclaims - Currently unused. 
03610  * \li long callsExecuted - Number of calls executed since the Rx facility was
03611  * initialized. 
03612  * \li char waitingForPackets - Is Rx currently blocked waiting for a packet
03613  * buffer to come free? 
03614  * \li char usedFDs - If the Rx facility is executing in the kernel, return the
03615  * number of unix file descriptors in use. This number is not directly related
03616  * to the Rx package, but rather describes the state of the machine on which Rx
03617  * is running. 
03618  * \li char version - Version number of the debugging package. 
03619  * \li char spare1[1] - Byte spare, reserved for future use. 
03620  * \li long spare2[10] - Set of 10 longword spares, reserved for future use. 
03621  * 
03622  *      \subsubsection sec5-3-4-4 Section 5.3.4.4: struct rx debugConn 
03623  * 
03624  * \par
03625  * This structure defines the data format returned when a caller requests
03626  * information concerning an Rx connection. Thus, rx debugConn defines the
03627  * external packaging of interest to external parties. Most of these fields are
03628  * set from the rx connection structure, as defined in Section 5.3.2.2, and
03629  * others are obtained by indirecting through such objects as the connection's
03630  * peer and call structures. 
03631  * \par
03632  * \b fields 
03633  * \li long host - Address of the host identified by the connection's peer
03634  * structure. 
03635  * \li long cid - The connection ID. 
03636  * \li long serial - The serial number of the next outgoing packet associated
03637  * with this connection. 
03638  * \li long callNumber[RX MAXCALLS] - The current call numbers for the
03639  * individual call channels on this connection. 
03640  * \li long error - Records the latest error code for calls occurring on this
03641  * connection. 
03642  * \li short port - UDP port associated with the connection's peer. 
03643  * \li char flags - State of the connection; see Section 5.2.4 for individual
03644  * bit definitions. 
03645  * \li char type - Whether the connection is a server-side or client-side one.
03646  * See Section 5.2.5 for individual bit definitions. 
03647  * \li char securityIndex - Index in the associated server-side service class
03648  * of the security object being used by this call. 
03649  * \li char sparec[3] - Used to force alignment for later fields. 
03650  * \li char callState[RX MAXCALLS] - Current call state on each call channel.
03651  * The associated bit definitions appear in Section 5.2.7. 
03652  * \li char callMode[RX MAXCALLS] - Current mode of all call channels that are
03653  * in RX STATE ACTIVE state. The associated bit definitions appear in Section
03654  * 5.2.8. 
03655  * \li char callFlags[RX MAXCALLS] - Flags pertaining to the state of each of
03656  * the connection's call channels. The associated bit definitions appear in
03657  * Section 5.2.7. 
03658  * \li char callOther[RX MAXCALLS] - Flag field for each call channel, where
03659  * the presence of the RX OTHER IN flag indicates that there are packets
03660  * present on the given call's reception queue, and the RX OTHER OUT flag
03661  * indicates the presence of packets on the transmission queue. 
03662  * \li struct rx securityObjectStats secStats - The contents of the statistics
03663  * related to the security object selected by the securityIndex field, if any. 
03664  * \li long epoch - The connection's client-side incarnation time. 
03665  * \li long sparel[10] - A set of 10 longword fields, reserved for future use. 
03666  * 
03667  *      \subsubsection sec5-3-4-5 Section 5.3.4.5: struct rx debugConn vL 
03668  * 
03669  * \par
03670  * This structure is identical to rx debugConn defined above, except for the
03671  * fact that it is missing the sparec field. This sparec field is used in rx
03672  * debugConn to fix an alignment problem that was discovered in version L of
03673  * the debugging/statistics interface (hence the trailing "tt vL tag in the
03674  * structure name). This alignment problem is fixed in version M, which
03675  * utilizes and exports the rx debugConn structure exclusively. Information
03676  * regarding the range of version-numbering values for the Rx
03677  * debugging/statistics interface may be found in Section 5.2.16.1. 
03678  *      \section sec5-4 Section 5.4: Exported Variables 
03679  * 
03680  * \par
03681  * This section describes the set of variables that the Rx facility exports to
03682  * its applications. Some of these variables have macros defined for the sole
03683  * purpose of providing the caller with a convenient way to manipulate them.
03684  * Note that some of these exported variables are never meant to be altered by
03685  * application code (e.g., rx nPackets). 
03686  * 
03687  *      \subsection sec5-4-1 Section 5.4.1: rx connDeadTime 
03688  * 
03689  * \par
03690  * This integer-valued variable determines the maximum number of seconds that a
03691  * connection may remain completely inactive, without receiving packets of any
03692  * kind, before it is eligible for garbage collection. Its initial value is 12
03693  * seconds. The rx SetRxDeadTime macro sets the value of this variable. 
03694  * 
03695  *      \subsection sec5-4-2 Section 5.4.2: rx idleConnectionTime 
03696  * 
03697  * \par
03698  * This integer-valued variable determines the maximum number of seconds that a
03699  * server connection may "idle" (i.e., not have any active calls and otherwise
03700  * not have sent a packet) before becoming eligible for garbage collection. Its
03701  * initial value is 60 seconds. 
03702  * 
03703  *      \subsection sec5-4-3 Section 5.4.3: rx idlePeerTime 
03704  * 
03705  * \par
03706  * This integer-valued variable determines the maximum number of seconds that
03707  * an Rx peer structure is allowed to exist without any connection structures
03708  * referencing it before becoming eligible for garbage collection. Its initial
03709  * value is 60 seconds. 
03710  * 
03711  *      \subsection sec5-4-4 Section 5.4.4: rx extraQuota 
03712  * 
03713  * \par
03714  * This integer-valued variable is part of the Rx packet quota system (see
03715  * Section 1.2.6), which is used to avoid system deadlock. This ensures that
03716  * each server-side thread has a minimum number of packets at its disposal,
03717  * allowing it to continue making progress on active calls. This particular
03718  * variable records how many extra data packets a user has requested be
03719  * allocated. Its initial value is 0. 
03720  * 
03721  *      \subsection sec5-4-5 Section 5.4.5: rx extraPackets 
03722  * 
03723  * \par
03724  * This integer-valued variable records how many additional packet buffers are
03725  * to be created for each Rx server thread. The caller, upon setting this
03726  * variable, is applying some application-specific knowledge of the level of
03727  * network activity expected. The rx extraPackets variable is used to compute
03728  * the overall number of packet buffers to reserve per server thread, namely rx
03729  * nPackets, described below. The initial value is 32 packets. 
03730  * 
03731  *      \subsection sec5-4-6 Section 5.4.6: rx nPackets 
03732  * 
03733  * \par
03734  * This integer-valued variable records the total number of packet buffers to
03735  * be allocated per Rx server thread. It takes into account the quota packet
03736  * buffers and the extra buffers requested by the caller, if any. 
03737  * \note This variable should never be set directly; the Rx facility itself
03738  * computes its value. Setting it incorrectly may result in the service
03739  * becoming deadlocked due to insufficient resources. Callers wishing to
03740  * allocate more packet buffers to their server threads should indicate that
03741  * desire by setting the rx extraPackets variable described above. 
03742  * 
03743  *      \subsection sec5-4-7 Section 5.4.7: rx nFreePackets 
03744  * 
03745  * \par
03746  * This integer-valued variable records the number of Rx packet buffers not
03747  * currently used by any call. These unused buffers are collected into a free
03748  * pool. 
03749  * 
03750  *      \subsection sec5-4-8 Section 5.4.8: rx stackSize 
03751  * 
03752  * \par
03753  * This integer-valued variable records the size in bytes for the lightweight
03754  * process stack. The variable is initially set to RX DEFAULT STACK SIZE, and
03755  * is typically manipulated via the rx SetStackSize() macro. 
03756  * 
03757  *      \subsection sec5-4-9 Section 5.4.9: rx packetTypes 
03758  * 
03759  * \par
03760  * This variable holds an array of string names used to describe the different
03761  * roles for Rx packets. Its value is derived from the RX PACKET TYPES
03762  * definition found in Section 5.2.11. 
03763  * 
03764  *      \subsection sec5-4-10 Section 5.4.10: rx stats 
03765  * 
03766  * \par
03767  * This variable contains the statistics structure that keeps track of Rx
03768  * statistics. The struct rx stats structure it provides is defined in Section
03769  * 5.3.4.1. 
03770  * 
03771  *      \section sec5-5 Section 5.5: Macros 
03772  * 
03773  * \par
03774  * Rx uses many macro definitions in preference to calling C functions
03775  * directly. There are two main reasons for doing this: 
03776  * \li field selection: Many Rx operations are easily realized by returning the
03777  * value of a particular structure's field. It is wasteful to invoke a C
03778  * routine to simply fetch a structure's field, incurring unnecessary function
03779  * call overhead. Yet, a convenient, procedure-oriented operation is still
03780  * provided to Rx clients for such operations by the use of macros. For
03781  * example, the rx ConnectionOf() macro, described in Section 5.5.1.1, simply
03782  * indirects through the Rx call structure pointer parameter to deliver the
03783  * conn field. 
03784  * \li Performance optimization: In some cases, a simple test or operation can
03785  * be performed to accomplish a particular task. When this simple,
03786  * straightforward operation fails, then a true C routine may be called to
03787  * handle to more complex (and rarer) situation. The Rx macro rx Write(),
03788  * described in Section 5.5.6.2, is a perfect example of this type of
03789  * optimization. Invoking rx Write() first checks to determine whether or not
03790  * the outgoing call's internal buffer has enough room to accept the specified
03791  * data bytes. If so, it copies them into the call's buffer, updating counts
03792  * and pointers as appropriate. Otherwise, rx Write() calls the rx WriteProc()
03793  * to do the work, which in this more complicated case involves packet
03794  * manipulations, dispatches, and allocations. The result is that the common,
03795  * simple cases are often handled in-line, with more complex (and rarer) cases
03796  * handled through true function invocations. 
03797  * \par
03798  * The set of Rx macros is described according to the following categories. 
03799  * \li field selections/assignments 
03800  * \li Boolean operations 
03801  * \li Service attributes 
03802  * \li Security-related operations 
03803  * \li Sizing operations 
03804  * \li Complex operation 
03805  * \li Security operation invocations 
03806  * 
03807  *      \subsection sec5-5-1 Section 5.5.1: field Selections/Assignments 
03808  * 
03809  * \par
03810  * These macros facilitate the fetching and setting of fields from the
03811  * structures described Chapter 5.3. 
03812  * 
03813  *      \subsubsection sec5-5-1-1 Section 5.5.1.1: rx ConnectionOf() 
03814  * 
03815  * \par
03816  * \#define rx_ConnectionOf(call) ((call)->conn) 
03817  * \par
03818  * Generate a reference to the connection field within the given Rx call
03819  * structure. The value supplied as the call argument must resolve into an
03820  * object of type (struct rx call *). An application of the rx ConnectionOf()
03821  * macro itself yields an object of type rx peer. 
03822  * 
03823  *      \subsubsection sec5-5-1-2 Section 5.5.1.2: rx PeerOf() 
03824  * 
03825  * \par
03826  * \#define rx_PeerOf(conn) ((conn)->peer) 
03827  * \par
03828  * Generate a reference to the peer field within the given Rx call structure.
03829  * The value supplied as the conn argument must resolve into an object of type
03830  * (struct rx connection *). An instance of the rx PeerOf() macro itself
03831  * resolves into an object of type rx peer. 
03832  * 
03833  *      \subsubsection sec5-5-1-3 Section 5.5.1.3: rx HostOf() 
03834  * 
03835  * \par
03836  * \#define rx_HostOf(peer) ((peer)->host) 
03837  * \par
03838  * Generate a reference to the host field within the given Rx peer structure.
03839  * The value supplied as the peer argument must resolve into an object of type
03840  * (struct rx peer *). An instance of the rx HostOf() macro itself resolves
03841  * into an object of type u long. 
03842  * 
03843  *      \subsubsection sec5-5-1-4 Section 5.5.1.4: rx PortOf() 
03844  * 
03845  * \par
03846  * \#define rx_PortOf(peer) ((peer)->port) 
03847  * \par
03848  * Generate a reference to the port field within the given Rx peer structure.
03849  * The value supplied as the peer argument must resolve into an object of type
03850  * (struct rx peer *). An instance of the rx PortOf() macro itself resolves
03851  * into an object of type u short. 
03852  * 
03853  *      \subsubsection sec5-5-1-5 Section 5.5.1.5: rx GetLocalStatus() 
03854  * 
03855  * \par
03856  * \#define rx_GetLocalStatus(call, status) ((call)->localStatus) 
03857  * \par
03858  * Generate a reference to the localStatus field, which specifies the local
03859  * user status sent out of band, within the given Rx call structure. The value
03860  * supplied as the call argument must resolve into an object of type (struct rx
03861  * call *). The second argument, status, is not used. An instance of the rx
03862  * GetLocalStatus() macro itself resolves into an object of type u char. 
03863  * 
03864  *      \subsubsection sec5-5-1-6 Section 5.5.1.6: rx SetLocalStatus() 
03865  * 
03866  * \par
03867  * \#define rx_SetLocalStatus(call, status) ((call)->localStatus = (status)) 
03868  * \par
03869  * Assign the contents of the localStatus field, which specifies the local user
03870  * status sent out of band, within the given Rx call structure. The value
03871  * supplied as the call argument must resolve into an object of type (struct rx
03872  * call *). The second argument, status, provides the new value of the
03873  * localStatus field, and must resolve into an object of type u char. An
03874  * instance of the rx GetLocalStatus() macro itself resolves into an object
03875  * resulting from the assignment, namely the u char status parameter. 
03876  * 
03877  *      \subsubsection sec5-5-1-7 Section 5.5.1.7: rx GetRemoteStatus() 
03878  * 
03879  * \par
03880  * \#define rx_GetRemoteStatus(call) ((call)->remoteStatus) 
03881  * \par
03882  * Generate a reference to the remoteStatus field, which specifies the remote
03883  * user status received out of band, within the given Rx call structure. The
03884  * value supplied as the call argument must resolve into an object of type
03885  * (struct rx call *). An instance of the rx GetRemoteStatus() macro itself
03886  * resolves into an object of type u char. 
03887  * 
03888  *      \subsubsection sec5-5-1-8 Section 5.5.1.8: rx Error() 
03889  * 
03890  * \par
03891  * \#define rx_Error(call) ((call)->error) 
03892  * \par
03893  * Generate a reference to the error field, which specifies the current error
03894  * condition, within the given Rx call structure. The value supplied as the
03895  * call argument must resolve into an object of type (struct rx call *). An
03896  * instance of the rx Error() macro itself resolves into an object of type
03897  * long. 
03898  * 
03899  *      \subsubsection sec5-5-1-9 Section 5.5.1.9: rx DataOf() 
03900  * 
03901  * \par
03902  * \#define rx_DataOf(packet) ((char *) (packet)->wire.data) 
03903  * \par
03904  * Generate a reference to the beginning of the data portion within the given
03905  * Rx packet as it appears on the wire. Any encryption headers will be resident
03906  * at this address. For Rx packets of type RX PACKET TYPE DATA, the actual user
03907  * data will appear at the address returned by the rx DataOf macro plus the
03908  * connection's security header size. The value supplied as the packet argument
03909  * must resolve into an object of type (struct rx packet *). An instance of the
03910  * rx DataOf() macro itself resolves into an object of type (u long *). 
03911  * 
03912  *      \subsubsection sec5-5-1-10 Section 5.5.1.10: rx GetDataSize() 
03913  * 
03914  * \par
03915  * \#define rx_GetDataSize(packet) ((packet)->length) 
03916  * \par
03917  * Generate a reference to the length field, which specifies the number of
03918  * bytes of user data contained within the wire form of the packet, within the
03919  * given Rx packet description structure. The value supplied as the packet
03920  * argument must resolve into an object of type (struct rx packet *). An
03921  * instance of the rx GetDataSize() macro itself resolves into an object of
03922  * type short. 
03923  * 
03924  *      \subsubsection sec5-5-1-11 Section 5.5.1.11: rx SetDataSize() 
03925  * 
03926  * \par
03927  * \#define rx_SetDataSize(packet, size) ((packet)->length = (size)) 
03928  * \par
03929  * Assign the contents of the length field, which specifies the number of bytes
03930  * of user data contained within the wire form of the packet, within the given
03931  * Rx packet description structure. The value supplied as the packet argument
03932  * must resolve into an object of type (struct rx packet *). The second
03933  * argument, size, provides the new value of the length field, and must resolve
03934  * into an object of type short. An instance of the rx SetDataSize() macro
03935  * itself resolves into an object resulting from the assignment, namely the
03936  * short length parameter. 
03937  * 
03938  *      \subsubsection sec5-5-1-12 Section 5.5.1.12: rx GetPacketCksum() 
03939  * 
03940  * \par
03941  * \#define rx_GetPacketCksum(packet) ((packet)->header.spare) 
03942  * \par
03943  * Generate a reference to the header checksum field, as used by the built-in
03944  * rxkad security module (See Chapter 3), within the given Rx packet
03945  * description structure. The value supplied as the packet argument must
03946  * resolve into an object of type (struct rx packet *). An instance of the rx
03947  * GetPacketCksum() macro itself resolves into an object of type u short. 
03948  * 
03949  *      \subsubsection sec5-5-1-13 Section 5.5.1.13: rx SetPacketCksum() 
03950  * 
03951  * \par
03952  * \#define rx_SetPacketCksum(packet, cksum) ((packet)->header.spare = (cksum)) 
03953  * \par
03954  * Assign the contents of the header checksum field, as used by the built-in
03955  * rxkad security module (See Chapter 3), within the given Rx packet
03956  * description structure. The value supplied as the packet argument must
03957  * resolve into an object of type (struct rx packet *). The second argument,
03958  * cksum, provides the new value of the checksum, and must resolve into an
03959  * object of type u short. An instance of the rx SetPacketCksum() macro itself
03960  * resolves into an object resulting from the assignment, namely the u short
03961  * checksum parameter. 
03962  * 
03963  *      \subsubsection sec5-5-1-14 Section 5.5.1.14: rx GetRock() 
03964  * 
03965  * \par
03966  * \#define rx_GetRock(obj, type) ((type)(obj)->rock) 
03967  * \par
03968  * Generate a reference to the field named rock within the object identified by
03969  * the obj pointer. One common Rx structure to which this macro may be applied
03970  * is struct rx connection. The specified rock field is casted to the value of
03971  * the type parameter, which is the overall value of the rx GetRock() macro. 
03972  * 
03973  *      \subsubsection sec5-5-1-15 Section 5.5.1.15: rx SetRock() 
03974  * 
03975  * \par
03976  * \#define rx_SetRock(obj, newrock) ((obj)->rock = (VOID *)(newrock)) 
03977  * \par
03978  * Assign the contents of the newrock parameter into the rock field of the
03979  * object pointed to by obj. The given object's rock field must be of type
03980  * (VOID *). An instance of the rx SetRock() macro itself resolves into an
03981  * object resulting from the assignment and is of type (VOID *). 
03982  * 
03983  *      \subsubsection sec5-5-1-16 Section 5.5.1.16: rx SecurityClassOf() 
03984  * 
03985  * \par
03986  * \#define rx_SecurityClassOf(conn) ((conn)->securityIndex) 
03987  * \par
03988  * Generate a reference to the security index field of the given Rx connection
03989  * description structure. This identifies the security class used by the
03990  * connection. The value supplied as the conn argument must resolve into an
03991  * object of type (struct rx connection *). An instance of the rx
03992  * SecurityClassOf() macro itself resolves into an object of type u char. 
03993  * 
03994  *      \subsubsection sec5-5-1-17 Section 5.5.1.17: rx SecurityObjectOf() 
03995  * 
03996  * \par
03997  * \#define rx_SecurityObjectOf(conn) ((conn)->securityObject) 
03998  * \par
03999  * Generate a reference to the security object in use by the given Rx
04000  * connection description structure. The choice of security object determines
04001  * the authentication protocol enforced by the connection. The value supplied
04002  * as the conn argument must resolve into an object of type (struct rx
04003  * connection *). An instance of the rx SecurityObjectOf() macro itself
04004  * resolves into an object of type (struct rx securityClass *). 
04005  * 
04006  *      \subsection sec5-5-2 Section 5.5.2: Boolean Operations 
04007  * 
04008  * \par
04009  * The macros described in this section all return Boolean values. They are
04010  * used to query such things as the whether a connection is a server-side or
04011  * client-side one and if extra levels of checksumming are being used in Rx
04012  * packet headers. 
04013  * 
04014  *      \subsubsection sec5-5-2-1 Section 5.5.2.1: rx IsServerConn() 
04015  * 
04016  * \par
04017  * \#define rx_IsServerConn(conn) ((conn)->type == RX_SERVER_CONNECTION) 
04018  * \par
04019  * Determine whether or not the Rx connection specified by the conn argument is
04020  * a server-side connection. The value supplied for conn must resolve to an
04021  * object of type struct rx connection. The result is determined by testing
04022  * whether or not the connection's type field is set to RX SERVER CONNECTION. 
04023  * \note Another macro, rx ServerConn(), performs the identical operation. 
04024  * 
04025  *      \subsubsection sec5-5-2-2 Section 5.5.2.2: rx IsClientConn() 
04026  * 
04027  * \par
04028  * \#define rx_IsClientConn(conn) ((conn)->type == RX_CLIENT_CONNECTION) 
04029  * \par
04030  * Determine whether or not the Rx connection specified by the conn argument is
04031  * a client-side connection. The value supplied for conn must resolve to an
04032  * object of type struct rx connection. The result is determined by testing
04033  * whether or not the connection's type field is set to RX CLIENT CONNECTION. 
04034  * \note Another macro, rx ClientConn(), performs the identical operation. 
04035  * 
04036  *      \subsubsection sec5-5-2-3 Section 5.5.2.2: rx IsUsingPktCksum() 
04037  * 
04038  * \par
04039  * \#define rx_IsUsingPktCksum(conn) ((conn)->flags &
04040  * RX_CONN_USING_PACKET_CKSUM) 
04041  * \par
04042  * Determine whether or not the Rx connection specified by the conn argument is
04043  * checksum-ming the headers of all packets on its calls. The value supplied
04044  * for conn must resolve to an object of type struct rx connection. The result
04045  * is determined by testing whether or not the connection's flags field has the
04046  * RX CONN USING PACKET CKSUM bit enabled. 
04047  * 
04048  *      \subsection sec5-5-3 Section 5.5.3: Service Attributes 
04049  * 
04050  * \par
04051  * This section describes user-callable macros that manipulate the attributes
04052  * of an Rx service. Note that these macros must be called (and hence their
04053  * operations performed) before the given service is installed via the
04054  * appropriate invocation of the associated rx StartServer() function.
04055  * 
04056  *      \subsubsection sec5-5-3-1 Section 5.5.3.1: rx SetStackSize()
04057  * 
04058  * \par
04059  * rx_stackSize = (((stackSize) stackSize) > rx_stackSize) ? stackSize :
04060  * rx_stackSize) 
04061  * \par
04062  * Inform the Rx facility of the stack size in bytes for a class of threads to
04063  * be created in support of Rx services. The exported rx stackSize variable
04064  * tracks the high-water mark for all stack size requests before the call to rx
04065  * StartServer(). If no calls to rx SetStackSize() are made, then rx stackSize
04066  * will retain its default setting of RX DEFAULT STACK SIZE. 
04067  * \par
04068  * In this macro, the first argument is not used. It was originally intended
04069  * that thread stack sizes would be settable on a per-service basis. However,
04070  * calls to rx SetStackSize() will ignore the service parameter and set the
04071  * high-water mark for all Rx threads created after the use of rx
04072  * SetStackSize(). The second argument, stackSize, specifies determines the new
04073  * stack size, and should resolve to an object of type int. The value placed in
04074  * the stackSize parameter will not be recorded in the global rx stackSize
04075  * variable unless it is greater than the variable's current setting. 
04076  * \par
04077  * An instance of the rx SetStackSize() macro itself resolves into the result
04078  * of the assignment, which is an object of type int. 
04079  * 
04080  *      \subsubsection sec5-5-3-2 Section 5.5.3.2: rx SetMinProcs() 
04081  * 
04082  * \par
04083  * \#define rx_SetMinProcs(service, min) ((service)->minProcs = (min)) 
04084  * \par
04085  * Choose min as the minimum number of threads guaranteed to be available for
04086  * parallel execution of the given Rx service. The service parameter should
04087  * resolve to an object of type struct rx service. The min parameter should
04088  * resolve to an object of type short. An instance of the rx SetMinProcs()
04089  * macro itself resolves into the result of the assignment, which is an object
04090  * of type short. 
04091  * 
04092  *      \subsubsection sec5-5-3-3 Section 5.5.3.3: rx SetMaxProcs() 
04093  * 
04094  * \par
04095  * \#define rx_SetMaxProcs(service, max) ((service)->maxProcs = (max)) 
04096  * \par
04097  * Limit the maximum number of threads that may be made available to the given
04098  * Rx service for parallel execution to be max. The service parameter should
04099  * resolve to an object of type struct rx service. The max parameter should
04100  * resolve to an object of type short. An instance of the rx SetMaxProcs()
04101  * macro itself resolves into the result of the assignment, which is an object
04102  * of type short. 
04103  * 
04104  *      \subsubsection sec5-5-3-4 Section 5.5.3.4: rx SetIdleDeadTime() 
04105  * 
04106  * \par
04107  * \#define rx_SetIdleDeadTime(service, time) ((service)->idleDeadTime =
04108  * (time)) 
04109  * \par
04110  * Every Rx service has a maximum amount of time it is willing to have its
04111  * active calls sit idle (i.e., no new data is read or written for a call
04112  * marked as RX STATE ACTIVE) before unilaterally shutting down the call. The
04113  * expired call will have its error field set to RX CALL TIMEOUT. The operative
04114  * assumption in this situation is that the client code is exhibiting a
04115  * protocol error that prevents progress from being made on this call, and thus
04116  * the call's resources on the server side should be freed. The default value,
04117  * as recorded in the service's idleDeadTime field, is set at service creation
04118  * time to be 60 seconds. The rx SetIdleTime() macro allows a caller to
04119  * dynamically set this idle call timeout value. 
04120  * \par
04121  * The service parameter should resolve to an object of type struct rx service.
04122  * Also, the time parameter should resolve to an object of type short. finally,
04123  * an instance of the rx SetIdleDeadTime() macro itself resolves into the
04124  * result of the assignment, which is an object of type short. 
04125  * 
04126  *      \subsubsection sec5-5-3-5 Section 5.5.3.5: rx SetServiceDeadTime() 
04127  * 
04128  * \par
04129  * \#define rx_SetServiceDeadTime(service, seconds)
04130  * ((service)->secondsUntilDead = (seconds)) 
04131  * \note This macro definition is obsolete and should NOT be used. Including it
04132  * in application code will generate a compile-time error, since the service
04133  * structure no longer has such a field defined. 
04134  * \par
04135  * See the description of the rx SetConnDeadTime() macro below to see how hard
04136  * timeouts may be set for situations of complete call inactivity. 
04137  * 
04138  *      \subsubsection sec5-5-3-6 Section 5.5.3.6: rx SetRxDeadTime() 
04139  * 
04140  * \par
04141  * \#define rx_SetRxDeadTime(seconds) (rx_connDeadTime = (seconds)) 
04142  * \par
04143  * Inform the Rx facility of the maximum number of seconds of complete
04144  * inactivity that will be tolerated on an active call. The exported rx
04145  * connDeadTime variable tracks this value, and is initialized to a value of 12
04146  * seconds. The current value of rx connDeadTime will be copied into new Rx
04147  * service and connection records upon their creation. 
04148  * \par
04149  * The seconds argument determines the value of rx connDeadTime, and should
04150  * resolve to an object of type int. An instance of the rx SetRxDeadTime()
04151  * macro itself resolves into the result of the assignment, which is an object
04152  * of type int. 
04153  * 
04154  *      \subsubsection sec5-5-3-7 Section 5.5.3.7: rx SetConnDeadTime() 
04155  * 
04156  * \par
04157  * \#define rx_SetConnDeadTime(conn, seconds) (rxi_SetConnDeadTime(conn,
04158  * seconds)) 
04159  * \par
04160  * Every Rx connection has a maximum amount of time it is willing to have its
04161  * active calls on a server connection sit without receiving packets of any
04162  * kind from its peer. After such a quiescent time, during which neither data
04163  * packets (regardless of whether they are properly sequenced or duplicates)
04164  * nor keep-alive packets are received, the call's error field is set to RX
04165  * CALL DEAD and the call is terminated. The operative assumption in this
04166  * situation is that the client making the call has perished, and thus the
04167  * call's resources on the server side should be freed. The default value, as
04168  * recorded in the connection's secondsUntilDead field, is set at connection
04169  * creation time to be the same as its parent service. The rx SetConnDeadTime()
04170  * macro allows a caller to dynamically set this timeout value. 
04171  * \par
04172  * The conn parameter should resolve to an object of type struct rx connection.
04173  * Also, the seconds parameter should resolve to an object of type int.
04174  * finally, an instance of the rx SetConnDeadTime() macro itself resolves into
04175  * the a call to rxi SetConnDeadTime(), whose return value is void. 
04176  * 
04177  *      \subsubsection sec5-5-3-8 Section 5.5.3.8: rx SetConnHardDeadTime() 
04178  * 
04179  * \par
04180  * \#define rx_SetConnHardDeadTime(conn, seconds) ((conn)->hardDeadTime =
04181  * (seconds)) 
04182  * \par
04183  * It is convenient to be able to specify that calls on certain Rx connections
04184  * have a hard absolute timeout. This guards against protocol errors not caught
04185  * by other checks in which one or both of the client and server are looping.
04186  * The rx SetConnHardDeadTime() macro is available for this purpose. It will
04187  * limit calls on the connection identified by the conn parameter to execution
04188  * times of no more than the given number of seconds. By default, active calls
04189  * on an Rx connection may proceed for an unbounded time, as long as they are
04190  * not totally quiescent (see Section 5.5.3.7 for a description of the rx
04191  * SetConnDeadTime()) or idle (see Section 5.5.3.4 for a description of the rx
04192  * SetIdleDeadTime()). 
04193  * \par
04194  * The conn parameter should resolve to an object of type (struct rx connection
04195  * *). The seconds parameter should resolve to an object of type u short. An
04196  * instance of the rx SetConnHardDeadTime() macro itself resolves into the
04197  * result of the assignment, which is an object of type u short. 
04198  * 
04199  *      \subsubsection sec5-5-3-9 Section 5.5.3.9: rx GetBeforeProc() 
04200  * 
04201  * \par
04202  * \#define rx_GetBeforeProc(service) ((service)->beforeProc) 
04203  * \par
04204  * Return a pointer of type (VOID *)() to the procedure associated with the
04205  * given Rx service that will be called immediately upon activation of a server
04206  * thread to handle an incoming call. The service parameter should resolve to
04207  * an object of type struct rx service. 
04208  * \par
04209  * When an Rx service is first created (via a call to the rx NewService()
04210  * function), its beforeProc field is set to a null pointer. See the
04211  * description of the rx SetBeforeProc() below. 
04212  * 
04213  *      \subsubsection sec5-5-3-10 Section 5.5.3.10: rx SetBeforeProc() 
04214  * 
04215  * \par
04216  * \#define rx_SetBeforeProc(service, proc) ((service)->beforeProc = (proc)) 
04217  * \par
04218  * Instruct the Rx facility to call the procedure identified by the proc
04219  * parameter immediately upon activation of a server thread to handle an
04220  * incoming call. The specified procedure will be called with a single
04221  * parameter, a pointer of type struct rx call, identifying the call this
04222  * thread will now be responsible for handling. The value returned by the
04223  * procedure, if any, is discarded. 
04224  * \par
04225  * The service parameter should resolve to an object of type struct rx service.
04226  * The proc parameter should resolve to an object of type (VOID *)(). An
04227  * instance of the rx SetBeforeProc() macro itself resolves into the result of
04228  * the assignment, which is an object of type (VOID *)(). 
04229  * 
04230  *      \subsubsection sec5-5-3-11 Section 5.5.3.11: rx GetAfterProc() 
04231  * 
04232  * \par
04233  * \#define rx_GetAfterProc(service) ((service)->afterProc) 
04234  * \par
04235  * Return a pointer of type (VOID *)() to the procedure associated with the
04236  * given Rx service that will be called immediately upon completion of the
04237  * particular Rx call for which a server thread was activated. The service
04238  * parameter should resolve to an object of type struct rx service. 
04239  * \par
04240  * When an Rx service is first created (via a call to the rx NewService()
04241  * function), its afterProc field is set to a null pointer. See the description
04242  * of the rx SetAfterProc() below. 
04243  * 
04244  *      \subsubsection sec5-5-3-12 Section 5.5.3.12: rx SetAfterProc() 
04245  * 
04246  * \par
04247  * \#define rx_SetAfterProc(service, proc) ((service)->afterProc = (proc)) 
04248  * \par
04249  * Instruct the Rx facility to call the procedure identified by the proc
04250  * parameter immediately upon completion of the particular Rx call for which a
04251  * server thread was activated. The specified procedure will be called with a
04252  * single parameter, a pointer of type struct rx call, identifying the call
04253  * this thread just handled. The value returned by the procedure, if any, is
04254  * discarded. 
04255  * \par
04256  * The service parameter should resolve to an object of type struct rx service.
04257  * The proc parameter should resolve to an object of type (VOID *)(). An
04258  * instance of the rx SetAfterProc() macro itself resolves into the result of
04259  * the assignment, which is an object of type (VOID *)(). 
04260  * 
04261  *      \subsubsection sec5-5-3-13 Section 5.5.3.13: rx SetNewConnProc() 
04262  * 
04263  * \par
04264  * \#define rx_SetNewConnProc(service, proc) ((service)->newConnProc = (proc)) 
04265  * \par
04266  * Instruct the Rx facility to call the procedure identified by the proc
04267  * parameter as the last step in the creation of a new Rx server-side
04268  * connection for the given service. The specified procedure will be called
04269  * with a single parameter, a pointer of type (struct rx connection *),
04270  * identifying the connection structure that was just built. The value returned
04271  * by the procedure, if any, is discarded. 
04272  * \par
04273  * The service parameter should resolve to an object of type struct rx service.
04274  * The proc parameter should resolve to an object of type (VOID *)(). An
04275  * instance of the rx SetNewConnProc() macro itself resolves into the result of
04276  * the assignment, which is an object of type (VOID *)(). 
04277  * \note There is no access counterpart defined for this macro, namely one that
04278  * returns the current setting of a service's newConnProc. 
04279  * 
04280  *      \subsubsection sec5-5-3-14 Section 5.5.3.14: rx SetDestroyConnProc() 
04281  * 
04282  * \par
04283  * \#define rx_SetDestroyConnProc(service, proc) ((service)->destroyConnProc =
04284  * (proc)) 
04285  * \par
04286  * Instruct the Rx facility to call the procedure identified by the proc
04287  * parameter just before a server connection associated with the given Rx
04288  * service is destroyed. The specified procedure will be called with a single
04289  * parameter, a pointer of type (struct rx connection *), identifying the
04290  * connection about to be destroyed. The value returned by the procedure, if
04291  * any, is discarded. 
04292  * \par
04293  * The service parameter should resolve to an object of type struct rx service.
04294  * The proc parameter should resolve to an object of type (VOID *)(). An
04295  * instance of the rx SetDestroyConnProc() macro itself resolves into the
04296  * result of the assignment, which is an object of type (VOID *)(). 
04297  * \note There is no access counterpart defined for this macro, namely one that
04298  * returns the current setting of a service's destroyConnProc. 
04299  * 
04300  *      \subsection sec5-5-4 Section 5.5.4: Security-Related Operations 
04301  * 
04302  * \par
04303  * The following macros are callable by Rx security modules, and assist in
04304  * getting and setting header and trailer lengths, setting actual packet size,
04305  * and finding the beginning of the security header (or data). 
04306  * 
04307  *      \subsubsection sec5-5-4-1 Section 5.5.4.1: rx GetSecurityHeaderSize() 
04308  * 
04309  * \par
04310  * \#define rx_GetSecurityHeaderSize(conn) ((conn)->securityHeaderSize) 
04311  * \par
04312  * Generate a reference to the field in an Rx connection structure that records
04313  * the length in bytes of the associated security module's packet header data. 
04314  * \par
04315  * The conn parameter should resolve to an object of type struct rx connection.
04316  * An instance of the rx GetSecurityHeaderSize() macro itself resolves into an
04317  * object of type u short. 
04318  * 
04319  *      \subsubsection sec5-5-4-2 Section 5.5.4.2: rx SetSecurityHeaderSize() 
04320  * 
04321  * \par
04322  * \#define rx_SetSecurityHeaderSize(conn, length) ((conn)->securityHeaderSize
04323  * = (length)) 
04324  * \par
04325  * Set the field in a connection structure that records the length in bytes of
04326  * the associated security module's packet header data. 
04327  * \par
04328  * The conn parameter should resolve to an object of type struct rx connection.
04329  * The length parameter should resolve to an object of type u short. An
04330  * instance of the rx SetSecurityHeaderSize() macro itself resolves into the
04331  * result of the assignment, which is an object of type u short. 
04332  * 
04333  *      \subsubsection sec5-5-4-3 Section 5.5.4.3: rx
04334  *      GetSecurityMaxTrailerSize() 
04335  * 
04336  * \par
04337  * \#define rx_GetSecurityMaxTrailerSize(conn) ((conn)->securityMaxTrailerSize) 
04338  * \par
04339  * Generate a reference to the field in an Rx connection structure that records
04340  * the maximum length in bytes of the associated security module's packet
04341  * trailer data. 
04342  * \par
04343  * The conn parameter should resolve to an object of type struct rx connection.
04344  * An instance of the rx GetSecurityMaxTrailerSize() macro itself resolves into
04345  * an object of type u short. 
04346  * 
04347  *      \subsubsection sec5-5-4-4 Section 5.5.4.4: rx
04348  *      SetSecurityMaxTrailerSize() 
04349  * 
04350  * \par
04351  * \#define rx_SetSecurityMaxTrailerSize(conn, length)
04352  * ((conn)->securityMaxTrailerSize = (length)) 
04353  * \par
04354  * Set the field in a connection structure that records the maximum length in
04355  * bytes of the associated security module's packet trailer data. 
04356  * \par
04357  * The conn parameter should resolve to an object of type struct rx connection.
04358  * The length parameter should resolve to an object of type u short. An
04359  * instance of the rx SetSecurityHeaderSize() macro itself resolves into the
04360  * result of the assignment, which is an object of type u short. 
04361  * 
04362  *      \subsection sec5-5-5 Section 5.5.5: Sizing Operations 
04363  * 
04364  * \par
04365  * The macros described in this section assist the application programmer in
04366  * determining the sizes of the various Rx packet regions, as well as their
04367  * placement within a packet buffer. 
04368  * 
04369  *      \subsubsection sec5-5-5-1 Section 5.5.5.1: rx UserDataOf() 
04370  * 
04371  * \par
04372  * \#define rx_UserDataOf(conn, packet) (((char *) (packet)->wire.data) +
04373  * (conn)->securityHeaderSize) 
04374  * \par
04375  * Generate a pointer to the beginning of the actual user data in the given Rx
04376  * packet, that is associated with the connection described by the conn
04377  * pointer. User data appears immediately after the packet's security header
04378  * region, whose length is determined by the security module used by the
04379  * connection. The conn parameter should resolve to an object of type struct rx
04380  * connection. The packet parameter should resolve to an object of type struct
04381  * rx packet. An instance of the rx UserDataOf() macro itself resolves into an
04382  * object of type (char *). 
04383  * 
04384  *      \subsubsection sec5-5-5-2 Section 5.5.5.2: rx MaxUserDataSize() 
04385  * 
04386  * \par
04387  * \#define rx_MaxUserDataSize(conn) 
04388  * \n ((conn)->peer->packetSize 
04389  * \n -RX_HEADER_SIZE 
04390  * \n -(conn)->securityHeaderSize 
04391  * \n -(conn)->securityMaxTrailerSize) 
04392  * \par
04393  * Return the maximum number of user data bytes that may be carried by a packet
04394  * on the Rx connection described by the conn pointer. The overall packet size
04395  * is reduced by the IP, UDP, and Rx headers, as well as the header and trailer
04396  * areas required by the connection's security module. 
04397  * \par
04398  * The conn parameter should resolve to an object of type struct rx connection.
04399  * An instance of the rx MaxUserDataSize() macro itself resolves into the an
04400  * object of type (u short). 
04401  * 
04402  *      \subsection sec5-5-6 Section 5.5.6: Complex Operations 
04403  * 
04404  * \par
04405  * Two Rx macros are designed to handle potentially complex operations, namely
04406  * reading data from an active incoming call and writing data to an active
04407  * outgoing call. Each call structure has an internal buffer that is used to
04408  * collect and cache data traveling through the call. This buffer is used in
04409  * conjunction with reading or writing to the actual Rx packets traveling on
04410  * the wire in support of the call. The rx Read() and rx Write() macros allow
04411  * their caller to simply manipulate the internal data buffer associated with
04412  * the Rx call structures whenever possible, thus avoiding the overhead
04413  * associated with a function call. When buffers are either filled or drained
04414  * (depending on the direction of the data flow), these macros will then call
04415  * functions to handle the more complex cases of generating or receiving
04416  * packets in support of the operation. 
04417  * 
04418  *      \subsubsection sec5-5-6-1 Section 5.5.6.1: rx Read() 
04419  * 
04420  * \par
04421  * \#define rx_Read(call, buf, nbytes) 
04422  * \n ((call)->nLeft > (nbytes) ? 
04423  * \n bcopy((call)->bufPtr, (buf), (nbytes)), 
04424  * \n (call)->nLeft -= (nbytes), (call)->bufPtr += (nbytes), (nbytes) 
04425  * \n : rx_ReadProc((call), (buf), (nbytes))) 
04426  * \par
04427  * Read nbytes of data from the given Rx call into the buffer to which buf
04428  * points. If the call's internal buffer has at least nbytes bytes already
04429  * filled, then this is done in-line with a copy and some pointer and counter
04430  * updates within the call structure. If the call's internal buffer doesn't
04431  * have enough data to satisfy the request, then the rx ReadProc() function
04432  * will handle this more complex situation. 
04433  * \par
04434  * In either case, the rx Read() macro returns the number of bytes actually
04435  * read from the call, resolving to an object of type int. If rx Read() returns
04436  * fewer than nbytes bytes, the call status should be checked via the rx
04437  * Error() macro. 
04438  * 
04439  *      \subsubsection sec5-5-6-2 Section 5.5.6.2: rx Write() 
04440  * 
04441  * \par
04442  * \#define rx_Write(call, buf, nbytes) 
04443  * \n ((call)->nFree > (nbytes) ? 
04444  * \n bcopy((buf), (call)->bufPtr, (nbytes)), 
04445  * \n (call)->nFree -= (nbytes), 
04446  * \n (call)->bufPtr += (nbytes), (nbytes) 
04447  * \n : rx_WriteProc((call), (buf), (nbytes))) 
04448  * \par
04449  * Write nbytes of data from the buffer pointed to by buf into the given Rx
04450  * call. If the call's internal buffer has at least nbytes bytes free, then
04451  * this is done in-line with a copy and some pointer and counter updates within
04452  * the call structure. If the call's internal buffer doesn't have room, then
04453  * the rx WriteProc() function will handle this more complex situation. 
04454  * \par
04455  * In either case, the rx Write() macro returns the number of bytes actually
04456  * written to the call, resolving to an object of type int. If zero is
04457  * returned, the call status should be checked via the rx Error() macro. 
04458  * 
04459  *      \subsection sec5-5-7 Section 5.5.7: Security Operation Invocations 
04460  * 
04461  * \par
04462  * Every Rx security module is required to implement an identically-named set
04463  * of operations, through which the security mechanism it defines is invoked.
04464  * This characteristic interface is reminiscent of the vnode interface defined
04465  * and popularized for file systems by Sun Microsystems [4]. The structure
04466  * defining this function array is described in Section 5.3.1.1. 
04467  * \par
04468  * These security operations are part of the struct rx securityClass, which
04469  * keeps not only the ops array itself but also any private data they require
04470  * and a reference count. Every Rx service contains an array of these security
04471  * class objects, specifying the range of security mechanisms it is capable of
04472  * enforcing. Every Rx connection within a service is associated with exactly
04473  * one of that service's security objects, and every call issued on the
04474  * connection will execute the given security protocol. 
04475  * \par
04476  * The macros described below facilitate the execution of the security module
04477  * interface functions. They are covered in the same order they appear in the
04478  * struct rx securityOps declaration. 
04479  * 
04480  *      \subsubsection sec5-5-7-1 Section 5.5.7.1: RXS OP() 
04481  * 
04482  * \code
04483  * #if defined(__STDC__) && !defined(__HIGHC__) 
04484  *      #define RXS_OP(obj, op, args) 
04485  *              ((obj->ops->op_ ## op) ? (*(obj)->ops->op_ ## op)args : 0) 
04486  * #else 
04487  *      #define RXS_OP(obj, op, args) 
04488  *              ((obj->ops->op_op) ? (*(obj)->ops->op_op)args : 0) 
04489  * #endif 
04490  * \endcode
04491  * 
04492  * \par
04493  * The RXS OP macro represents the workhorse macro in this group, used by all
04494  * the others. It takes three arguments, the first of which is a pointer to the
04495  * security object to be referenced. This obj parameter must resolve to an
04496  * object of type (struct rx securityOps *). The second parameter identifies
04497  * the specific op to be performed on this security object. The actual text of
04498  * this op argument is used to name the desired opcode function. The third and
04499  * final argument, args, specifies the text of the argument list to be fed to
04500  * the chosen security function. Note that this argument must contain the
04501  * bracketing parentheses for the function call's arguments. In fact, note that
04502  * each of the security function access macros defined below provides the
04503  * enclosing parentheses to this third RXS OP() macro. 
04504  * 
04505  *      \subsubsection sec5-5-7-2 Section 5.5.7.1: RXS Close() 
04506  * 
04507  * \par
04508  * \#define RXS_Close(obj) RXS_OP(obj, Close, (obj)) 
04509  * \par
04510  * This macro causes the execution of the interface routine occupying the op
04511  * Close() slot in the Rx security object identified by the obj pointer. This
04512  * interface function is invoked by Rx immediately before a security object is
04513  * discarded. Among the responsibilities of such a function might be
04514  * decrementing the object's refCount field, and thus perhaps freeing up any
04515  * space contained within the security object's private storage region,
04516  * referenced by the object's privateData field. 
04517  * \par
04518  * The obj parameter must resolve into an object of type (struct rx securityOps
04519  * *). In generating a call to the security object's op Close() routine, the
04520  * obj pointer is used as its single parameter. An invocation of the RXS
04521  * Close() macro results in a return value identical to that of the op Close()
04522  * routine, namely a value of type int. 
04523  * 
04524  *      \subsubsection sec5-5-7-3 Section 5.5.7.3: RXS NewConnection() 
04525  * 
04526  * \par
04527  * \#define RXS_NewConnection(obj, conn) RXS_OP(obj, NewConnection, (obj,
04528  * conn)) 
04529  * \par
04530  * This macro causes the execution of the interface routine in the op
04531  * NewConnection() slot in the Rx security object identified by the obj
04532  * pointer. This interface function is invoked by Rx immediately after a
04533  * connection using the given security object is created. Among the
04534  * responsibilities of such a function might be incrementing the object's
04535  * refCount field, and setting any per-connection information based on the
04536  * associated security object's private storage region, as referenced by the
04537  * object's privateData field. 
04538  * \par
04539  * The obj parameter must resolve into an object of type (struct rx securityOps
04540  * *). The conn argument contains a pointer to the newly-created connection
04541  * structure, and must resolve into an object of type (struct rx connection *). 
04542  * \par
04543  * In generating a call to the routine located at the security object's op
04544  * NewConnection() slot, the obj and conn pointers are used as its two
04545  * parameters. An invocation of the RXS NewConnection() macro results in a
04546  * return value identical to that of the op NewConnection() routine, namely a
04547  * value of type int. 
04548  * 
04549  *      \subsubsection sec5-5-7-4 Section 5.5.7.4: RXS PreparePacket() 
04550  * 
04551  * \par
04552  * \#define RXS_PreparePacket(obj, call, packet) 
04553  * \n RXS_OP(obj, PreparePacket, (obj, call, packet)) 
04554  * \par
04555  * This macro causes the execution of the interface routine in the op
04556  * PreparePacket() slot in the Rx security object identified by the obj
04557  * pointer. This interface function is invoked by Rx each time it prepares an
04558  * outward-bound packet. Among the responsibilities of such a function might be
04559  * computing information to put into the packet's security header and/or
04560  * trailer. 
04561  * \par
04562  * The obj parameter must resolve into an object of type (struct rx securityOps
04563  * *). The call argument contains a pointer to the Rx call to which the given
04564  * packet belongs, and must resolve to an object of type (struct rx call *).
04565  * The final argument, packet, contains a pointer to the packet itself. It
04566  * should resolve to an object of type (struct rx packet *). 
04567  * \par
04568  * In generating a call to the routine located at the security object's op
04569  * PreparePacket() slot, the obj, call, and packet pointers are used as its
04570  * three parameters. An invocation of the RXS PreparePacket() macro results in
04571  * a return value identical to that of the op PreparePacket() routine, namely a
04572  * value of type int. 
04573  * 
04574  *      \subsubsection sec5-5-7-5 Section 5.5.7.5: RXS SendPacket() 
04575  * 
04576  * \par
04577  * \#define RXS_SendPacket(obj, call, packet) RXS_OP(obj, SendPacket, (obj,
04578  * call, packet)) 
04579  * \par
04580  * This macro causes the execution of the interface routine occupying the op
04581  * SendPacket() slot in the Rx security object identified by the obj pointer.
04582  * This interface function is invoked by Rx each time it physically transmits
04583  * an outward-bound packet. Among the responsibilities of such a function might
04584  * be recomputing information in the packet's security header and/or trailer. 
04585  * \par
04586  * The obj parameter must resolve into an object of type (struct rx securityOps
04587  * *). The call argument contains a pointer to the Rx call to which the given
04588  * packet belongs, and must resolve to an object of type (struct rx call *).
04589  * The final argument, packet, contains a pointer to the packet itself. It
04590  * should resolve to an object of type (struct rx packet *). 
04591  * \par
04592  * In generating a call to the routine located at the security object's op
04593  * SendPacket() slot, the obj, call, and packet pointers are used as its three
04594  * parameters. An invocation of the RXS SendPacket() macro results in a return
04595  * value identical to that of the op SendPacket() routine, namely a value of
04596  * type int. 
04597  * 
04598  *      \subsubsection sec5-5-7-6 Section 5.5.7.6: RXS CheckAuthentication() 
04599  * 
04600  * \par
04601  * \#define RXS_CheckAuthentication(obj, conn) RXS_OP(obj, CheckAuthentication,
04602  * (obj, conn)) 
04603  * \par
04604  * This macro causes the execution of the interface routine in the op
04605  * CheckAuthentication() slot in the Rx security object identified by the obj
04606  * pointer. This interface function is invoked by Rx each time it needs to
04607  * check whether the given connection is one on which authenticated calls are
04608  * being performed. Specifically, a value of 0 is returned if authenticated
04609  * calls are not being executed on this connection, and a value of 1 is
04610  * returned if they are. 
04611  * \par
04612  * The obj parameter must resolve into an object of type (struct rx securityOps
04613  * *). The conn argument contains a pointer to the Rx connection checked as to
04614  * whether authentication is being performed, and must resolve to an object of
04615  * type (struct rx connection *). 
04616  * \par
04617  * In generating a call to the routine in the security object's op
04618  * CheckAuthentication() slot, the obj and conn pointers are used as its two
04619  * parameters. An invocation of the RXS CheckAuthentication() macro results in
04620  * a return value identical to that of the op CheckAuthentication() routine,
04621  * namely a value of type int. 
04622  * 
04623  *      \subsubsection sec5-5-7-7 Section 5.5.7.7: RXS CreateChallenge() 
04624  * 
04625  * \par
04626  * \#define RXS_CreateChallenge(obj, conn) RXS_OP(obj, CreateChallenge, (obj,
04627  * conn)) 
04628  * \par
04629  * This macro causes the execution of the interface routine in the op
04630  * CreateChallenge() slot in the Rx security object identified by the obj
04631  * pointer. This interface function is invoked by Rx each time a challenge
04632  * event is constructed for a given connection. Among the responsibilities of
04633  * such a function might be marking the connection as temporarily
04634  * unauthenticated until the given challenge is successfully met. 
04635  * \par
04636  * The obj parameter must resolve into an object of type (struct rx securityOps
04637  * *). The conn argument contains a pointer to the Rx connection for which the
04638  * authentication challenge is being constructed, and must resolve to an object
04639  * of type (struct rx connection *). 
04640  * \par
04641  * In generating a call to the routine located at the security object's op
04642  * CreateChallenge() slot, the obj and conn pointers are used as its two
04643  * parameters. An invocation of the RXS CreateChallenge() macro results in a
04644  * return value identical to that of the op CreateChallenge() routine, namely a
04645  * value of type int. 
04646  * 
04647  *      \subsubsection sec5-5-7-8 Section 5.5.7.8: RXS GetChallenge() 
04648  * 
04649  * \par
04650  * \#define RXS_GetChallenge(obj, conn, packet) RXS_OP(obj, GetChallenge, (obj,
04651  * conn, packet)) 
04652  * \par
04653  * This macro causes the execution of the interface routine occupying the op
04654  * GetChallenge() slot in the Rx security object identified by the obj pointer.
04655  * This interface function is invoked by Rx each time a challenge packet is
04656  * constructed for a given connection. Among the responsibilities of such a
04657  * function might be constructing the appropriate challenge structures in the
04658  * area of packet dedicated to security matters. 
04659  * \par
04660  * The obj parameter must resolve into an object of type (struct rx securityOps
04661  * *). The conn argument contains a pointer to the Rx connection to which the
04662  * given challenge packet belongs, and must resolve to an object of type
04663  * (struct rx connection *). The final argument, packet, contains a pointer to
04664  * the challenge packet itself. It should resolve to an object of type (struct
04665  * rx packet *). 
04666  * \par
04667  * In generating a call to the routine located at the security object's op
04668  * GetChallenge() slot, the obj, conn, and packet pointers are used as its
04669  * three parameters. An invocation of the RXS GetChallenge() macro results in a
04670  * return value identical to that of the op GetChallenge() routine, namely a
04671  * value of type int. 
04672  * 
04673  *      \subsubsection sec5-5-7-9 Section 5.5.7.9: RXS GetResponse() 
04674  * 
04675  * \par
04676  * \#define RXS_GetResponse(obj, conn, packet) RXS_OP(obj, GetResponse, (obj,
04677  * conn, packet)) 
04678  * \par
04679  * This macro causes the execution of the interface routine occupying the op
04680  * GetResponse() slot in the Rx security object identified by the obj pointer.
04681  * This interface function is invoked by Rx on the server side each time a
04682  * response to a challenge packet must be received. 
04683  * \par
04684  * The obj parameter must resolve into an object of type (struct rx securityOps
04685  * *). The conn argument contains a pointer to the Rx client connection that
04686  * must respond to the authentication challenge, and must resolve to a (struct
04687  * rx connection *) object. The final argument, packet, contains a pointer to
04688  * the packet to be built in response to the challenge. It should resolve to an
04689  * object of type (struct rx packet *). 
04690  * \par
04691  * In generating a call to the routine located at the security object's op
04692  * GetResponse() slot, the obj, conn, and packet pointers are used as its three
04693  * parameters. An invocation of the RXS GetResponse() macro results in a return
04694  * value identical to that of the op GetResponse() routine, namely a value of
04695  * type int. 
04696  * 
04697  *      \subsubsection sec5-5-7-10 Section 5.5.7.10: RXS CheckResponse() 
04698  * 
04699  * \par
04700  * \#define RXS_CheckResponse(obj, conn, packet) RXS_OP(obj, CheckResponse,
04701  * (obj, conn, packet)) 
04702  * \par
04703  * This macro causes the execution of the interface routine in the op
04704  * CheckResponse() slot in the Rx security object identified by the obj
04705  * pointer. This interface function is invoked by Rx on the server side each
04706  * time a response to a challenge packet is received for a given connection.
04707  * The responsibilities of such a function might include verifying the
04708  * integrity of the response, pulling out the necessary security information
04709  * and storing that information within the affected connection, and otherwise
04710  * updating the state of the connection. 
04711  * \par
04712  * The obj parameter must resolve into an object of type (struct rx securityOps
04713  * *). The conn argument contains a pointer to the Rx server connection to
04714  * which the given challenge response is directed. This argument must resolve
04715  * to an object of type (struct rx connection *). The final argument, packet,
04716  * contains a pointer to the packet received in response to the challenge
04717  * itself. It should resolve to an object of type (struct rx packet *). 
04718  * \par
04719  * In generating a call to the routine located at the security object's op
04720  * CheckResponse() slot, the obj, conn, and packet pointers are ued as its
04721  * three parameters. An invocation of the RXS CheckResponse() macro results in
04722  * a return value identical to that of the op CheckResponse() routine, namely a
04723  * value of type int. 
04724  * 
04725  *      \subsubsection sec5-5-7-11 Section 5.5.7.11: RXS CheckPacket() 
04726  * 
04727  * \par
04728  * \#define RXS_CheckPacket(obj, call, packet) RXS_OP(obj, CheckPacket, (obj,
04729  * call, packet)) 
04730  * \par
04731  * This macro causes the execution of the interface routine occupying the op
04732  * CheckPacket() slot in the Rx security object identified by the obj pointer.
04733  * This interface function is invoked by Rx each time a packet is received. The
04734  * responsibilities of such a function might include verifying the integrity of
04735  * given packet, detecting any unauthorized modifications or tampering. 
04736  * \par
04737  * The obj parameter must resolve into an object of type (struct rx securityOps
04738  * *). The conn argument contains a pointer to the Rx connection to which the
04739  * given challenge response is directed, and must resolve to an object of type
04740  * (struct rx connection *). The final argument, packet, contains a pointer to
04741  * the packet received in response to the challenge itself. It should resolve
04742  * to an object of type (struct rx packet *). 
04743  * \par
04744  * In generating a call to the routine located at the security object's op
04745  * CheckPacket() slot, the obj, conn, and packet pointers are used as its three
04746  * parameters. An invocation of the RXS CheckPacket() macro results in a return
04747  * value identical to that of the op CheckPacket() routine, namely a value of
04748  * type int. 
04749  * \par
04750  * Please note that any non-zero return will cause Rx to abort all calls on the
04751  * connection. Furthermore, the connection itself will be marked as being in
04752  * error in such a case, causing it to reject any further incoming packets. 
04753  * 
04754  *      \subsubsection sec5-5-7-12 Section 5.5.7.12: RXS DestroyConnection() 
04755  * 
04756  * \par
04757  * \#define RXS_DestroyConnection(obj, conn) RXS_OP(obj, DestroyConnection,
04758  * (obj, conn)) 
04759  * \par
04760  * This macro causes the execution of the interface routine in the op
04761  * DestroyConnection() slot in the Rx security object identified by the obj
04762  * pointer. This interface function is invoked by Rx each time a connection
04763  * employing the given security object is being destroyed. The responsibilities
04764  * of such a function might include deleting any private data maintained by the
04765  * security module for this connection. 
04766  * \par
04767  * The obj parameter must resolve into an object of type (struct rx securityOps
04768  * *). The conn argument contains a pointer to the Rx connection being reaped,
04769  * and must resolve to a (struct rx connection *) object. 
04770  * \par
04771  * In generating a call to the routine located at the security object's op
04772  * DestroyConnection() slot, the obj and conn pointers are used as its two
04773  * parameters. An invocation of the RXS DestroyConnection() macro results in a
04774  * return value identical to that of the op DestroyConnection() routine, namely
04775  * a value of type int. 
04776  * 
04777  *      \subsubsection sec5-5-7-13 Section 5.5.7.13: RXS GetStats() 
04778  * 
04779  * \par
04780  * \#define RXS_GetStats(obj, conn, stats) RXS_OP(obj, GetStats, (obj, conn,
04781  * stats)) 
04782  * \par
04783  * This macro causes the execution of the interface routine in the op
04784  * GetStats() slot in the Rx security object identified by the obj pointer.
04785  * This interface function is invoked by Rx each time current statistics
04786  * concerning the given security object are desired. 
04787  * \par
04788  * The obj parameter must resolve into an object of type (struct rx securityOps
04789  * *). The conn argument contains a pointer to the Rx connection using the
04790  * security object to be examined, and must resolve to an object of type
04791  * (struct rx connection *). The final argument, stats, contains a pointer to a
04792  * region to be filled with the desired statistics. It should resolve to an
04793  * object of type (struct rx securityObjectStats *). 
04794  * \par
04795  * In generating a call to the routine located at the security object's op
04796  * GetStats() slot, the obj, conn, and stats pointers are used as its three
04797  * parameters. An invocation of the RXS GetStats() macro results in a return
04798  * value identical to that of the op GetStats() routine, namely a value of type
04799  * int. 
04800  * 
04801  *      \section sec5-6 Section 5.6: Functions 
04802  * 
04803  * \par
04804  * Rx exports a collection of functions that, in conjuction with the macros
04805  * explored in Section 5.5, allows its clients to set up and export services,
04806  * create and tear down connections to these services, and execute remote
04807  * procedure calls along these connections. 
04808  * \par
04809  * This paper employs two basic categorizations of these Rx routines. One set
04810  * of functions is meant to be called directly by clients of the facility, and
04811  * are referred to as the exported operations. The individual members of the
04812  * second set of functions are not meant to be called directly by Rx clients,
04813  * but rather are called by the collection of defined macros, so they must
04814  * still be lexically visible. These indirectly-executed routines are referred
04815  * to here as the semi-exported operations. 
04816  * \par
04817  * All Rx routines return zero upon success. The range of error codes employed
04818  * by Rx is defined in Section 5.2.15. 
04819  * 
04820  *      \subsection sec5-6-1 Section 5.6.1: Exported Operations 
04821  * 
04822  *      \subsection sec5-6-2 Section 5.6.2: rx Init _ Initialize Rx 
04823  * 
04824  * \par
04825  * int rx Init(IN int port) 
04826  * \par Description 
04827  * Initialize the Rx facility. If a non-zero port number is provided, it
04828  * becomes the default port number for any service installed later. If 0 is
04829  * provided for the port, a random port will be chosen by the system. The rx
04830  * Init() function sets up internal tables and timers, along with starting up
04831  * the listener thread. 
04832  * \par Error Codes 
04833  * RX ADDRINUSE The port provided has already been taken. 
04834  * 
04835  *      \subsection sec5-6-3 Section 5.6.3: rx NewService _ Create and install
04836  *      a new service 
04837  * 
04838  * \par
04839  * struct rx service *rx NewService(IN u short port; IN u short serviceId; IN
04840  * char *serviceName; IN struct rx securityClass **securityObjects; IN int
04841  * nSecurityObjects; IN long (*serviceProc)()) 
04842  * \par Description 
04843  * Create and advertise a new Rx service. A service is uniquely named by a UDP
04844  * port number plus a non-zero 16-bit serviceId on the given host. The port
04845  * argument may be set to zero if rx Init() was called with a non-zero port
04846  * number, in which case that original port will be used. A serviceName must
04847  * also be provided, to be used for identification purposes (e.g., the service
04848  * name might be used for probing for statistics). A pointer to an array of
04849  * nSecurityObjects security objects to be associated with the new service is
04850  * given in . securityObjects. The service's executeRequestProc() pointer is
04851  * set to serviceProc. 
04852  * \par
04853  * The function returns a pointer to a descriptor for the requested Rx service.
04854  * A null return value indicates that the new service could not be created.
04855  * Possible reasons include: 
04856  * \li The serviceId parameter was found to be zero. 
04857  * \li A port value of zero was specified at Rx initialization time (i.e., when
04858  * rx init() was called), requiring a non-zero value for the port parameter
04859  * here. 
04860  * \li Another Rx service is already using serviceId. 
04861  * \li Rx has already created the maximum RX MAX SERVICES Rx services (see
04862  * Section 5.2.1). 
04863  * \par Error Codes 
04864  * (struct rx service *) NULL The new Rx service could not be created, due to
04865  * one of the errors listed above. 
04866  * 
04867  *      \subsection sec5-6-4 Section 5.6.4: rx NewConnection _ Create a new
04868  *      connection to a given service 
04869  * 
04870  * \par
04871  * struct rx connection *rx NewConnection( IN u long shost, IN u short sport,
04872  * IN u short sservice, IN struct rx securityClass *securityObject, IN int
04873  * service SecurityIndex) 
04874  * \par Description 
04875  * Create a new Rx client connection to service sservice on the host whose IP
04876  * address is contained in shost and to that host's sport UDP port. The
04877  * corresponding Rx service identifier is expected in sservice. The caller also
04878  * provides a pointer to the security object to use for the connection in
04879  * securityObject, along with that object's serviceSecurityIndex among the
04880  * security objects associated with service sservice via a previous rx
04881  * NewService() call (see Section 5.6.3). 
04882  * \note It is permissible to provide a null value for the securityObject
04883  * parameter if the chosen serviceSecurityIndex is zero. This corresponds to
04884  * the pre-defined null security object, which does not engage in authorization
04885  * checking of any kind. 
04886  * \par Error Codes 
04887  * --- A pointer to an initialized Rx connection is always returned, unless osi
04888  *  Panic() is called due to memory allocation failure. 
04889  * 
04890  *      \subsection sec5-6-5 Section 5.6.5: rx NewCall _ Start a new call on
04891  *      the given connection 
04892  * 
04893  * \par
04894  * struct rx call *rx NewCall( IN struct rx connection *conn) 
04895  * \par Description 
04896  * Start a new Rx remote procedure call on the connection specified by the conn
04897  * parameter. The existing call structures (up to RX MAXCALLS of them) are
04898  * examined in order. The first non-active call encountered (i.e., either
04899  * unused or whose call->state is RX STATE DALLY) will be appropriated and
04900  * reset if necessary. If all call structures are in active use, the RX CONN
04901  * MAKECALL WAITING flag is set in the conn->flags field, and the thread
04902  * handling this request will sleep until a call structure comes free. Once a
04903  * call structure has been reserved, the keep-alive protocol is enabled for it. 
04904  * \par
04905  * The state of the given connection determines the detailed behavior of the
04906  * function. The conn->timeout field specifies the absolute upper limit of the
04907  * number of seconds this particular call may be in operation. After this time
04908  * interval, calls to such routines as rx SendData() or rx ReadData() will fail
04909  * with an RX CALL TIMEOUT indication. 
04910  * \par Error Codes 
04911  * --- A pointer to an initialized Rx call is always returned, unless osi
04912  *  Panic() is called due to memory allocation failure. 
04913  * 
04914  *      \subsection sec5-6-6 Section 5.6.6: rx EndCall _ Terminate the given
04915  *      call 
04916  * 
04917  * \par
04918  * int rx EndCall(
04919  * \param IN struct rx call *call,
04920  * \param IN long rc
04921  * \n ) 
04922  * \par Description
04923  * Indicate that the Rx call described by the structure located at call is
04924  * finished, possibly prematurely. The value passed in the rc parameter is
04925  * returned to the peer, if appropriate. The final error code from processing
04926  * the call will be returned as rx EndCall()'s value. The given call's state
04927  * will be set to RX STATE DALLY, and threads waiting to establish a new call
04928  * on this connection are signalled (see the description of the rx NewCall() in
04929  * Section 5.6.5). 
04930  * \par Error Codes 
04931  * -1 Unspecified error has occurred. 
04932  * 
04933  *      \subsection sec5-6-7 Section 5.6.7: rx StartServer _ Activate installed
04934  *      rx service(s) 
04935  * 
04936  * \par
04937  * void rx StartServer( IN int donateMe) 
04938  * \par Description 
04939  * This function starts server threads in support of the Rx services installed
04940  * via calls to rx NewService() (see Section 5.6.3). This routine first
04941  * computes the number of server threads it must create, governed by the
04942  * minProcs and maxProcs fields in the installed service descriptors. The
04943  * minProcs field specifies the minimum number of threads that are guaranteed
04944  * to be concurrently available to the given service. The maxProcs field
04945  * specifies the maximum number of threads that may ever be concurrently
04946  * assigned to the particular service, if idle threads are available. Using
04947  * this information, rx StartServer() computes the correct overall number of
04948  * threads as follows: For each installed service, minProcs threads will be
04949  * created, enforcing the minimality guarantee. Calculate the maximum
04950  * difference between the maxProcs and minProcs fields for each service, and
04951  * create this many additional server threads, enforcing the maximality
04952  * guarantee. 
04953  * \par
04954  * If the value placed in the donateMe argument is zero, then rx StartServer()
04955  * will simply return after performing as described above. Otherwise, the
04956  * thread making the rx StartServer() call will itself begin executing the
04957  * server thread loop. In this case, the rx StartServer() call will never
04958  * return. 
04959  * \par Error Codes 
04960  * ---None. 
04961  * 
04962  *      \subsection sec5-6-8 Section 5.6.8: rx PrintStats -- Print basic
04963  *      statistics to a file
04964  * 
04965  * \par
04966  * void rx PrintStats( IN FILE *file)
04967  * \par Description
04968  * Prints Rx statistics (basically the contents of the struct rx stats holding
04969  * the statistics for the Rx facility) to the open file descriptor identified
04970  * by file. The output is ASCII text, and is intended for human consumption. 
04971  * \note This function is available only if the Rx package has been compiled
04972  * with the RXDEBUG flag. 
04973  * \par Error Codes 
04974  * ---None. 
04975  * 
04976  *      \subsection sec5-6-9 Section 5.6.9: rx PrintPeerStats _ Print peer
04977  *      statistics to a file 
04978  * \par
04979  * void rx PrintPeerStats( IN FILE *file, IN struct rx peer *peer)
04980  * \par Description
04981  * Prints the Rx peer statistics found in peer to the open file descriptor
04982  * identified by file. The output is in normal ASCII text, and is intended for
04983  * human consumption. 
04984  * \note This function is available only if the Rx package has been compiled
04985  * with the RXDEBUG flag. 
04986  * \par Error Codes 
04987  * ---None. 
04988  * 
04989  *      \subsection sec5-6-10 Section 5.6.10: rx finalize _ Shut down Rx
04990  *      gracefully 
04991  * 
04992  * \par
04993  * void rx finalize() 
04994  * \par Description 
04995  * This routine may be used to shut down the Rx facility for either server or
04996  * client applications. All of the client connections will be gracefully
04997  * garbage-collected after their active calls are cleaned up. The result of
04998  * calling rx finalize() from a client program is that the server-side entity
04999  * will be explicitly advised that the client has terminated. This notification
05000  * frees the server-side application from having to probe the client until its
05001  * records eventually time out, and also allows it to free resources currently
05002  * assigned to that client's support. 
05003  * \par Error Codes 
05004  * ---None. 
05005  * 
05006  *      \subsection sec5-6-11 Section 5.6.11: Semi-Exported Operations 
05007  * 
05008  * \par
05009  * As described in the introductory text in Section 5.6, entries in this
05010  * lexically-visible set of Rx functions are not meant to be called directly by
05011  * client applications, but rather are invoked by Rx macros called by users. 
05012  * 
05013  *      \subsection sec5-6-12 Section 5.6.12: rx WriteProc _ Write data to an
05014  *      outgoing call 
05015  * 
05016  * \par
05017  * int rx WriteProc( IN struct rx call *call, IN char *buf, IN int nbytes)
05018  * \par Description 
05019  * Write nbytes of data from buffer buf into the Rx call identified by the call
05020  * parameter. The value returned by rx WriteProc() reports the number of bytes
05021  * actually written into the call. If zero is returned, then the rx Error()
05022  * macro may be used to obtain the call status. 
05023  * \par
05024  * This routine is called by the rx Write() macro, which is why it must be
05025  * exported by the Rx facility. 
05026  * \par Error Codes 
05027  * Indicates error in the given Rx call; use the rx Error() macro to determine
05028  * the call status. 
05029  * 
05030  *      \subsection sec5-6-13 Section 5.6.13: rx ReadProc _ Read data from an
05031  *      incoming call 
05032  * 
05033  * \par
05034  * int rx ReadProc( IN struct rx call *call, IN char *buf, IN int nbytes)
05035  * \par Description 
05036  * Read up to nbytes of data from the Rx call identified by the call parameter
05037  * into the buf buffer. The value returned by rx ReadProc() reports the number
05038  * of bytes actually read from the call. If zero is returned, then the rx
05039  * Error() macro may be used to obtain the call status. 
05040  * \par
05041  * This routine is called by the rx Read() macro, which is why it must be
05042  * exported by the Rx facility. 
05043  * \par Error Codes 
05044  * Indicates error in the given Rx call; use the rx Error() macro to determine
05045  * the call status. 
05046  * 
05047  *      \subsection sec5-6-1 Section 5.6.1: rx FlushWrite -- Flush buffered
05048  *      data on outgoing call
05049  * 
05050  * \par
05051  * void rx FlushWrite( IN struct rx call *call)
05052  * \par Description
05053  * Flush any buffered data on the given Rx call to the stream. If the call is
05054  * taking place on a server connection, the call->mode is set to RX MODE EOF.
05055  * If the call is taking place on a client connection, the call->mode is set to
05056  * RX MODE RECEIVING. 
05057  * \par Error Codes 
05058  * ---None. 
05059  * 
05060  *      \subsection sec5-6-15 Section 5.6.15: rx SetArrivalProc _ Set function
05061  *      to invoke upon call packet arrival 
05062  * 
05063  * \par
05064  * void rx SetArrivalProc( IN struct rx call *call, IN VOID (*proc)(), IN VOID
05065  * *handle, IN VOID *arg) 
05066  * \par Description 
05067  * Establish a procedure to be called when a packet arrives for a call. This
05068  * routine will be called at most once after each call, and will also be called
05069  * if there is an error condition on the call or the call is complete. The rx
05070  * SetArrivalProc() function is used by multicast Rx routines to build a
05071  * selection function that determines which of several calls is likely to be a
05072  * good one to read from. The implementor's comments in the Rx code state that,
05073  * due to the current implementation, it is probably only reasonable to use rx
05074  * SetArrivalProc() immediately after an rx NewCall(), and to only use it once. 
05075  * \par Error Codes 
05076  * ---None. 
05077  * 
05078  *      \page chap6 Chapter 6 -- Example Server and Client 
05079  * 
05080  *      \section sec6-1 Section 6.1: Introduction 
05081  * 
05082  * \par
05083  * This chapter provides a sample program showing the use of Rx. Specifically,
05084  * the rxdemo application, with all its support files, is documented and
05085  * examined. The goal is to provide the reader with a fully-developed and
05086  * operational program illustrating the use of both regular Rx remote procedure
05087  * calls and streamed RPCs. The full text of the rxdemo application is
05088  * reproduced in the sections below, along with additional commentary. 
05089  * \par
05090  * Readers wishing to directly experiment with this example Rx application are
05091  * encouraged to examine the on-line version of rxdemo. Since it is a program
05092  * of general interest, it has been installed in the usr/contrib tree in the
05093  * grand.central.org cell. This area contains user-contributed software for the
05094  * entire AFS community. At the top of this tree is the
05095  * /afs/grand.central.org/darpa/usr/contrib directory. Both the server-side and
05096  * client-side rxdemo binaries (rxdemo server and rxdemo client, respectively)
05097  * may be found in the bin subdirectory. The actual sources reside in the
05098  * .site/grand.central.org/rxdemo/src subdirectory. 
05099  * \par
05100  * The rxdemo code is composed of two classes of files, namely those written by
05101  * a human programmer and those generated from the human-written code by the
05102  * Rxgen tool. Included in the first group of files are: 
05103  * \li  rxdemo.xg This is the RPC interface definition file, providing
05104  * high-level definitions of the supported calls. 
05105  * \li  rxdemo client.c: This is the rxdemo client program, calling upon the
05106  * associated server to perform operations defined by rxdemo.xg. 
05107  * \li  rxdemo server.c: This is the rxdemo server program, implementing the
05108  * operations promised in rxdemo.xg. 
05109  * \li  Makefile: This is the file that directs the compilation and
05110  * installation of the rxdemo code. 
05111  * \par
05112  * The class of automatically-generated files includes the following items: 
05113  * \li rxdemo.h: This header file contains the set of constant definitions
05114  * present in rxdemo.xg, along with information on the RPC opcodes defined for
05115  * this Rx service. 
05116  * \li rxdemo.cs.c: This client-side stub file performs all the marshalling and
05117  * unmarshalling of the arguments for the RPC routines defined in rxdemo.xg. 
05118  * \li rxdemo.ss.c: This stub file similarly defines all the marshalling and
05119  * unmarshalling of arguments for the server side of the RPCs, invokes the
05120  * routines defined within rxdemo server.c to implement the calls, and also
05121  * provides the dispatcher function. 
05122  * \li rxdemo.xdr.c: This module defines the routines required to convert
05123  * complex user-defined data structures appearing as arguments to the Rx RPC
05124  * calls exported by rxdemo.xg into network byte order, so that correct
05125  * communication is guaranteed between clients and server with different memory
05126  * organizations. 
05127  * \par
05128  * The chapter concludes with a section containing sample output from running
05129  * the rxdemo server and client programs. 
05130  * 
05131  *      \section sec6-2 Section 6.2: Human-Generated files 
05132  * 
05133  * \par
05134  * The rxdemo application is based on the four human-authored files described
05135  * in this section. They provide the basis for the construction of the full set
05136  * of modules needed to implement the specified Rx service. 
05137  * 
05138  *      \subsection sec6-2-1 Section 6.2.1: Interface file: rxdemo.xg 
05139  * 
05140  * \par
05141  * This file serves as the RPC interface definition file for this application.
05142  * It defines various constants, including the Rx service port to use and the
05143  * index of the null security object (no encryption is used by rxdemo). It
05144  * defines the RXDEMO MAX and RXDEMO MIN constants, which will be used by the
05145  * server as the upper and lower bounds on the number of Rx listener threads to
05146  * run. It also defines the set of error codes exported by this facility.
05147  * finally, it provides the RPC function declarations, namely Add() and
05148  * Getfile(). Note that when building the actual function definitions, Rxgen
05149  * will prepend the value of the package line in this file, namely "RXDEMO ",
05150  * to the function declarations. Thus, the generated functions become RXDEMO
05151  * Add() and RXDEMO Getfile(), respectively. Note the use of the split keyword
05152  * in the RXDEMO Getfile() declaration, which specifies that this is a streamed
05153  * call, and actually generates two client-side stub routines (see Section
05154  * 6.3.1). 
05155  * 
05156  * \code
05157  * /*======================================================================= 
05158  * * Interface for an example Rx server/client application, using both * * 
05159  * standard and streamed calls.  * ** * Edward R. Zayas * * Transarc 
05160  * Corporation * ** ** * The United States Government has rights in this 
05161  * work pursuant * * to contract no. MDA972-90-C-0036 between the United 
05162  * States Defense * * Advanced Research Projects Agency and Transarc 
05163  * Corporation.  * ** * (C) Copyright 1991 Transarc Corporation * ** * 
05164  * Redistribution and use in source and binary forms are permitted * 
05165  * provided that: (1) source distributions retain this entire copy- * * 
05166  * right notice and comment, and (2) distributions including binaries * * 
05167  * display the following acknowledgement: * ** * ''This product includes 
05168  * software developed by Transarc * * Corporation and its contributors'' * 
05169  * ** * in the documentation or other materials mentioning features or * * 
05170  * use of this software. Neither the name of Transarc nor the names * * of 
05171  * its contributors may be used to endorse or promote products * * derived 
05172  * from this software without specific prior written * * permission.  * ** 
05173  * * THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED * 
05174  * * WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF * 
05175  * * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. 
05176  * =======================================================================*/
05177  * 
05178  * package RXDEMO_ 
05179  * %#include <rx/rx.h> 
05180  * %#include <rx/rx_null.h> 
05181  * %#define RXDEMO_SERVER_PORT 8000 /* Service port to advertise */
05182  * %#define RXDEMO_SERVICE_PORT 0 /* User server's port */
05183  * %#define RXDEMO_SERVICE_ID 4 /* Service ID */
05184  * %#define RXDEMO_NULL_SECOBJ_IDX 0 /* Index of null security object */
05185  * 
05186  * /* Maximum number of requests that will be handled by this service 
05187  *  * simultaneously. This number will be guaranteed to execute in 
05188  *  * parallel if other service's results are being processed. */
05189  * 
05190  * %#define RXDEMO_MAX 3 
05191  * 
05192  * /* Minimum number of requests that are guaranteed to be 
05193  *  * handled simultaneously. */
05194  * 
05195  * %#define RXDEMO_MIN 2 
05196  * 
05197  * /* Index of the "null" security class in the sample service. */
05198  * 
05199  * %#define RXDEMO_NULL 0 
05200  * 
05201  * /* Maximum number of characters in a file name (for demo purposes). */
05202  * 
05203  * %#define RXDEMO_NAME_MAX_CHARS 64 
05204  * 
05205  * /* Define the max number of bytes to transfer at one shot. */
05206  * 
05207  * %#define RXDEMO_BUFF_BYTES 512 
05208  * 
05209  * /* Values returned by the RXDEMO_Getfile() call. 
05210  *  * RXDEMO_CODE_SUCCESS : Everything went fine. 
05211  *  * RXDEMO_CODE_CANT_OPEN : Can't open named file. 
05212  *  * RXDEMO_CODE_CANT_STAT : Can't stat open file. 
05213  *  * RXDEMO_CODE_CANT_READ : Error reading the open file. 
05214  *  * RXDEMO_CODE_WRITE_ERROR : Error writing the open file. */
05215  * 
05216  * /* ------------Interface calls defined for this service ----------- */
05217  * %#define RXDEMO_CODE_SUCCESS 0 
05218  * %#define RXDEMO_CODE_CANT_OPEN 1 
05219  * %#define RXDEMO_CODE_CANT_STAT 2 
05220  * %#define RXDEMO_CODE_CANT_READ 3 
05221  * %#define RXDEMO_CODE_WRITE_ERROR 4 
05222  * /* -------------------------------------------------------------------
05223  * * RXDEMO_Add * 
05224  * *    
05225  * * Summary: 
05226  * *    Add the two numbers provided and return the result. * 
05227  * * Parameters: 
05228  * *    int a_first : first operand. 
05229  * *    int a_second : Second operand. 
05230  * *    int *a_result : Sum of the above. * 
05231  * *    Side effects: None.  
05232  * *-------------------------------------------------------------------- */
05233  * 
05234  * Add(IN int a, int b, OUT int *result) = 1; 
05235  * /*-------------------------------------------------------------------
05236  * * RXDEMO_Getfile * 
05237  * * Summary: 
05238  * *    Return the contents of the named file in the server's environment. 
05239  * * Parameters: 
05240  * *    STRING a_nameToRead : Name of the file whose contents are to be 
05241  * *    fetched. 
05242  * *    int *a_result : Set to the result of opening and reading the file 
05243  * *    on the server side. * 
05244  * *    Side effects: None. 
05245  * *-------------------------------------------------------------------- */
05246  * 
05247  * Getfile(IN string a_nameToRead<RXDEMO_NAME_MAX_CHARS>, OUT int *a_result) 
05248  *      split = 2; 
05249  * \endcode
05250  * 
05251  *      \subsection sec6-2-2 Section 6.2.2: Client Program: rxdemo client.c 
05252  * 
05253  * \par
05254  * The rxdemo client program, rxdemo client, calls upon the associated server
05255  * to perform operations defined by rxdemo.xg. After its header, it defines a
05256  * private GetIPAddress() utility routine, which given a character string host
05257  * name will return its IP address. 
05258  * 
05259  * \code
05260  * /*======================================================================= 
05261  * % Client side of an example Rx application, using both standard and % % 
05262  * streamed calls.  % %% % Edward R. Zayas % % Transarc Corporation % %% 
05263  * %% % The United States Government has rights in this work pursuant % % 
05264  * to contract no. MDA972-90-C-0036 between the United States Defense % % 
05265  * Advanced Research Projects Agency and Transarc Corporation.  % %% % (C) 
05266  * Copyright 1991 Transarc Corporation % %% % Redistribution and use in source 
05267  * and binary forms are permitted % % provided that: (1) source distributions 
05268  * retain this entire copy- % % right notice and comment, and (2) distributions 
05269  * including binaries % % display the following acknowledgement: % %% % 
05270  * ''This product includes software developed by Transarc % % Corporation and 
05271  * its contributors'' % %% % in the documentation or other materials mentioning 
05272  * features or % % use of this software. Neither the name of Transarc nor the 
05273  * names % % of its contributors may be used to endorse or promote products % % 
05274  * derived from this software without specific prior written % % permission. 
05275  * % %% % THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED 
05276  * % % WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF % % 
05277  * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. 
05278  * % %=======================================================================
05279  * */
05280  * 
05281  * #include <sys/types.h> 
05282  * #include <netdb.h> 
05283  * #include <stdio.h> 
05284  * #include "rxdemo.h" 
05285  * static char pn[] = "rxdemo"; /* Program name */
05286  * static u_long GetIpAddress(a_hostName) char *a_hostName; 
05287  * { /* GetIPAddress */
05288  *      static char rn[] = "GetIPAddress"; /* Routine name */
05289  *      struct hostent *hostEntP; /* Ptr to host descriptor */
05290  *      u_long hostIPAddr; /* Host IP address */
05291  *      hostEntP = gethostbyname(a_hostName); 
05292  *      if (hostEntP == (struct hostent *)0) { 
05293  *              printf("[%s:%s] Host '%s' not found\n", 
05294  *              pn, rn, a_hostName); 
05295  *              exit(1); 
05296  *      } 
05297  *      if (hostEntP->h_length != sizeof(u_long)) { 
05298  *              printf("[%s:%s] Wrong host address length (%d bytes instead of
05299  *              %d)", 
05300  *              pn, rn, hostEntP->h_length, sizeof(u_long)); 
05301  *              exit(1); 
05302  *      } 
05303  *      bcopy(hostEntP->h_addr, (char *)&hostIPAddr, sizeof(hostIPAddr)); 
05304  *      return(hostIPAddr); 
05305  * } /* GetIpAddress */
05306  * \endcode
05307  * 
05308  * \par
05309  * The main program section of the client code, after handling its command line
05310  * arguments, starts off by initializing the Rx facility. 
05311  * 
05312  * \code
05313  * main(argc, argv) 
05314  * int argc; 
05315  * char **argv; 
05316  * { /* Main */
05317  *      struct rx_connection *rxConnP; /* Ptr to server connection */
05318  *      struct rx_call *rxCallP; /* Ptr to Rx call descriptor */
05319  *      u_long hostIPAddr; /* IP address of chosen host */
05320  *      int demoUDPPort; /* UDP port of Rx service */
05321  *      struct rx_securityClass *nullSecObjP; /* Ptr to null security object */
05322  *      int operand1, operand2; /* Numbers to add int sum; Their sum */
05323  *      int code; /* Return code */
05324  *      char fileName[64]; /* Buffer for desired file's name */
05325  *      long fileDataBytes; /* Num bytes in file to get */
05326  *      char buff[RXDEMO_BUFF_BYTES+1]; /* Read buffer */
05327  *      int currBytesToRead; /* Num bytes to read in one iteration */
05328  *      int maxBytesToRead; /* Max bytes to read in one iteration */
05329  *      int bytesReallyRead; /* Num bytes read off Rx stream */
05330  *      int getResults; /* Results of the file fetch */
05331  *      printf("\n%s: Example Rx client process\n\n", pn); 
05332  *      if ((argc < 2) || (argc > 3)) { 
05333  *              printf("Usage: rxdemo <HostName> [PortToUse]"); 
05334  *              exit(1); 
05335  *      } 
05336  *      hostIPAddr = GetIpAddress(argv[1]); 
05337  *      if (argc > 2) 
05338  *              demoUDPPort = atoi(argv[2]); 
05339  *      else 
05340  *              demoUDPPort = RXDEMO_SERVER_PORT; 
05341  *      /* Initialize the Rx facility. */
05342  *      code = rx_Init(htons(demoUDPPort)); 
05343  *      if (code) { 
05344  *              printf("**      Error calling rx_Init(); code is %d\n", code); 
05345  *              exit(1); 
05346  *      } 
05347  *      /* Create a client-side null security object. */
05348  *      nullSecObjP = rxnull_NewClientSecurityObject(); 
05349  *      if (nullSecObjP == (struct rx_securityClass *)0) { 
05350  *              printf("%s: Can't create a null client-side security
05351  *              object!\n", pn); 
05352  *              exit(1); 
05353  *      } 
05354  *      /* Set up a connection to the desired Rx service, telling it to use
05355  *      * the null security object we just created.  */
05356  *      printf("Connecting to Rx server on '%s', IP address 0x%x, UDP port
05357  *      %d\n", argv[1], hostIPAddr, demoUDPPort); 
05358  *      rxConnP = rx_NewConnection(hostIPAddr, RXDEMO_SERVER_PORT,
05359  *      RXDEMO_SERVICE_ID, nullSecObjP, RXDEMO_NULL_SECOBJ_IDX); 
05360  *      if (rxConnP == (struct rx_connection *)0) { 
05361  *              printf("rxdemo: Can't create connection to server!\n"); 
05362  *              exit(1); 
05363  *      } else 
05364  *              printf(" ---> Connected.\n"); 
05365  * \endcode
05366  * 
05367  * \par
05368  * The rx Init() invocation initializes the Rx library and defines the desired
05369  * service UDP port (in network byte order). The rxnull
05370  * NewClientSecurityObject() call creates a client-side Rx security object that
05371  * does not perform any authentication on Rx calls. Once a client
05372  * authentication object is in hand, the program calls rx NewConnection(),
05373  * specifying the host, UDP port, Rx service ID, and security information
05374  * needed to establish contact with the rxdemo server entity that will be
05375  * providing the service. 
05376  * \par
05377  * With the Rx connection in place, the program may perform RPCs. The first one
05378  * to be invoked is RXDEMO Add(): 
05379  *  
05380  * \code
05381  * /* Perform our first, simple remote procedure call. */
05382  * operand1 = 1; 
05383  * operand2 = 2; 
05384  * printf("Asking server to add %d and %d: ", operand1, operand2); 
05385  * code = RXDEMO_Add(rxConnP, operand1, operand2, &sum); 
05386  * if (code) { 
05387  *      printf("  // ** Error in the RXDEMO_Add RPC: code is %d\n", code); 
05388  *      exit(1); 
05389  * } 
05390  * printf("Reported sum is %d\n", sum); 
05391  * \endcode
05392  * 
05393  * \par
05394  * The first argument to RXDEMO Add() is a pointer to the Rx connection
05395  * established above. The client-side body of the RXDEMO Add() function was
05396  * generated from the rxdemo.xg interface file, and resides in the rxdemo.cs.c
05397  * file (see Section 6.3.1). It gives the appearance of being a normal C
05398  * procedure call. 
05399  * \par
05400  * The second RPC invocation involves the more complex, streamed RXDEMO
05401  * Getfile() function. More of the internal Rx workings are exposed in this
05402  * type of call. The first additional detail to consider is that we must
05403  * manually create a new Rx call on the connection. 
05404  *  
05405  * \code
05406  * /* Set up for our second, streamed procedure call. */
05407  * printf("Name of file to read from server: "); 
05408  * scanf("%s", fileName); 
05409  * maxBytesToRead = RXDEMO_BUFF_BYTES; 
05410  * printf("Setting up an Rx call for RXDEMO_Getfile..."); 
05411  * rxCallP = rx_NewCall(rxConnP); 
05412  * if (rxCallP == (struct rx_call *)0) { 
05413  *      printf("** Can't create call\n"); 
05414  *      exit(1); 
05415  * } 
05416  * printf("done\n"); 
05417  * \endcode
05418  * 
05419  * \par
05420  * Once the Rx call structure has been created, we may begin executing the call
05421  * itself. Having been declared to be split in the interface file, Rxgen
05422  * creates two function bodies for rxdemo Getfile() and places them in
05423  * rxdemo.cs.c. The first, StartRXDEMO Getfile(), is responsible for
05424  * marshalling the outgoing arguments and issuing the RPC. The second,
05425  * EndRXDEMO Getfile(), takes care of unmarshalling the non-streamed OUT
05426  * function parameters. The following code fragment illustrates how the RPC is
05427  * started, using the StartRXDEMO Getfile() routine to pass the call parameters
05428  * to the server. 
05429  *  
05430  * \code
05431  * /* Sending IN parameters for the streamed call. */
05432  * code = StartRXDEMO_Getfile(rxCallP, fileName); 
05433  * if (code) { 
05434  *      printf("**      Error calling StartRXDEMO_Getfile(); code is %d\n",
05435  *      code); 
05436  *      exit(1); 
05437  * } 
05438  * \endcode
05439  * 
05440  * \par
05441  * Once the call parameters have been shipped, the server will commence
05442  * delivering the "stream" data bytes back to the client on the given Rx call
05443  * structure. The first longword to come back on the stream specifies the
05444  * number of bytes to follow. 
05445  *  
05446  * \par
05447  * Begin reading the data being shipped from the server in response to * our
05448  * setup call. The first longword coming back on the Rx call is 
05449  * the number of bytes to follow. It appears in network byte order, 
05450  * so we have to fix it up before referring to it. 
05451  * 
05452  * \code
05453  * bytesReallyRead = rx_Read(rxCallP, &fileDataBytes, sizeof(long)); 
05454  * if (bytesReallyRead != sizeof(long)) { 
05455  *      printf("** Only %d bytes read for file length; should have been %d\n",
05456  *      bytesReallyRead, sizeof(long)); 
05457  *      exit(1); 
05458  * } 
05459  * fileDataBytes = ntohl(fileDataBytes); 
05460  * \endcode
05461  * 
05462  * \par
05463  * Once the client knows how many bytes will be sent, it runs a loop in which
05464  * it reads a buffer at a time from the Rx call stream, using rx Read() to
05465  * accomplish this. In this application, all that is done with each
05466  * newly-acquired buffer of information is printing it out. 
05467  * 
05468  * \code 
05469  * /* Read the file bytes via the Rx call, a buffer at a time. */
05470  * printf("[file contents (%d bytes) fetched over the Rx call appear
05471  * below]\n\n", fileDataBytes); 
05472  * while (fileDataBytes > 0) 
05473  * { 
05474  *      currBytesToRead = (fileDataBytes > maxBytesToRead ?  maxBytesToRead :
05475  *      fileDataBytes); 
05476  *      bytesReallyRead = rx_Read(rxCallP, buff, currBytesToRead); 
05477  *      if (bytesReallyRead != currBytesToRead)
05478  *      { 
05479  *              printf("\nExpecting %d bytes on this read, got %d instead\n",
05480  *              currBytesToRead, bytesReallyRead); 
05481  *              exit(1); 
05482  *      }  
05483  *      /* Null-terminate the chunk before printing it. */
05484  *      buff[currBytesToRead] = 0; 
05485  *      printf("%s", buff); 
05486  *      /* Adjust the number of bytes left to read. */
05487  *      fileDataBytes -= currBytesToRead; 
05488  * } /* Read one bufferful of the file */
05489  * \endcode
05490  * 
05491  * \par
05492  * After this loop terminates, the Rx stream has been drained of all data. The
05493  * Rx call is concluded by invoking the second of the two
05494  * automatically-generated functions, EndRXDEMO Getfile(), which retrieves the
05495  * call's OUT parameter from the server. 
05496  * 
05497  * \code
05498  * /* finish off the Rx call, getting the OUT parameters. */
05499  * printf("\n\n[End of file data]\n"); 
05500  * code = EndRXDEMO_Getfile(rxCallP, &getResults); 
05501  * if (code) 
05502  * { 
05503  *      printf("**      Error getting file transfer results; code is %d\n",
05504  *      code); 
05505  *      exit(1); 
05506  * } 
05507  * \endcode
05508  * 
05509  * \par
05510  * With both normal and streamed Rx calls accomplished, the client demo code
05511  * concludes by terminating the Rx call it set up earlier. With that done, the
05512  * client exits. 
05513  * 
05514  * \code 
05515  * /* finish off the Rx call. */
05516  * code = rx_EndCall(rxCallP, code); 
05517  * if (code) 
05518  *      printf("Error   in calling rx_EndCall(); code is %d\n", code); 
05519  * 
05520  * printf("\n\nrxdemo complete.\n"); 
05521  * \endcode
05522  * 
05523  *      \subsection sec6-2-3 Server Program: rxdemo server.c 
05524  * 
05525  * \par
05526  * The rxdemo server program, rxdemo server, implements the operations promised
05527  * in the rxdemo.xg interface file. 
05528  * \par
05529  * After the initial header, the external function RXDEMO ExecuteRequest() is
05530  * declared. The RXDEMO ExecuteRequest() function is generated automatically by
05531  * rxgen from the interface file and deposited in rxdemo.ss.c. The main program
05532  * listed below will associate this RXDEMO ExecuteRequest() routine with the Rx
05533  * service to be instantiated. 
05534  * 
05535  * \code
05536  * /*======================================================================
05537  * % % Advanced Research Projects Agency and Transarc Corporation.  % %% % 
05538  * (C) Copyright 1991 Transarc Corporation % %% % Redistribution and use in 
05539  * source and binary forms are permitted % % provided that: (1) source 
05540  * distributions retain this entire copy- % % right notice and comment, and 
05541  * (2) distributions including binaries % % display the following 
05542  * acknowledgement: % %% % ''This product includes software developed by 
05543  * Transarc % % Corporation and its contributors'' % %% % in the documentation 
05544  * or other materials mentioning features or % % use of this software. Neither 
05545  * the name of Transarc nor the names % % of its contributors may be used to 
05546  * endorse or promote products % % derived from this software without specific 
05547  * prior written % % permission.  % %% % THIS SOFTWARE IS PROVIDED "AS IS" AND 
05548  * WITHOUT ANY EXPRESS OR IMPLIED % % WARRANTIES, INCLUDING, WITHOUT
05549  * LIMITATION, 
05550  * THE IMPLIED WARRANTIES OF % % MERCHANTABILITY AND FITNESS FOR A PARTICULAR 
05551  * PURPOSE.  % %
05552  * ====================================================================== */
05553  * 
05554  * /* Server portion of the example RXDEMO application, using both % 
05555  * standard and streamed calls. % % Edward R. Zayas % Transarc Corporation % 
05556  * % % The United States Government has rights in this work pursuant % 
05557  * to contract no. MDA972-90-C-0036 between the United States Defense % */
05558  * 
05559  * #include <sys/types.h> 
05560  * #include <sys/stat.h> 
05561  * #include <sys/file.h> 
05562  * #include <netdb.h> 
05563  * #include <stdio.h> 
05564  * #include "rxdemo.h" 
05565  * #define N_SECURITY_OBJECTS 1 
05566  * extern RXDEMO_ExecuteRequest(); 
05567  * \endcode
05568  * 
05569  * \par
05570  * After choosing either the default or user-specified UDP port on which the Rx
05571  * service will be established, rx Init() is called to set up the library. 
05572  * 
05573  * \code
05574  * main(argc, argv) 
05575  *      int argc; 
05576  *      char **argv; 
05577  * { /* Main */
05578  *      static char pn[] = "rxdemo_server"; /* Program name */
05579  *      struct rx_securityClass 
05580  *      (securityObjects[1]); /* Security objs */
05581  *      struct rx_service *rxServiceP; /* Ptr to Rx service descriptor */
05582  *      struct rx_call *rxCallP; /* Ptr to Rx call descriptor */
05583  *      int demoUDPPort; /* UDP port of Rx service */
05584  *      int fd; /* file descriptor */
05585  *      int code; /* Return code */
05586  *      printf("\n%s: Example Rx server process\n\n", pn); 
05587  *      if (argc >2) { 
05588  *              printf("Usage: rxdemo [PortToUse]"); 
05589  *              exit(1); 
05590  *      } 
05591  *      if (argc > 1) 
05592  *              demoUDPPort = atoi(argv[1]); 
05593  *      else 
05594  *              demoUDPPort = RXDEMO_SERVER_PORT; 
05595  * 
05596  *      /* Initialize the Rx facility, telling it the UDP port number this 
05597  *      * server will use for its single service.  */
05598  * 
05599  *      printf("Listening on UDP port %d\n", demoUDPPort); 
05600  *      code = rx_Init(demoUDPPort); 
05601  *      if (code) { 
05602  *              printf("**      Error calling rx_Init(); code is %d\n", code); 
05603  *              exit(1); 
05604  *      } 
05605  * \endcode
05606  *  
05607  * \par
05608  * A security object specific to the server side of an Rx conversation is
05609  * created in the next code fragment. As with the client side of the code, a
05610  * "null" server security object, namely one that does not perform any
05611  * authentication at all, is constructed with the rxnull
05612  * NewServerSecurityObject() function. 
05613  *  
05614  * \code
05615  *      /* Create a single server-side security object. In this case, the 
05616  *      * null security object (for unauthenticated connections) will be used 
05617  *      * to control security on connections made to this server. */
05618  * 
05619  *      securityObjects[RXDEMO_NULL_SECOBJ_IDX] =
05620  *      rxnull_NewServerSecurityObject(); 
05621  *      if (securityObjects[RXDEMO_NULL_SECOBJ_IDX] == (struct rx_securityClass
05622  *      *) 0) { 
05623  *              printf("** Can't create server-side security object\n"); 
05624  *              exit(1); 
05625  *      } 
05626  * \endcode
05627  * 
05628  * \par
05629  * The rxdemo server program is now in a position to create the desired Rx
05630  * service, primed to recognize exactly those interface calls defined in
05631  * rxdemo.xg. This is accomplished by calling the rx NewService() library
05632  * routine, passing it the security object created above and the generated Rx
05633  * dispatcher routine. 
05634  * 
05635  * \code 
05636  * /* Instantiate a single sample service. The rxgen-generated procedure 
05637  * * called to dispatch requests is passed in (RXDEMO_ExecuteRequest).  */
05638  * 
05639  *      rxServiceP = rx_NewService(     0, 
05640  *                                      RXDEMO_SERVICE_ID, 
05641  *                                      "rxdemo", 
05642  *                                      securityObjects, 
05643  *                                      1, 
05644  *                                      RXDEMO_ExecuteRequest
05645  *                              ); 
05646  *      if (rxServiceP == (struct rx_service *) 0) { 
05647  *              printf("** Can't create Rx service\n"); 
05648  *              exit(1); 
05649  *      } 
05650  * \endcode
05651  * 
05652  * \par
05653  * The final step in this main routine is to activate servicing of calls to the
05654  * exported Rx interface. Specifically, the proper number of threads are
05655  * created to handle incoming interface calls. Since we are passing a non-zero
05656  * argument to the rx StartServer() call, the main program will itself begin
05657  * executing the server thread loop, never returning from the rx StartServer()
05658  * call. The print statement afterwards should never be executed, and its
05659  * presence represents some level of paranoia, useful for debugging
05660  * malfunctioning thread packages. 
05661  * 
05662  * \code 
05663  *      /* Start up Rx services, donating this thread to the server pool. */
05664  *      rx_StartServer(1); 
05665  *      /* We should never return from the previous call. */
05666  *      printf("** rx_StartServer() returned!!\n"); exit(1); 
05667  * } /* Main */
05668  * \endcode
05669  * 
05670  * \par
05671  * Following the main procedure are the functions called by the
05672  * automatically-generated routines in the rxdemo.ss.c module to implement the
05673  * specific routines defined in the Rx interface. 
05674  * \par
05675  * The first to be defined is the RXDEMO Add() function. The arguments for this
05676  * routine are exactly as they appear in the interface definition, with the
05677  * exception of the very first. The a rxCallP parameter is a pointer to the Rx
05678  * structure describing the call on which this function was activated. All
05679  * user-supplied routines implementing an interface function are required to
05680  * have a pointer to this structure as their first parameter. Other than
05681  * printing out the fact that it has been called and which operands it
05682  * received, all that RXDEMO Add() does is compute the sum and place it in the
05683  * output parameter. 
05684  * \par
05685  * Since RXDEMO Add() is a non-streamed function, with all data travelling
05686  * through the set of parameters, this is all that needs to be done. To mark a
05687  * successful completion, RXDEMO Add() returns zero, which is passed all the
05688  * way through to the RPC's client. 
05689  * 
05690  * \code
05691  * int RXDEMO_Add(a_rxCallP, a_operand1, a_operand2, a_resultP) 
05692  *      struct rx_call *a_rxCallP; 
05693  * int a_operand1, a_operand2; 
05694  * int *a_resultP; 
05695  * { /* RXDEMO_Add */
05696  *      printf("\t[Handling call to RXDEMO_Add(%d, %d)]\n", 
05697  *              a_operand1, a_operand2); 
05698  *      *a_resultP = a_operand1 + a_operand2; 
05699  *      return(0); 
05700  * } /* RXDEMO_Add */
05701  * \endcode
05702  * 
05703  * \par
05704  * The next and final interface routine defined in this file is RXDEMO
05705  * Getfile(). Declared as a split function in the interface file, RXDEMO
05706  * Getfile() is an example of a streamed Rx call. As with RXDEMO Add(), the
05707  * initial parameter is required to be a pointer to the Rx call structure with
05708  * which this routine is associated, Similarly, the other parameters appear
05709  * exactly as in the interface definition, and are handled identically. 
05710  * \par
05711  * The difference between RXDEMO Add() and RXDEMO Getfile() is in the use of
05712  * the rx Write() library routine by RXDEMO Getfile() to feed the desired
05713  * file's data directly into the Rx call stream. This is an example of the use
05714  * of the a rxCallP argument, providing all the information necessary to
05715  * support the rx Write() activity. 
05716  * \par
05717  * The RXDEMO Getfile() function begins by printing out the fact that it's been
05718  * called and the name of the requested file. It will then attempt to open the
05719  * requested file and stat it to determine its size. 
05720  * 
05721  * \code
05722  * int RXDEMO_Getfile(a_rxCallP, a_nameToRead, a_resultP) 
05723  *      struct rx_call *a_rxCallP; 
05724  * char *a_nameToRead; 
05725  * int *a_resultP; 
05726  * { /* RXDEMO_Getfile */
05727  *      struct stat fileStat; /* Stat structure for file */
05728  *      long fileBytes; /* Size of file in bytes */
05729  *      long nbofileBytes; /* file bytes in network byte order */
05730  *      int code; /* Return code */
05731  *      int bytesReallyWritten; /* Bytes written on Rx channel */
05732  *      int bytesToSend; /* Num bytes to read & send this time */
05733  *      int maxBytesToSend; /* Max num bytes to read & send ever */
05734  *      int bytesRead; /* Num bytes read from file */
05735  *      char buff[RXDEMO_BUFF_BYTES+1]; /* Read buffer */
05736  *      int fd; /* file descriptor */
05737  *      maxBytesToSend = RXDEMO_BUFF_BYTES; 
05738  *      printf("\t[Handling call to RXDEMO_Getfile(%s)]\n", a_nameToRead); 
05739  *      fd = open(a_nameToRead, O_RDONLY, 0444); 
05740  *      if (fd <0) { 
05741  *              printf("\t\t[**Can't open file '%s']\n", a_nameToRead); 
05742  *              *a_resultP = RXDEMO_CODE_CANT_OPEN; 
05743  *              return(1); 
05744  *      } else 
05745  *              printf("\t\t[file opened]\n"); 
05746  *      /* Stat the file to find out how big it is. */
05747  *      code = fstat(fd, &fileStat); 
05748  *      if (code) { 
05749  *              a_resultP = RXDEMO_CODE_CANT_STAT; 
05750  *              printf("\t\t[file closed]\n"); 
05751  *              close(fd); 
05752  *              return(1); 
05753  *      } 
05754  *      fileBytes = fileStat.st_size; 
05755  *      printf("\t\t[file has %d bytes]\n", fileBytes); 
05756  * \endcode
05757  * 
05758  * \par
05759  * Only standard unix operations have been used so far. Now that the file is
05760  * open, we must first feed the size of the file, in bytes, to the Rx call
05761  * stream. With this information, the client code can then determine how many
05762  * bytes will follow on the stream. As with all data that flows through an Rx
05763  * stream, the longword containing the file size, in bytes, must be converted
05764  * to network byte order before being sent. This insures that the recipient may
05765  * properly interpret the streamed information, regardless of its memory
05766  * architecture. 
05767  * 
05768  * \code
05769  *      nbofileBytes = htonl(fileBytes); 
05770  *      /* Write out the size of the file to the Rx call. */
05771  *      bytesReallyWritten = rx_Write(a_rxCallP, &nbofileBytes, sizeof(long)); 
05772  *      if (bytesReallyWritten != sizeof(long)) { 
05773  *              printf("** %d bytes written instead of %d for file length\n", 
05774  *              bytesReallyWritten, sizeof(long)); 
05775  *              *a_resultP = RXDEMO_CODE_WRITE_ERROR; 
05776  *              printf("\t\t[file closed]\n"); 
05777  *              close(fd); 
05778  *              return(1); 
05779  *      } 
05780  * \endcode
05781  * 
05782  * \par
05783  * Once the number of file bytes has been placed in the stream, the RXDEMO
05784  * Getfile() routine runs a loop, reading a buffer's worth of the file and then
05785  * inserting that buffer of file data into the Rx stream at each iteration.
05786  * This loop executes until all of the file's bytes have been shipped. Notice
05787  * there is no special end-of-file character or marker inserted into the
05788  * stream. 
05789  * \par
05790  * The body of the loop checks for both unix read() and rx Write errors. If
05791  * there is a problem reading from the unix file into the transfer buffer, it
05792  * is reflected back to the client by setting the error return parameter
05793  * appropriately. Specifically, an individual unix read() operation could fail
05794  * to return the desired number of bytes. Problems with rx Write() are handled
05795  * similarly. All errors discovered in the loop result in the file being
05796  * closed, and RXDEMO Getfile() exiting with a non-zero return value. 
05797  *  
05798  * \code
05799  *      /* Write out the contents of the file, one buffer at a time.  */
05800  *      while (fileBytes > 0) {  
05801  *              /* figure out the number of bytes to 
05802  *              * read (and send) this time.  */
05803  *              bytesToSend = (fileBytes > maxBytesToSend ? 
05804  *                              maxBytesToSend : fileBytes); 
05805  *              bytesRead = read(fd, buff, bytesToSend); 
05806  *              if (bytesRead != bytesToSend) { 
05807  *                      printf("Read %d instead of %d bytes from the file\n", 
05808  *                              bytesRead, bytesToSend); 
05809  *                      *a_resultP = RXDEMO_CODE_WRITE_ERROR; 
05810  *                      printf("\t\t[file closed]\n"); 
05811  *                      close(fd); 
05812  *                      return(1); 
05813  *              } 
05814  *              /* Go ahead and send them. */
05815  *              bytesReallyWritten = rx_Write(a_rxCallP, buff, bytesToSend); 
05816  *              if (bytesReallyWritten != bytesToSend) { 
05817  *                      printf("%d file bytes written instead of %d\n", 
05818  *                              bytesReallyWritten, bytesToSend); 
05819  *                      *a_resultP = RXDEMO_CODE_WRITE_ERROR; 
05820  *                      printf("\t\t[file closed]\n"); 
05821  *                      close(fd); 
05822  *                      return(1); 
05823  *              } 
05824  *              /* Update the number of bytes left to go. */
05825  *              fileBytes -= bytesToSend; 
05826  *      } /* Write out the file to our caller */
05827  * \endcode
05828  * 
05829  * \par
05830  * Once all of the file's bytes have been shipped to the remote client, all
05831  * that remains to be done is to close the file and return successfully. 
05832  * 
05833  * \code
05834  *      /* Close the file, then return happily. */
05835  *      *a_resultP = RXDEMO_CODE_SUCCESS; 
05836  *      printf("\t\t[file closed]\n"); 
05837  *      close(fd); 
05838  *      return(0); 
05839  * } /* RXDEMO_Getfile */
05840  * \endcode
05841  * 
05842  *      \subsection sec6-2-4 Section 6.2.4: Makefile 
05843  * 
05844  * \par
05845  * This file directs the compilation and installation of the rxdemo code. It
05846  * specifies the locations of libraries, include files, sources, and such tools
05847  * as Rxgen and install, which strips symbol tables from executables and places
05848  * them in their target directories. This Makefile demostrates cross-cell
05849  * software development, with the rxdemo sources residing in the
05850  * grand.central.org cell and the AFS include files and libraries accessed from
05851  * their locations in the transarc.com cell. 
05852  * \par
05853  * In order to produce and install the rxdemo server and rxdemo client
05854  * binaries, the system target should be specified on the command line when
05855  * invoking make: 
05856  * \code
05857  *              make system 
05858  * \endcode
05859  * \par
05860  * A note of caution is in order concerning generation of the rxdemo binaries.
05861  * While tools exist that deposit the results of all compilations to other
05862  * (architecture-specific) directories, and thus facilitate multiple
05863  * simultaneous builds across a variety of machine architectures (e.g.,
05864  * Transarc's washtool), the assumption is made here that compilations will
05865  * take place directly in the directory containing all the rxdemo sources.
05866  * Thus, a user will have to execute a make clean command to remove all
05867  * machine-specific object, library, and executable files before compiling for
05868  * a different architecture. Note, though, that the binaries are installed into
05869  * a directory specifically reserved for the current machine type.
05870  * Specifically, the final pathname component of the ${PROJ DIR}bin
05871  * installation target is really a symbolic link to ${PROJ DIR}.bin/@sys. 
05872  * \par
05873  * Two libraries are needed to support the rxdemo code. The first is obvious,
05874  * namely the Rx librx.a library. The second is the lightweight thread package
05875  * library, liblwp.a, which implements all the threading operations that must
05876  * be performed. The include files are taken from the unix /usr/include
05877  * directory, along with various AFS-specific directories. Note that for
05878  * portability reasons, this Makefile only contains fully-qualified AFS
05879  * pathnames and "standard" unix pathnames (such as /usr/include). 
05880  * 
05881  * \code
05882  * /*#=======================================================================# 
05883  * # The United States Government has rights in this work pursuant # # to 
05884  * contract no. MDA972-90-C-0036 between the United States Defense # # Advanced 
05885  * Research Projects Agency and Transarc Corporation. # # # # (C) Copyright
05886  * 1991 
05887  * Transarc Corporation # # # # Redistribution and use in source and binary
05888  * forms 
05889  * are permitted # # provided that: (1) source distributions retain this entire 
05890  * copy-# # right notice and comment, and (2) distributions including binaries
05891  * # 
05892  * # display the following acknowledgement: # # # # ''This product includes 
05893  * software developed by Transarc # # Corporation and its contributors'' # # #
05894  * # 
05895  * in the documentation or other materials mentioning features or # # use of
05896  * this 
05897  * software. Neither the name of Transarc nor the names # # of its contributors 
05898  * may be used to endorse or promote products # # derived from this software 
05899  * without specific prior written # # permission. # # # # THIS SOFTWARE IS 
05900  * PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED # # WARRANTIES,
05901  * INCLUDING, 
05902  * WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF # # MERCHANTABILITY AND
05903  * FITNESS 
05904  * FOR A PARTICULAR PURPOSE. # 
05905  * #=======================================================================# */
05906  * 
05907  * SHELL = /bin/sh 
05908  * TOOL_CELL = grand.central.org 
05909  * AFS_INCLIB_CELL = transarc.com 
05910  * USR_CONTRIB = /afs/${TOOL_CELL}/darpa/usr/contrib/ 
05911  * PROJ_DIR = ${USR_CONTRIB}.site/grand.central.org/rxdemo/ 
05912  * AFS_INCLIB_DIR = /afs/${AFS_INCLIB_CELL}/afs/dest/ 
05913  * RXGEN = ${AFS_INCLIB_DIR}bin/rxgen 
05914  * INSTALL = ${AFS_INCLIB_DIR}bin/install 
05915  * LIBS =       ${AFS_INCLIB_DIR}lib/librx.a \ ${AFS_INCLIB_DIR}lib/liblwp.a 
05916  * CFLAGS = -g \ 
05917  *      -I. \ 
05918  *      -I${AFS_INCLIB_DIR}include \ 
05919  *      -I${AFS_INCLIB_DIR}include/afs \ 
05920  *      -I${AFS_INCLIB_DIR} \ 
05921  *      -I/usr/include 
05922  * 
05923  * system: install 
05924  * 
05925  * install: all 
05926  *      ${INSTALL} rxdemo_client 
05927  *      ${PROJ_DIR}bin 
05928  *      ${INSTALL} rxdemo_server 
05929  *      ${PROJ_DIR}bin 
05930  * 
05931  * all: rxdemo_client rxdemo_server 
05932  * 
05933  * rxdemo_client: rxdemo_client.o ${LIBS} rxdemo.cs.o ${CC} ${CFLAGS} 
05934  *              -o rxdemo_client rxdemo_client.o rxdemo.cs.o ${LIBS} 
05935  * 
05936  * rxdemo_server: rxdemo_server.o rxdemo.ss.o ${LIBS} ${CC} ${CFLAGS} 
05937  *              -o rxdemo_server rxdemo_server.o rxdemo.ss.o ${LIBS} 
05938  * 
05939  * rxdemo_client.o: rxdemo.h 
05940  * 
05941  * rxdemo_server.o: rxdemo.h 
05942  * 
05943  * rxdemo.cs.c rxdemo.ss.c rxdemo.er.c rxdemo.h: rxdemo.xg rxgen rxdemo.xg 
05944  * 
05945  * clean: rm -f *.o rxdemo.cs.c rxdemo.ss.c rxdemo.xdr.c rxdemo.h \ 
05946  *              rxdemo_client rxdemo_server core 
05947  * \endcode
05948  * 
05949  *      \section sec6-3 Section 6.3: Computer-Generated files 
05950  * 
05951  * \par
05952  * The four human-generated files described above provide all the information
05953  * necessary to construct the full set of modules to support the rxdemo example
05954  * application. This section describes those routines that are generated from
05955  * the base set by Rxgen, filling out the code required to implement an Rx
05956  * service. 
05957  * 
05958  *      \subsection sec6-3-1 Client-Side Routines: rxdemo.cs.c 
05959  * 
05960  * \par
05961  * The rxdemo client.c program, described in Section 6.2.2, calls the
05962  * client-side stub routines contained in this module in order to make rxdemo
05963  * RPCs. Basically, these client-side stubs are responsible for creating new Rx
05964  * calls on the given connection parameter and then marshalling and
05965  * unmarshalling the rest of the interface call parameters. The IN and INOUT
05966  * arguments, namely those that are to be delivered to the server-side code
05967  * implementing the call, must be packaged in network byte order and shipped
05968  * along the given Rx call. The return parameters, namely those objects
05969  * declared as INOUT and OUT, must be fetched from the server side of the
05970  * associated Rx call, put back in host byte order, and inserted into the
05971  * appropriate parameter variables. 
05972  * \par
05973  * The first part of rxdemo.cs.c echoes the definitions appearing in the
05974  * rxdemo.xg interface file, and also #includes another Rxgen-generated file,
05975  * rxdemo.h. 
05976  * 
05977  * \code
05978  * /*======================================================================% 
05979  * * % THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED % 
05980  * * % WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF % 
05981  * * % MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. % 
05982  * * %====================================================================== */
05983  * /* Machine generated file --Do NOT edit */
05984  * 
05985  * #include "rxdemo.h" 
05986  * #define RXDEMO_CODE_WRITE_ERROR 4 
05987  * 
05988  * #include <rx/rx.h>
05989  * #include <rx/rx_null.h>
05990  * #define RXDEMO_SERVER_PORT 8000 /* Service port to advertise */
05991  * #define RXDEMO_SERVICE_PORT 0 /* User server's port */
05992  * #define RXDEMO_SERVICE_ID 4 /* Service ID */
05993  * #define RXDEMO_NULL_SECOBJ_IDX 0 /* Index of null security object */
05994  * #define RXDEMO_MAX 3
05995  * #define RXDEMO_MIN 2
05996  * #define RXDEMO_NULL 0 
05997  * #define RXDEMO_NAME_MAX_CHARS 64
05998  * #define RXDEMO_BUFF_BYTES 512
05999  * #define RXDEMO_CODE_SUCCESS 0
06000  * #define RXDEMO_CODE_CANT_OPEN 1
06001  * #define RXDEMO_CODE_CANT_STAT 2
06002  * #define RXDEMO_CODE_CANT_READ 3
06003  * #define RXDEMO_CODE_WRITE_ERROR 4
06004  * \endcode
06005  * 
06006  * \par
06007  * The next code fragment defines the client-side stub for the RXDEMO Add()
06008  * routine, called by the rxdemo client program to execute the associated RPC. 
06009  * 
06010  * \code
06011  * int RXDEMO_Add(z_conn, a, b, result) register struct rx_connection *z_conn; 
06012  * int a, b; 
06013  * int * result; 
06014  * { 
06015  *      struct rx_call *z_call = rx_NewCall(z_conn); 
06016  *      static int z_op = 1; 
06017  *      int z_result; 
06018  *      XDR z_xdrs; 
06019  *      xdrrx_create(&z_xdrs, z_call, XDR_ENCODE); 
06020  *      /* Marshal the arguments */
06021  *      if ((!xdr_int(&z_xdrs, &z_op)) 
06022  *                      || (!xdr_int(&z_xdrs, &a)) 
06023  *                      || (!xdr_int(&z_xdrs, &b))) { 
06024  *              z_result = RXGEN_CC_MARSHAL; 
06025  *              goto fail; 
06026  *      } 
06027  *      /* Un-marshal the reply arguments */
06028  *      z_xdrs.x_op = XDR_DECODE; 
06029  *      if ((!xdr_int(&z_xdrs, result))) { 
06030  *              z_result = RXGEN_CC_UNMARSHAL; 
06031  *              goto fail; 
06032  *      } 
06033  *      z_result = RXGEN_SUCCESS; 
06034  *      fail: return rx_EndCall(z_call, z_result); 
06035  * } 
06036  * \endcode
06037  * 
06038  * \par
06039  * The very first operation performed by RXDEMO Add() occurs in the local
06040  * variable declarations, where z call is set to point to the structure
06041  * describing a newly-created Rx call on the given connection. An XDR
06042  * structure, z xdrs, is then created for the given Rx call with xdrrx
06043  * create(). This XDR object is used to deliver the proper arguments, in
06044  * network byte order, to the matching server stub code. Three calls to xdr
06045  * int() follow, which insert the appropriate Rx opcode and the two operands
06046  * into the Rx call. With the IN arguments thus transmitted, RXDEMO Add()
06047  * prepares to pull the value of the single OUT parameter. The z xdrs XDR
06048  * structure, originally set to XDR ENCODE objects, is now reset to XDR DECODE
06049  * to convert further items received into host byte order. Once the return
06050  * parameter promised by the function is retrieved, RXDEMO Add() returns
06051  * successfully. 
06052  * \par
06053  * Should any failure occur in passing the parameters to and from the server
06054  * side of the call, the branch to fail will invoke Rx EndCall(), which advises
06055  * the server that the call has come to a premature end (see Section 5.6.6 for
06056  * full details on rx EndCall() and the meaning of its return value). 
06057  * \par
06058  * The next client-side stub appearing in this generated file handles the
06059  * delivery of the IN parameters for StartRXDEMO Getfile(). It operates
06060  * identically as the RXDEMO Add() stub routine in this respect, except that it
06061  * does not attempt to retrieve the OUT parameter. Since this is a streamed
06062  * call, the number of bytes that will be placed on the Rx stream cannot be
06063  * determined at compile time, and must be handled explicitly by rxdemo
06064  * client.c. 
06065  * 
06066  * \code
06067  * int StartRXDEMO_Getfile(z_call, a_nameToRead) 
06068  *      register struct rx_call *z_call; 
06069  * char * a_nameToRead; 
06070  * { 
06071  *      static int z_op = 2; 
06072  *      int z_result; 
06073  *      XDR z_xdrs; 
06074  *      xdrrx_create(&z_xdrs, z_call, XDR_ENCODE); 
06075  *      /* Marshal the arguments */
06076  *      if ((!xdr_int(&z_xdrs, &z_op)) || (!xdr_string(&z_xdrs, &a_nameToRead,
06077  *      RXDEMO_NAME_MAX_CHARS))) { 
06078  *              z_result = RXGEN_CC_MARSHAL; 
06079  *              goto fail; 
06080  *      } 
06081  *      z_result = RXGEN_SUCCESS; 
06082  *      fail: return z_result; 
06083  * } 
06084  * \endcode
06085  * 
06086  * \par
06087  * The final stub routine appearing in this generated file, EndRXDEMO
06088  * Getfile(), handles the case where rxdemo client.c has already successfully
06089  * recovered the unbounded streamed data appearing on the call, and then simply
06090  * has to fetch the OUT parameter. This routine behaves identially to the
06091  * latter portion of RXDEMO Getfile(). 
06092  * 
06093  * \code
06094  * int EndRXDEMO_Getfile(z_call, a_result) 
06095  *      register struct rx_call *z_call; 
06096  * int * a_result; 
06097  * { 
06098  *      int z_result; 
06099  *      XDR z_xdrs; 
06100  *      /* Un-marshal the reply arguments */
06101  *      xdrrx_create(&z_xdrs, z_call, XDR_DECODE); 
06102  *      if ((!xdr_int(&z_xdrs, a_result))) { 
06103  *              z_result = RXGEN_CC_UNMARSHAL; 
06104  *              goto fail; 
06105  *      } 
06106  *      z_result = RXGEN_SUCCESS; fail: 
06107  *      return z_result; 
06108  * } 
06109  * \endcode
06110  * 
06111  *      \subsection sec6-3-2 Server-Side Routines: rxdemo.ss.c 
06112  * 
06113  * \par
06114  * This generated file provides the core components required to implement the
06115  * server side of the rxdemo RPC service. Included in this file is the
06116  * generated dispatcher routine, RXDEMO ExecuteRequest(), which the rx
06117  * NewService() invocation in rxdemo server.c uses to construct the body of
06118  * each listener thread's loop. Also included are the server-side stubs to
06119  * handle marshalling and unmarshalling of parameters for each defined RPC call
06120  * (i.e., RXDEMO Add() and RXDEMO Getfile()). These stubs are called by RXDEMO
06121  * ExecuteRequest(). The routine to be called by RXDEMO ExecuteRequest()
06122  * depends on the opcode received, which appears as the very first longword in
06123  * the call data. 
06124  * \par
06125  * As usual, the first fragment is copyright information followed by the body
06126  * of the definitions from the interface file. 
06127  * 
06128  * \code
06129  * /*======================================================================% 
06130  * % Edward R. Zayas % % Transarc Corporation % % % % % % The United States 
06131  * Government has rights in this work pursuant % % to contract no. 
06132  * MDA972-90-C-0036 between the United States Defense % % Advanced Research 
06133  * Projects Agency and Transarc Corporation. % % % % (C) Copyright 1991 
06134  * Transarc Corporation % % % % Redistribution and use in source and binary 
06135  * forms are permitted % % provided that: (1) source distributions retain 
06136  * this entire copy¬% % right notice and comment, and (2) distributions 
06137  * including binaries % 
06138  * %====================================================================== */
06139  * /* Machine generated file --Do NOT edit */
06140  * 
06141  * #include "rxdemo.h" 
06142  * #include <rx/rx.h> 
06143  * #include <rx/rx_null.h> 
06144  * #define RXDEMO_SERVER_PORT 8000 /* Service port to advertise */
06145  * #define RXDEMO_SERVICE_PORT 0 /* User server's port */
06146  * #define RXDEMO_SERVICE_ID 4 /* Service ID */
06147  * #define RXDEMO_NULL_SECOBJ_IDX 0 /* Index of null security object */
06148  * #define RXDEMO_MAX 3 
06149  * #define RXDEMO_MIN 2 
06150  * #define RXDEMO_NULL 0 
06151  * #define RXDEMO_NAME_MAX_CHARS 64 
06152  * #define RXDEMO_BUFF_BYTES 512 
06153  * #define RXDEMO_CODE_SUCCESS 0 
06154  * #define RXDEMO_CODE_CANT_OPEN 1 
06155  * #define RXDEMO_CODE_CANT_STAT 2 
06156  * #define RXDEMO_CODE_CANT_READ 3 
06157  * #define RXDEMO_CODE_WRITE_ERROR 4 
06158  * \endcode
06159  * 
06160  * \par
06161  * After this preamble, the first server-side stub appears. This RXDEMO Add()
06162  * routine is basically the inverse of the RXDEMO Add() client-side stub
06163  * defined in rxdemo.cs.c. Its job is to unmarshall the IN parameters for the
06164  * call, invoke the "true" server-side RXDEMO Add() routine (defined in rxdemo
06165  * server.c), and then package and ship the OUT parameter. Being so similar to
06166  * the client-side RXDEMO Add(), no further discussion is offered here. 
06167  * 
06168  * \code
06169  * long _RXDEMO_Add(z_call, z_xdrs) 
06170  *      struct rx_call *z_call; 
06171  * XDR *z_xdrs; 
06172  * { 
06173  *      long z_result; 
06174  *      int a, b; 
06175  *      int result; 
06176  *      if ((!xdr_int(z_xdrs, &a)) || (!xdr_int(z_xdrs, &b))) 
06177  *      { 
06178  *              z_result = RXGEN_SS_UNMARSHAL; 
06179  *              goto fail; 
06180  *      } 
06181  *      z_result = RXDEMO_Add(z_call, a, b, &result); 
06182  *      z_xdrs->x_op = XDR_ENCODE; 
06183  *      if ((!xdr_int(z_xdrs, &result))) 
06184  *              z_result = RXGEN_SS_MARSHAL; 
06185  *      fail: return z_result; 
06186  * } 
06187  * \endcode
06188  * 
06189  * \par
06190  * The second server-side stub, RXDEMO Getfile(), appears next. It operates
06191  * identically to RXDEMO Add(), first unmarshalling the IN arguments, then
06192  * invoking the routine that actually performs the server-side work for the
06193  * call, then finishing up by returning the OUT parameters. 
06194  * 
06195  * \code
06196  * long _RXDEMO_Getfile(z_call, z_xdrs) 
06197  *      struct rx_call *z_call; 
06198  * XDR *z_xdrs; 
06199  * { 
06200  *      long z_result; 
06201  *      char * a_nameToRead=(char *)0; 
06202  *      int a_result; 
06203  *      if ((!xdr_string(z_xdrs, &a_nameToRead, RXDEMO_NAME_MAX_CHARS))) { 
06204  *              z_result = RXGEN_SS_UNMARSHAL; 
06205  *              goto fail; 
06206  *      } 
06207  *      z_result = RXDEMO_Getfile(z_call, a_nameToRead, &a_result); 
06208  *      z_xdrs->x_op = XDR_ENCODE; 
06209  *      if ((!xdr_int(z_xdrs, &a_result))) 
06210  *              z_result = RXGEN_SS_MARSHAL; 
06211  *      fail: z_xdrs->x_op = XDR_FREE; 
06212  *      if (!xdr_string(z_xdrs, &a_nameToRead, RXDEMO_NAME_MAX_CHARS)) 
06213  *              goto fail1; 
06214  *      return z_result; 
06215  *      fail1: return RXGEN_SS_XDRFREE; 
06216  * } 
06217  * \endcode
06218  * 
06219  * \par
06220  * The next portion of the automatically generated server-side module sets up
06221  * the dispatcher routine for incoming Rx calls. The above stub routines are
06222  * placed into an array in opcode order. 
06223  * 
06224  * \code
06225  * long _RXDEMO_Add(); 
06226  * long _RXDEMO_Getfile(); 
06227  * static long (*StubProcsArray0[])() = {_RXDEMO_Add, _RXDEMO_Getfile}; 
06228  * \endcode
06229  * 
06230  * \par
06231  * The dispatcher routine itself, RXDEMO ExecuteRequest, appears next. This is
06232  * the function provided to the rx NewService() call in rxdemo server.c, and it
06233  * is used as the body of each listener thread's service loop. When activated,
06234  * it decodes the first longword in the given Rx call, which contains the
06235  * opcode. It then dispatches the call based on this opcode, invoking the
06236  * appropriate server-side stub as organized in the StubProcsArray. 
06237  * 
06238  * \code
06239  * RXDEMO_ExecuteRequest(z_call) 
06240  *      register struct rx_call *z_call; 
06241  * { 
06242  *      int op; 
06243  *      XDR z_xdrs; 
06244  *      long z_result; 
06245  *      xdrrx_create(&z_xdrs, z_call, XDR_DECODE); 
06246  *      if (!xdr_int(&z_xdrs, &op)) 
06247  *              z_result = RXGEN_DECODE; 
06248  *      else if (op < RXDEMO_LOWEST_OPCODE || op > RXDEMO_HIGHEST_OPCODE) 
06249  *              z_result = RXGEN_OPCODE; 
06250  *      else 
06251  *              z_result = (*StubProcsArray0[op -RXDEMO_LOWEST_OPCODE])(z_call,
06252  *              &z_xdrs); 
06253  *      return z_result; 
06254  * } 
06255  * \endcode
06256  * 
06257  *      \subsection sec6-3-3 External Data Rep file: rxdemo.xdr.c 
06258  * 
06259  * \par
06260  * This file is created to provide the special routines needed to map any
06261  * user-defined structures appearing as Rx arguments into and out of network
06262  * byte order. Again, all on-thewire data appears in network byte order,
06263  * insuring proper communication between servers and clients with different
06264  * memory organizations. 
06265  * \par
06266  * Since the rxdemo example application does not define any special structures
06267  * to pass as arguments in its calls, this generated file contains only the set
06268  * of definitions appearing in the interface file. In general, though, should
06269  * the user define a struct xyz and use it as a parameter to an RPC function,
06270  * this file would contain a routine named xdr xyz(), which converted the
06271  * structure field-by-field to and from network byte order. 
06272  * 
06273  * \code
06274  * /*======================================================================% 
06275  * %% % in the documentation or other materials mentioning features or % % 
06276  * use of this software. Neither the name of Transarc nor the names % % of 
06277  * its contributors may be used to endorse or promote products % % derived 
06278  * from this software without specific prior written % % permission. % % % 
06279  * % THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED % 
06280  * % WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF % 
06281  * % MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. % 
06282  * % Edward R. Zayas % Transarc Corporation % % % The United States 
06283  * Government has rights in this work pursuant to contract no. 
06284  * MDA972-90-C-0036 between the United States Defense % Advanced Research 
06285  * Projects Agency and Transarc Corporation. % % (C) Copyright 1991 Transarc 
06286  * Corporation % % Redistribution and use in source and binary forms are 
06287  * permitted % % provided that: (1) source distributions retain this entire 
06288  * copy¬ % right notice and comment, and (2) distributions including binaries 
06289  * % % display the following acknowledgement: % % % % ``This product includes 
06290  * software developed by Transarc % % Corporation and its contributors'' % 
06291  * %====================================================================== */
06292  * /* Machine generated file --Do NOT edit */
06293  * 
06294  * #include "rxdemo.h" 
06295  * #include <rx/rx.h> 
06296  * #include <rx/rx_null.h> 
06297  * #define RXDEMO_SERVER_PORT 8000 /* Service port to advertise */
06298  * #define RXDEMO_SERVICE_PORT 0 /* User server's port */
06299  * #define RXDEMO_SERVICE_ID 4 /* Service ID */
06300  * #define RXDEMO_NULL_SECOBJ_IDX 0 /* Index of null security object */
06301  * #define RXDEMO_MAX 3 
06302  * #define RXDEMO_MIN 2 
06303  * #define RXDEMO_NULL 0 
06304  * #define RXDEMO_NAME_MAX_CHARS 64 
06305  * #define RXDEMO_BUFF_BYTES 512 
06306  * #define RXDEMO_CODE_SUCCESS 0 
06307  * #define RXDEMO_CODE_CANT_OPEN 1 
06308  * #define RXDEMO_CODE_CANT_STAT 2 
06309  * #define RXDEMO_CODE_CANT_READ 3 
06310  * #define RXDEMO_CODE_WRITE_ERROR 4 
06311  * \endcode
06312  * 
06313  *      \section sec6-4 Section 6.4: Sample Output 
06314  * 
06315  * \par
06316  * This section contains the output generated by running the example rxdemo
06317  * server and rxdemo client programs described above. The server end was run on
06318  * a machine named Apollo, and the client program was run on a machine named
06319  * Bigtime. 
06320  * \par
06321  * The server program on Apollo was started as follows: 
06322  * \li apollo: rxdemo_server 
06323  * \li rxdemo_server: Example Rx server process 
06324  * \li Listening on UDP port 8000 
06325  * \par
06326  * At this point, rxdemo server has initialized its Rx module and started up
06327  * its listener LWPs, which are sleeping on the arrival of an RPC from any
06328  * rxdemo client. 
06329  * \par
06330  * The client portion was then started on Bigtime: 
06331  * \n bigtime: rxdemo_client apollo 
06332  * \n rxdemo: Example Rx client process 
06333  * \n Connecting to Rx server on 'apollo', IP address 0x1acf37c0, UDP port 8000 
06334  * \n ---> Connected. Asking server to add 1 and 2: Reported sum is 3 
06335  * \par
06336  * The command line instructs rxdemo client to connect to the rxdemo server on
06337  * host apollo and to use the standard port defined for this service. It
06338  * reports on the successful Rx connection establishment, and immediately
06339  * executes an rxdemo Add(1, 2) RPC. It reports that the sum was successfully
06340  * received. When the RPC request arrived at the server and was dispatched by
06341  * the rxdemo server code, it printed out the following line: 
06342  * \n [Handling call to RXDEMO_Add(1, 2)] 
06343  * \par
06344  * Next, rxdemo client prompts for the name of the file to read from the rxdemo
06345  * server. It is told to fetch the Makefile for the Rx demo directory. The
06346  * server is executing in the same directory in which it was compiled, so an
06347  * absolute name for the Makefile is not required. The client echoes the
06348  * following: 
06349  * \n Name of file to read from server: Makefile Setting up an Rx call for
06350  * RXDEMO_Getfile...done 
06351  * \par
06352  * As with the rxdemo Add() call, rxdemo server receives this RPC, and prints
06353  * out the following information: 
06354  * \li [Handling call to RXDEMO_Getfile(Makefile)] 
06355  * \li [file opened] 
06356  * \li [file has 2450 bytes] 
06357  * \li [file closed] 
06358  * \par
06359  * It successfully opens the named file, and reports on its size in bytes. The
06360  * rxdemo server program then executes the streamed portion of the rxdemo
06361  * Getfile call, and when complete, indicates that the file has been closed.
06362  * Meanwhile, rxdemo client prints out the reported size of the file, follows
06363  * it with the file's contents, then advises that the test run has completed: 
06364  * 
06365  * \code
06366  * [file contents (2450 bytes) fetched over the Rx call appear below] 
06367  * 
06368  * /*#=======================================================================# 
06369  * # The United States Government has rights in this work pursuant # # to 
06370  * contract no. MDA972-90-C-0036 between the United States Defense # # Advanced 
06371  * Research Projects Agency and Transarc Corporation. # # # # (C) Copyright 
06372  * 1991 Transarc Corporation # # # # Redistribution and use in source and 
06373  * binary forms are permitted # # provided that: (1) source distributions 
06374  * retain this entire copy-# # right notice and comment, and (2) distributions 
06375  * including binaries # # display the following acknowledgement: # # # # ''This 
06376  * product includes software developed by Transarc # # Corporation and its 
06377  * contributors'' # # # # in the documentation or other materials mentioning 
06378  * features or # # use of this software. Neither the name of Transarc nor the 
06379  * names # # of its contributors may be used to endorse or promote products # 
06380  * # derived from this software without specific prior written # # permission. 
06381  * # # # # THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED 
06382  * # # WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF # # 
06383  * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. # 
06384  * #=======================================================================# */
06385  * 
06386  * SHELL = /bin/sh 
06387  * TOOL_CELL = grand.central.org 
06388  * AFS_INCLIB_CELL = transarc.com 
06389  * USR_CONTRIB = /afs/${TOOL_CELL}/darpa/usr/contrib/ 
06390  * PROJ_DIR = ${USR_CONTRIB}.site/grand.central.org/rxdemo/ 
06391  * AFS_INCLIB_DIR = /afs/${AFS_INCLIB_CELL}/afs/dest/ 
06392  * RXGEN = ${AFS_INCLIB_DIR}bin/rxgen 
06393  * INSTALL = ${AFS_INCLIB_DIR}bin/install 
06394  * LIBS =       ${AFS_INCLIB_DIR}lib/librx.a \ ${AFS_INCLIB_DIR}lib/liblwp.a 
06395  *      CFLAGS = -g \ 
06396  *      -I. \ 
06397  *      -I${AFS_INCLIB_DIR}include \ 
06398  *      -I${AFS_INCLIB_DIR}include/afs \ 
06399  *      -I${AFS_INCLIB_DIR} \ 
06400  *      -I/usr/include 
06401  * 
06402  * system: install 
06403  * 
06404  * install: all 
06405  *      ${INSTALL} rxdemo_client ${PROJ_DIR}bin 
06406  *      ${INSTALL} rxdemo_server ${PROJ_DIR}bin 
06407  * 
06408  * all: rxdemo_client rxdemo_server 
06409  * 
06410  * rxdemo_client: rxdemo_client.o ${LIBS} rxdemo.cs.o ${CC} ${CFLAGS} 
06411  *      -o rxdemo_client rxdemo_client.o rxdemo.cs.o ${LIBS} 
06412  * 
06413  * rxdemo_server: rxdemo_server.o rxdemo.ss.o ${LIBS} ${CC} ${CFLAGS} 
06414  *      -o rxdemo_server rxdemo_server.o rxdemo.ss.o ${LIBS} 
06415  * 
06416  * rxdemo_client.o: rxdemo.h 
06417  * 
06418  * rxdemo_server.o: rxdemo.h 
06419  * 
06420  * rxdemo.cs.c rxdemo.ss.c rxdemo.er.c rxdemo.h: rxdemo.xg rxgen rxdemo.xg 
06421  * 
06422  * clean: rm -f *.o rxdemo.cs.c rxdemo.ss.c rxdemo.xdr.c rxdemo.h \ 
06423  *      rxdemo_client rxdemo_server core 
06424  * 
06425  * [End of file data] 
06426  * rxdemo complete. 
06427  * \endcode
06428  * 
06429  * \par
06430  * The rxdemo server program continues to run after handling these calls,
06431  * offering its services to any other callers. It can be killed by sending it
06432  * an interrupt signal using Control-C (or whatever mapping has been set up for
06433  * the shell's interrupt character). 
06434  * 
06435  *      \section Bibliography Bibliography 
06436  * 
06437  * \li [1] Transarc Corporation. AFS 3.0 System Administrator's Guide,
06438  * F-30-0-D102, Pittsburgh, PA, April 1990. 
06439  * \li [2] S.P. Miller, B.C. Neuman, J.I. Schiller, J.H. Saltzer. Kerberos
06440  * Authentication and Authorization System, Project Athena Technical Plan,
06441  * Section E.2.1, M.I.T., December 1987. 
06442  * \li [3] Bill         Bryant. Designing an Authentication System: a Dialogue
06443  * in Four Scenes, Project Athena internal document, M.I.T, draft of 8 February
06444  * 1988. 
06445  * \li [4] S. R. Kleinman.      Vnodes: An Architecture for Multiple file
06446  * System Types in Sun UNIX, Conference Proceedings, 1986 Summer Usenix
06447  * Technical Conference, pp. 238-247, El Toro, CA, 1986. 
06448  * 
06449  */

Generated on Fri Aug 31 2012 10:48:02 by  doxygen 1.7.1