CHK4MAIL(1)

NAME
chk4mail - list the number of mails in your mailfolders

SYNOPSIS
chk4mail [--acfhijlnqstux] [-d directory] [-e folder] [-m padding] [-r host] [-# padding] folder ...

DESCRIPTION
This manual page documents the chk4mail utility.

This program lists the number of read and unread emails in the folders in your maildirectory and your incoming mailfolder. The program assumes that the mailfolders reside in the subdir ~/Mail (or alternatively ~/mail). To determine the incoming folder, the value of the environment variable ${MAIL} is used.

However if you explicitly mention the mailfolders you want to see on the commandline, then only those files will be checked for new mail. You can specify the names as absolute filenames or use the =folder notation to indicate that the folder is located in your maildirectory. Instead of the equals sign (‘=’), a plus (‘+’) may be used as well.

The mailfolders are shown (and parsed) in alphabetical order, excluding any empty folders. The incoming folder is always shown last. Folder names that don't start with a lower case character will be ignored. When the number of emails cannot be determined (e.g. due to missing headers), a question mark is shown instead.

Although the mailfolders need to be read to obtain the necessary information, the original file access time will be preserved. Other programs such as mutt(1) and tcsh(1) use the access time to determine when new mail has arrived. Let's not upset these programs...

OPTIONS
-a  Display the number of messages which have been answered. Only works if your mailreader supports this X-Status extension.
-c  Also display folders when the name starts with a capital (the default is to ignore these folders).
-d directory
    Look for mailfolders in the specified directory instead of the default.
-e folder
    Exclude the specified mail folder. Note that the -e options may be given multiple times to exclude more mailfolders. Extra folder names explicitly specified as command line arguments will override any exclude options.
-f  Display the number of messages which have flagged as important. Only works if your mailreader supports this X-Status extension.
-h  Hide folders which contain only old mail (any folder with mail marked as new will be displayed).
-i  Only parse the standard incoming mail folder.
-j  Parse everything except the standard incoming mail folder.
-l  Always follow symbolic links. By default symbolic links are only followed when the filename is mentioned in $MAIL or as a command line argument, but not when encountered in your mailfolder directory.
-m number
    Set the maximum folder name length. This is usually detected automatically, but not when you use Maildirs with subfolders. Setting this may lead to a prettier layout formatting.
-n  Only show new folders, i.e. folders that actually received new mail since the last time you opened them. If you have quite some mailfolders (with old mail), this will be much faster than using the -h option.
-p  Use pthreads for parallel processing of multiple folders at once. This may speed up the process, but can actually be slower in some environments. This feature is still experimental: it produces incorrect results on some architectures.
-q  Suppress errors when a specified file is missing or can not be read. With this option, unreable files will be simply ignored.
-r hostname
    Execute this program on another machine, using rsh(1) to the remote host. If this option is specified, then all other command-line options will be ignored.
    If hostname equals the local hostname (without a domain), then this option will be ignored completely.
-s  Short output: only show files which haven't been opened since the last time that new mail had been received (this is fast). Implies the -n option.
-t  Change the timestamp of "old" mailfolders which do however contain new messages. This will make sure that other mail programs will also detect the new messages and that they will show up with -n in future runs as well. This option does not affect the timestamp of folders that were already detected as "new" (i.e. folders that do show up with -n already).
    Note that this option as absolutely no effect in combination with the -n flag: because that will skip the examination of these "old" folders.
-u  Treat unread messages as old instead of new email.
-w  Perform case sensitive parsing of mail headers. Although most applications generate headers in standard case-specific format, this is not a strict requirement. In general, mail message headers are case insensitive. Therefore, using this option may produce unexpected results, but it will speed up parsing of messages.
-x  Show folders with leading dots in the name as well. In Unix using a dot as first character usually means that the file is hidden in normal directory listings.
-# number
    Pad the last output field (total messages) to number spaces. The default is 4.

The behaviour of this program can be further tweaked using environment variables: see ENVIRONMENT below.

ARGUMENTS
A single optional argument is accepted: this should be the filename of the folder you want to parse. If an argument is given, only this folder is checked and your default folders will be ignored.

SUPPORTED FORMATS
chk4mail recognizes five different mailbox formats: mbox, MMDF, MH, Maildir and Extended Maildir. The mailbox type is autodetected, so there is no need to use a flag for different mailbox types.

mbox
    This mailbox format is most common. The mailfolder consists of a single file containing all messages. Each message starts with a line of the form:
    Unfortunately these ‘From ’ lines are not always quoted properly in the message body. That is why chk4mail takes the ‘Content-Length’ header into account, where-ever possible.

MMDF
    This is a variant of the mbox format. It has a clearer way of seperating messages: Each message is surrounded by lines containing ‘^A^A^A^A’.

MH  A mailfolder consists of a directory and each message is stored in a separate file. The filename indicates the message number. Deleted files are renamed by prepending a comma to the filename. Whether a file is unread should be indicated in the .mh_sequences file. However as neither procmail(1) nor mutt(1) update this, there is no point in checking it. So the number of new messages in these folder is always unknown, and a question mark is shown instead.

Maildir
    A newer mailfolder format, which is (can be) used by qmail(1) and procmail(1). Like MH directories are used for the mailfolders, however it adds three subdirectories for the mailfolder: tmp, new and cur. As filenames for the messages, the message-id of the mail is used, so it should always be unique, and file locking is not needed.

Extended Maildir
    A format used by Courier MTA, but not recognized by qmail or procmail. This is an extension of the Maildir format whereby each maildir may contain one or more subfolders (all subfolders also contain tmp, new, cur directories). These subfolders do not have subsubfolders, but a dot seperator can be used to indicate a hierarchy: so .Sent.2004 and .Sent.2005 indicate two parts of the Sent subfolder.

Remember that procmail(1) can use only three of these mailbox formats: mbox (‘folder’), MH (‘folder/.’) and Maildir (‘folder/’). However mutt(1) supports all five formats.

NOTES
Empty files, filenames not starting with a lowercase character, symbolic links and special devices will be ignored. However files containing dots as well as subdirectories are treated as mailfolders. If you don't like this, then you shouldn't put these in your maildirectory!

There is no fall-back for an incoming folder. When the ${MAIL} variable is not set, we simply assume all the folders are in the maildirectory. When you don't have a maildirectory either, there is little point in using this utility. This may be a bit confusing because mail readers like mutt(1) and elm(1) usually do have a fall-back default, which is determined at compile-time. This is usually something like /var/mail/${USER}.

The ${MAILPATH} environment variable will be ignored if it is set. This is not a bug. Having to list 50 full pathnames in a variable just to get your mail program to function is rediculous.

To be somewhat compatible with frm(1) and nfrm(1) chk4mail will behave completely different when it is run as frm or nfrm: in this case it will display a list with the senders and subjects of the (new) messages in your standard inbox. The output may not be completely compatible and the command line options of frm(1) are not supported.

ENVIRONMENT
HOME
    Full path of the user's home directory. This is used to determine the directory where the user's mailfolders reside. By default the subdirectory Mail is used; if this does not exist then the directory mail is used instead.
MAIL
    Full path of the user's default incoming mailfolder.
MAIL_UNREAD_AS_OLD
    On popular demand, setting this variable will do the same as the -u command line option.
CHK4MAIL_OPTIONS
    This variable allows you to set default options for chk4mail. You should use options the same way as you would do on the command line.

SEE ALSO
chkimap(1)

AUTHOR
Johan van Selst <johans@stack.nl>

BUGS
By default this program does not make any distinction between new and unread messages. This is a feature, not a bug. See the -u option.

In the unlikely event that the program doesn't behave the way it is supposed to, you can always contact the author.