Copyright (C), 1997, Paul S. McCarthy.

From: "Paul S. McCarthy" <zarnuk@mcgh.org>
Date: December 15th, 1997
Subject: MailCompactor.2.s.tar.gz

INTRODUCTION:
	This program compacts NeXT mailboxes by physically removing
	"deleted" messages.

	Tested with:
		* NEXTSTEP 3.3
		* OPENSTEP 4.1 (mach)
		* OPENSTEP 4.2 (mach)

	This is the source code for the program.  It compiles and runs in
	all three environments listed above.

HIGHLIGHTS:
	* Avoids the compactmail+Mail.app bug-combo (see MOTIVATION).
	* Does not update files "in-place".  Uses temporary files for
	  intermediate stages to minimize the possibility of leaving
	  mailboxes in a corrupted state.

MOTIVATION:
	There are a pair of bugs in compactmail (from mailapp-utilities.2.0)
	and NeXT's Mail.app (NEXTSTEP 3.3), which combine to corrupt the
	table_of_contents files in users' mailboxes.  The symptoms from the
	users' perspective are that Mail.app presents a panel saying:
	"Open Mailbox", "Rebuilding table of contents..." and a progress
	thermometer, when the users open a corrupted mailbox.

	The bugs are these:

	* compactmail updates the "mbox" and "table_of_contents" files
	  "in-place".  When it tries to truncate the length of the
	  "table_of_contents" file, it silently fails and leaves
	  excess garbage bytes at the end of the file.  (At least this
	  is what happens to us under NEXTSTEP 3.3).  This creates a
	  "partially corrupt" table_of_contents file that both the
	  compactmail and Mail.app programs will read without complaint.

	* Mail.app appends index entries for new mail messages to the
	  end of the "table_of_contents" file regardless of whether or
	  not that is actually the correct place to add those new entries.
	  If the table_of_contents file was "partially corrupt" before, and
	  Mail.app runs and receives new mail messages, it will append the
	  index entries for the new messages at the end of the file, after
	  the intervening garbage.  The file header will be updated to
	  indicate the new number of messages, but the file is now malformed.
	  This creates a "totally corrupt" table_of_contents file that all
	  programs, Mail.app, compactmail, listmail, etc. will reject.  As
	  long as Mail.app still has the mailbox open, it will use an
	  in-memory index which is not corrupt.  Mail.app will not detect
	  the corrupt table_of_contents file until after the mailbox has
	  been closed and is opened again, forcing Mail.app to read the
	  file from disk.

INSTALLATION:

cd ~/Source				# Wherever you compile programs.
gnutar xzvf MailCompactor.2.s.tar.gz	# Creates MailCompactor/ directory.
cd MailCompactor
make					# Creates MailCompactor program.
cp MailCompactor /usr/local/bin		# Wherever you install programs.

USAGE:
	This program is generally used by site system administrators to
	compact users' mailboxes for them on a nightly basis.  This should
	be set up as a cron job.  Here's the command that we use at mcgh:

	HOMES=/system2/Homes		# Location of user home directories.
	COMPACTOR=/usr/local/bin/MailCompactor

	/usr/bin/find $HOMES -name '*.mbox' -type d -print \
		-exec $COMPACTOR {} \; -prune

	NOTE: You can use the program to compact your own mailbox, but if
	you want to use it to compact other users' mailboxes, then the
	program will have to run from the "root" account.  This is not a
	setuid program.

ACKNOWLEDGEMENTS:
	Much credit is due to creators and maintainers of the
	mailapp-utilities package:

		* Carl Edman wrote mailapp-utilities
		* Tom Hageman is maintaining it (as of August, 1997)
		* Chris Paris decoded the table_of_contents file.

	The structure of the table_of_contents file was gleaned from the
	mailapp-utilities package.  The lock routine and the directory
	removal routines are also adapted from routines in that package.

ARCHITECTURE:
	This program inspects the original table_of_contents to determine
	if there are any deleted messages.  If there are deleted messages
	the program will copy all undeleted messages from the mailbox and
	table_of_contents files into temporary files and record the names
	of the NeXT mail attachments of all deleted messages.  If (and
	only if) the entire mailbox is processed succesfully, then the
	temporary files are renamed to replace the originals, and the
	attachments from the deleted messages are removed.

	This architecture minimizes the opportunities for accidental
	mailbox corruption.  The original mailbox is left untouched until
	a completely finished and consistent new mailbox is ready.  The
	only opportunity for a corrupt mailbox occurs in the space of time
	between renaming the two files, and even in that case, the files
	will be self-consistent, there will only be an inconsistency
	between the mbox file and the table_of_contents file.

FREEWARE:
	You may use this package for free.  You may make and distribute
	copies of this package for free provided that: (a) the package is
	not modified in any way, and (b) no fee of any kind is collected
	for the distribution.

NO WARRANTY:
	USE THIS PROGRAM AT YOUR OWN RISK.  This program is provided
	"as-is".  There is no warranty.  There is no claim of
	merchantability nor fitness for any particular purpose.  The
	authors will not accept liablity for any damage or loss directly
	or indirectly attributed to the use of this program.

FEEDBACK:
	Comments to: "Paul S. McCarthy" <zarnuk@mcgh.org>

	Please include program version, operating system name, and
	operating system version in all feedback.


HISTORY:

v2 Mon Dec 15 20:20:21 EST 1997 zarnuk
	* MailCompactor.cc -- fixed some minor OPENSTEP compiler warnings.
	* Makefile -- made strip a separate step.

v1 Mon Dec 15 14:52:13 EST 1997 zarnuk

