home *** CD-ROM | disk | FTP | other *** search
/ Peanuts NeXT Software Archives / Peanuts-Update.iso / OpenStep / connectivity / mail / MailCompactor.2.s.README < prev    next >
Encoding:
Text File  |  1997-12-18  |  5.5 KB  |  141 lines
  1. Copyright (C), 1997, Paul S. McCarthy.
  2.  
  3. From: "Paul S. McCarthy" <zarnuk@mcgh.org>
  4. Date: December 15th, 1997
  5. Subject: MailCompactor.2.s.tar.gz
  6.  
  7. INTRODUCTION:
  8.     This program compacts NeXT mailboxes by physically removing
  9.     "deleted" messages.
  10.  
  11.     Tested with:
  12.         * NEXTSTEP 3.3
  13.         * OPENSTEP 4.1 (mach)
  14.         * OPENSTEP 4.2 (mach)
  15.  
  16.     This is the source code for the program.  It compiles and runs in
  17.     all three environments listed above.
  18.  
  19. HIGHLIGHTS:
  20.     * Avoids the compactmail+Mail.app bug-combo (see MOTIVATION).
  21.     * Does not update files "in-place".  Uses temporary files for
  22.       intermediate stages to minimize the possibility of leaving
  23.       mailboxes in a corrupted state.
  24.  
  25. MOTIVATION:
  26.     There are a pair of bugs in compactmail (from mailapp-utilities.2.0)
  27.     and NeXT's Mail.app (NEXTSTEP 3.3), which combine to corrupt the
  28.     table_of_contents files in users' mailboxes.  The symptoms from the
  29.     users' perspective are that Mail.app presents a panel saying:
  30.     "Open Mailbox", "Rebuilding table of contents..." and a progress
  31.     thermometer, when the users open a corrupted mailbox.
  32.  
  33.     The bugs are these:
  34.  
  35.     * compactmail updates the "mbox" and "table_of_contents" files
  36.       "in-place".  When it tries to truncate the length of the
  37.       "table_of_contents" file, it silently fails and leaves
  38.       excess garbage bytes at the end of the file.  (At least this
  39.       is what happens to us under NEXTSTEP 3.3).  This creates a
  40.       "partially corrupt" table_of_contents file that both the
  41.       compactmail and Mail.app programs will read without complaint.
  42.  
  43.     * Mail.app appends index entries for new mail messages to the
  44.       end of the "table_of_contents" file regardless of whether or
  45.       not that is actually the correct place to add those new entries.
  46.       If the table_of_contents file was "partially corrupt" before, and
  47.       Mail.app runs and receives new mail messages, it will append the
  48.       index entries for the new messages at the end of the file, after
  49.       the intervening garbage.  The file header will be updated to
  50.       indicate the new number of messages, but the file is now malformed.
  51.       This creates a "totally corrupt" table_of_contents file that all
  52.       programs, Mail.app, compactmail, listmail, etc. will reject.  As
  53.       long as Mail.app still has the mailbox open, it will use an
  54.       in-memory index which is not corrupt.  Mail.app will not detect
  55.       the corrupt table_of_contents file until after the mailbox has
  56.       been closed and is opened again, forcing Mail.app to read the
  57.       file from disk.
  58.  
  59. INSTALLATION:
  60.  
  61. cd ~/Source                # Wherever you compile programs.
  62. gnutar xzvf MailCompactor.2.s.tar.gz    # Creates MailCompactor/ directory.
  63. cd MailCompactor
  64. make                    # Creates MailCompactor program.
  65. cp MailCompactor /usr/local/bin        # Wherever you install programs.
  66.  
  67. USAGE:
  68.     This program is generally used by site system administrators to
  69.     compact users' mailboxes for them on a nightly basis.  This should
  70.     be set up as a cron job.  Here's the command that we use at mcgh:
  71.  
  72.     HOMES=/system2/Homes        # Location of user home directories.
  73.     COMPACTOR=/usr/local/bin/MailCompactor
  74.  
  75.     /usr/bin/find $HOMES -name '*.mbox' -type d -print \
  76.         -exec $COMPACTOR {} \; -prune
  77.  
  78.     NOTE: You can use the program to compact your own mailbox, but if
  79.     you want to use it to compact other users' mailboxes, then the
  80.     program will have to run from the "root" account.  This is not a
  81.     setuid program.
  82.  
  83. ACKNOWLEDGEMENTS:
  84.     Much credit is due to creators and maintainers of the
  85.     mailapp-utilities package:
  86.  
  87.         * Carl Edman wrote mailapp-utilities
  88.         * Tom Hageman is maintaining it (as of August, 1997)
  89.         * Chris Paris decoded the table_of_contents file.
  90.  
  91.     The structure of the table_of_contents file was gleaned from the
  92.     mailapp-utilities package.  The lock routine and the directory
  93.     removal routines are also adapted from routines in that package.
  94.  
  95. ARCHITECTURE:
  96.     This program inspects the original table_of_contents to determine
  97.     if there are any deleted messages.  If there are deleted messages
  98.     the program will copy all undeleted messages from the mailbox and
  99.     table_of_contents files into temporary files and record the names
  100.     of the NeXT mail attachments of all deleted messages.  If (and
  101.     only if) the entire mailbox is processed succesfully, then the
  102.     temporary files are renamed to replace the originals, and the
  103.     attachments from the deleted messages are removed.
  104.  
  105.     This architecture minimizes the opportunities for accidental
  106.     mailbox corruption.  The original mailbox is left untouched until
  107.     a completely finished and consistent new mailbox is ready.  The
  108.     only opportunity for a corrupt mailbox occurs in the space of time
  109.     between renaming the two files, and even in that case, the files
  110.     will be self-consistent, there will only be an inconsistency
  111.     between the mbox file and the table_of_contents file.
  112.  
  113. FREEWARE:
  114.     You may use this package for free.  You may make and distribute
  115.     copies of this package for free provided that: (a) the package is
  116.     not modified in any way, and (b) no fee of any kind is collected
  117.     for the distribution.
  118.  
  119. NO WARRANTY:
  120.     USE THIS PROGRAM AT YOUR OWN RISK.  This program is provided
  121.     "as-is".  There is no warranty.  There is no claim of
  122.     merchantability nor fitness for any particular purpose.  The
  123.     authors will not accept liablity for any damage or loss directly
  124.     or indirectly attributed to the use of this program.
  125.  
  126. FEEDBACK:
  127.     Comments to: "Paul S. McCarthy" <zarnuk@mcgh.org>
  128.  
  129.     Please include program version, operating system name, and
  130.     operating system version in all feedback.
  131.  
  132.  
  133. HISTORY:
  134.  
  135. v2 Mon Dec 15 20:20:21 EST 1997 zarnuk
  136.     * MailCompactor.cc -- fixed some minor OPENSTEP compiler warnings.
  137.     * Makefile -- made strip a separate step.
  138.  
  139. v1 Mon Dec 15 14:52:13 EST 1997 zarnuk
  140.  
  141.