home *** CD-ROM | disk | FTP | other *** search
/ rtsi.com / 2014.01.www.rtsi.com.tar / www.rtsi.com / OS9 / OSK / EFFO / forum16.lzh / SOFTWARE / ASSEMBLER / EXIT_HANDLER / uacct.doc < prev   
Text File  |  1991-01-09  |  6KB  |  174 lines
  1. ********** UPDATE FOR SECOND RELEASE - DOUG KEMP 1990-Nov-06 *****************
  2.  
  3. UACCT (Exit handler) module as installed by the system at boot:
  4. It must be included in the Extens module list in systype.d.
  5.  
  6. In order to install it after the boot the TypLang must be changed
  7. to 'Prgrm' (instead of 'System') and the rts line must be replaced by
  8. an 'OS9 F$Exit': then you can load it in memory and execute it.
  9. **************  END OF UPDATE FOR SECOND RELEASE *****************************
  10.  
  11.  
  12.                   OS-9 PROGRAMMABLE PROCESS EXIT HANDLER
  13.                   -------------------------------------
  14.  
  15.                                                     P. Mato
  16.                                                     A. Miotto
  17.  
  18.  
  19. INTRODUCTION
  20. ------------
  21.   Many software packages need to do some internal clean-up when the Process
  22. terminates. In normal situations a package user terminates his program with
  23. a call to a routine of the package implemented for that purpose. The problem
  24. arises when the user is a "bad user" and doesn't call the termination routine
  25. or his program has a crash and ends abnormally. Because these situations can
  26. occur the package writer has to provide a method to cope with them. There are
  27. several solutions:
  28.  - Using a dummy device driver. OS-9 takes care of closing all the open paths
  29.    before the user process ends. In that way the package is informed that
  30.    user program has exited.
  31.  - Doing a consistency check time to time or in certain conditions. The package
  32.    can keep a list of active users and their fork time. The fork time in the
  33.    list and in the process descriptor must be equal, otherwise something is
  34.    wrong. This technique works but the cpu time consumed can be large if the
  35.    check is done often.
  36.  - Implementing an Exit Handler. What writers want is a way of indicating to
  37.    the operating system that a certain routine must be called when the process
  38.    exits. Because a user process may use more than one package there must be
  39.    the possibility of declaring more than one routine to be executed on
  40.    exit. This utility does not exist in OS-9.
  41.  
  42.   This note explains how an OS-9 exit Handler has been implemented and how
  43. the package writers may make use of it.
  44.  
  45.  
  46. IMPLEMENTATION
  47. --------------
  48.   The OS-9  system call F$UAcct is foreseen for implementing User Accounting.
  49. This system service is called each time a process is forked and exited. By
  50. default this system call is a dummy routine. This is called each time a process
  51. exits, so we can use it as a hook for our exit handler. Moreover in the process
  52. descriptor there is some space reserved to be used by the User Accounting
  53. module. Two longwords of this reserved space can be used to store pointers
  54. to a double linked list containing the entry point and other parameters for
  55. each declared routine. Programs that do not use any of the packages using the
  56. Exit handler facility will have these pointers to zero and no routine will be
  57. executed.
  58.   Two more system services have been implemented to link and unlink elements
  59. to the exit handler list. These have the names F$ExhLnk and F$ExhUlk and are
  60. described as follows:
  61.     F$ExhLnk  equ  I$Last
  62.     F$ExhUlk  equ  I$Last+1
  63.  
  64. F$ExhLnk                        Link routine to the Exit Handler list
  65.  
  66. Assembler call: os9 F$ExhLnk
  67.  
  68. Input:          (a1) = 6 longword structure pointer
  69.                 offset 0: reserved for the pointer to the next entry
  70.                        4: reserved for the pointer to the previous entry
  71.                        8: entry point to the exit routine
  72.                       12: a6 to be passed to the exit routine
  73.                       16: d0 to be passed to the exit routine (optional)
  74.                       20: d1 to be passed to the exit routine (optional)
  75. Output:         none
  76.  
  77. Error:          cc   = carry bit set
  78.                 d1.w = error code if error
  79.  
  80. F$ExhUlk                        Unlink routine from the Exit Handler list
  81.  
  82. Assembler call: os9 F$ExhUlk
  83.  
  84. Input:          (a1) = 6 longword structure pointer
  85.  
  86. Output:         none
  87.  
  88. Error:          cc   = carry bit set
  89.                 d1.w = error code if error
  90.  
  91. CAVEATS
  92. -------
  93.   The exit routine is executed in supervisor mode. The user has to be careful
  94. to link to exit routines sensibly. There is no check in F$ExhLnk if the
  95. the entry point supplied has real meaning. The system service F$ExhUlk
  96. checks before doing the unlink if really the list element was linked. Otherwise
  97. returns an error.
  98.   The module "uacct" must be resident in memory all the time. Unpredictable
  99. errors (often a crash) can happen if is unlinked.
  100.  
  101.  
  102. INSTALLATION
  103. ____________
  104.   In order to install these new system services the following commands need
  105. to be executed at startup.
  106.  
  107.     $ load <path>/uacct    ! this contains the system services
  108.     $ <path>/install uacct ! This command is needed to install the new service
  109.  
  110.  
  111. EXAMPLE
  112. -------
  113.   This is an example of how can be use the exit handler in a routine package.
  114. Let's take the ALEPH OS-9 Buffer Manager as example.
  115.  
  116.  
  117. extern int bm_uclean();
  118. bm_include( .... )
  119. {
  120.    . . .   /* many other things */
  121.  
  122.    icode = bm_exh_link(bm_uclean,user_id);
  123.    if(icode == -1)
  124.    {
  125.       bm_uclean(user_id);
  126.       return(errno);
  127.    }
  128.    return(0);
  129. }
  130. bm_exclude()
  131. {
  132.    . . . /* other things */
  133.  
  134.    icode = bm_exh_unlink();
  135.    if (icode == -1) return(errno);
  136.    bm_uclean(user_id);
  137. }
  138.  
  139.  
  140. -------- assembler code ---------
  141.  
  142. F$ExhLnk  equ  I$Last
  143. F$ExhUlk  equ  I$Last+1
  144.     vsect
  145. next    dc.l    0
  146. prev    dc.l    0
  147. r_pc    dc.l    0
  148. r_a6    dc.l    0
  149. r_d0    dc.l    0
  150.         ends
  151. bm_exh_link:    equ     *     bm_exh_link(routine,arg1);
  152.         move.l  a1,-(a7)
  153.         move.l  d0,r_pc(a6)
  154.         move.l  a6,r_a6(a6)
  155.         move.l  d1,r_d0(a6)
  156.         lea.l   next(a6),a1
  157.         os9     F$ExhLnk
  158.         bcc     Exh_ok
  159.         move.l  #-1,d0
  160.         move.l  d1,errno(a6)
  161. Exh_ok  move.l  (a7)+,a1
  162.         rts
  163. bm_exh_unlink:  equ     *     bm_exh_unlink();
  164.         move.l  a1,-(a7)
  165.         moveq.l #0,d0
  166.         lea.l   next(a6),a1
  167.     os9     F$ExhUlk
  168.         bcc     Exhu_ok
  169.         move.l  #-1,d0
  170.         move.l  d1,errno(a6)
  171. Exhu_ok move.l  (a7)+,a1
  172.         rts
  173.  
  174.