Documentation for qmail-unread v0.9.0 by Simon Bond (bondsc@tcp.co.uk)

Introduction
------------

qmail-unread displays a summary of all unread mail (ie waiting in a user's mailbox or Maildir/) for all Qmail users on the system. It reads each users' .qmail file (if it exists) to determine the type and location of the incoming mail, performs various sanity checks and then displays the information in a table.

There are no command line arguments, just run it.



Example output
--------------

Below is sample output from qmail-unread, with a few example error messages to give you a basic idea:


Username       Mail location                 Format         Mail waiting
------------------------------------------------------------------------
simon          /home/simon/Maildir/          Maildir        1
stud1          /home/stud1/Maildir/          Maildir        Wrong permissions on home direcory
stud2          /home/stud2/Maildir/          Maildir        Maildir/ directory is missing
stud3          /home/stud3/Maildir/          Maildir        0
stud4          /home/stud4/Maildir2/         Maildir        1
stud5          /home/stud5/Maildir/          Maildir        0
root           /home/root/Maildir/           Maildir        0
postmaster     /var/qmail/alias/Mailbox      Mailbox        4
mailer-daemon  /var/qmail/alias/Mailbox      Mailbox        4



Installation
------------

To extract the archive:
tar -xzvf qmail-unread-0.9.0.tar.gz
cd qmail-unread-0.9.0

To compile the source (and replace the binary provided), simply type
make qmail-unread	(there is no Makefile, program is simple enough not to need it)

To use the binary, simply copy it to the qmail bin directory:
cp qmail-unread /var/qmail/bin



Platform
--------

The source should work on any system. Personally I've only tested it on my Slack/Debian/Hat systems on the Intel platform with kernel 2.0.3x, GCC 2.7.2.x, libc 5.4.xx. However, there is nothing wierd in the source code and I don't go to the kernel for anything.

The binary provided is (surprise, surprise) kernel 2.0.3x, GCC 2.7.2.x, libc 5.4.xx.



How it works
------------

If you really want to know how this program works, read the source. However, the notes below should give you a basic idea:

The program scans through each user specified in /etc/passwd (using the getpwent() system call).

For each user, the program tests if the home directory exists and if it has the correct ownership (since Qmail won't deliver mail if g+w or o+w is present).

For each user, the program then looks for a ~/.qmail file. If it doesn't find this file, it assumes that the mail is stored in the Mailbox file format in the file ~/Mailbox. If neither the ~/.qmail and ~/Mailbox files are found, the program assumes that you are not a Qmail user. (A handy way of jumping the bin, lp, etc users).

If the ~/.qmail file exists, the program reads it to determine whether you are using a Mailbox file format or Maildir/ directory format for your mail and where it is located. It can handle various types of entry. For example:

/home/bob/Mailbox	Specifying absolute path of Mailbox file
./Mailbox		Specifying relative path of Mailbox file
/home/bob/Maildir/	Specifying absolute path of Maildir directory
./Maildir/		Specifyinh relative path of Maildir directory

so I think it can catch all eventualities. All other lines in the ~/.qmail file (anything not beginning with a '.' or '/') are ignored. If the ~/.qmail file doesn't specify where the mail is stored, it is assumed to be in ~/Mailbox.

The program then performs various sanity checks:
For Mailbox type files:
  Does it exist?
  Is is a directory!!
For Maildir/ structures:
  Does it exist?
  Do the cur/, new/ and tmp/ sub folders exist?

The program then works out how many mails this user has:

For Mailbox type files, it counts the number of lines which begin with the text "To:". Now, I know this is a bit dodgy, because if any messages have the text "To:" in their body (at the start of the line), my program will count them as well. I basically couldn't be arsed to find a better way because I don't use Mailbox files myself, and the worse that can happen is that my program will report that a user has more mails than they really have (I think a very rare event).

For Maildir/ directory structures, it counts the number of files in ~/Maildir/new/ (or wherever the ~/.qmail file said it was).



Comments or bug reports
-----------------------

Any comments or bug reports are welcome. Just mail be at bondsc@tcp.co.uk

Of course, if you simply mail me saying "it doesn't work" or "Your program sucks", then I'll just ignore you (In the case of the latter comment, i'll probably send the lads round with the shooters in the boot :) ).

However, if you give me a lot of details (exact screen output and how it differs from what mail really was waiting) then I'll fix it.



Disclaimer
----------

There is absolutely no guarantee that the program will work and not wipe out your computer.

You can do what you like with the source code or binary. You can even claim it is your own, I simply don't care. I only wrote the program to simplify my admin job and thought that I'd make it available to anyone else.

If the program does any damage whatsoever (e.g. blows up your computer, turns it into a 386, and attracts all the bugs in a 100 mile radius), then hard shit. Nothing to do with me guv.

If there is a virus in the binary, hard luck. Not my problem.

Basically, if you download / run the program, you're on your own.

