Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
asmail(1)		    General Commands Manual		     asmail(1)

       asmail -	the AfterStep e-mail monitor

       asmail [-h] [-V]	[-v] [-nox]
	       [-f resource file]
	       [-geometry X geometry specification]

       The  asmail  is	a X11 application that acts as an e-mail monitor for a
       number of various format	mailboxes.  The	asmail provides	a  distinctive
       Afterstep window	manager	look and feel and features multiple options to
       allow the customization.

       Basically, the tool shows you the following:

       - The background	image changes depending	on whether
	 there is e-mail in your mailboxes or not.
	 Custom	images may be loaded and used for animation

       - The tool will display the number of e-mails waiting
	 in each mailbox and/or	the total numbers for all
	 mailboxes together.

       - For each mailbox, there is a status indicator that
	 shows whether the update is running at	this moment
	 and indicates if there	is an error. The same indicator
	 shows up next to the summary line.

       The folowing indicators are used	for the	status display:

	 R  An update on the mailbox is	running	at this	moment.
	    For	small mailboxes	with fast access, you may never
	    actually see it - so fast it disappears.

	 L  An error occured that has to do with the login
	    procedure. Most probably, your name/password
	    combination	was not	accepted by the	server.

	 C  A connection problem. asmail could not
	    connect to the server for some reason. The reasons
	    may	be many	- server down, network unreachable,
	    service not	available and so on.

	 T  A time-out has occured while asmail	was
	    waiting for	the server's answer. If	you have a
	    frequent problem with this but the server seems
	    to be available in other applicaitons, try
	    increasing the "timeout" setting for the mailbox.

	 F  This is an indicator of a general error condition.
	    Something is wrong,	maybe the configuration	is not
	    correct, or	the mailbox is not readable. Check the
	    output of asmail by	running	from the terminal -
	    this should	give you an idea of what is wrong.

       The resource files may be specified with	a  command  line  option.  The
       logic  of  asmail is simple: first it parses the	resource file that you
       specified on the	command	line.  If you do not specify the resource file
       on  the	command	line, asmail will look in the default location (~/.as-
       mailrc).	 If it exists, asmail will parse that one. If no configuration
       file  was  given	on the command line and	there is no configuration file
       in the default location,	asmail will attempt  to	 monitor  the  mailbox
       specified by the	$MAILBOX environment variable.

       How asmail distinguishes	between	old and	new mail.

       The UNIX	mailbox	format does not	contain	any indication on the outside.
       The mailbox must	be parsed to check if some e-mail is new. Parsing  the
       mailbox	is an expensive	operation, especially if the mailbox is	large.
       asmail checks the mailbox file modification time	with the stat(2)  sys-
       tem  call.  When	 the  file  modification  time changes,	the mailbox is
       parsed. The lines "From " are counted and taken to be the number	of  e-
       mails  in  the box. After each "From " line, asmail looks for the "Sta-
       tus:" header. This header contains flags	when the message was seen  and
       read.  Messages	without	this header line (or with an empty header) are
       considered to be	new.

       The Maildir format is very well-behaved.	There are separate folders for
       old  and	 new e-mails so	we just	count the number of files in "cur" and
       "new" subdirectories.  The "tmp"	subdirectory is	ignored	since this  is
       the temporary storage and is not	supposed to be taken into account.

       The  mH	format	is somewhere between Maildir and the UNIX mailbox for-
       mats. It	is used	by mh, nmh, balsa and xfmail among  others.  The  mes-
       sages  are  all stored in separate files, one message per file, and all
       of the messages in a single directory. Each message file	is named  with
       an  increasing  number, so the first message recieved in	the mailbox is
       stored as "1" and the 39th message is stored as "39".   There  are  two
       ways  that the status of	the messages are kept track of.	Traditionally,
       the mH tools used a file	called ".mh_sequences",	which is stored	in the
       mH  directory,  to keep track of	status.	This file contains a series of
       sequences, each one starting with a token followed by a colon and  then
       by  a  series of	message	numebrs, representing the messages that	belong
       to that sequence. It looks something like this:
	      unseen: 1	2 3-5 19 25-31
       Although	there are many sequences, some standard	and some user-defined,
       if  the	use-mh-sequences configuration option is set to	"yes" for that
       mailbox,	then asmail will parse this file, looking for the "unseen" se-
       quence to determine how many messages are new.  Some mail clients don't
       use the .mh_sequences file and instead treat the	files in the mH	 mail-
       box  just  like	a collection of	seperate messages from a UNIX mailbox.
       So, if the use-mh-sequences configuration option	is set to "no",	or  is
       not specified at	all, then asmail will parse all	of the files in	the mH
       directory, searching for	the Status header.  Therefore,	this  mode  is
       definitely the most "processor hungry" format from the point of view of
       asmail.	mh, nmh, and newer versions of balsa utilize the .mh_sequences
       file, while older versions of balsa and xfmail do not.  It is not known
       how other clients treat mH mailboxes.

       The POP3	protocol does not support the notion of	 new  or  old  e-mail.
       Your  e-mail  client  keeps a list of messages and can tell whether you
       read one	of them	or not.	Since asmail does not keep a list of  messages
       there  is no way	to tell	a new message from the old one.	Ok, so what we
       do is assume that all e-mail is new at start-up.	This is	a logical  as-
       sumption	 for  most of the people because they store the	e-mail locally
       and remove it from the server.  Others are out of luck. Now,  when  the
       number  of  messages decreases, we assume that you read all your	e-mail
       and deleted some, so all	messages are marked as old. When the number of
       messages	 increases,  we	assume that the	new mail arrived and we	report
       the additional mail as new.

       The IMAP	protocol is very well behaved, it reports the number of	new e-
       mails  and  the	number	of old e-mails if you ask politely :) Since we
       open the	mailbox	in read-only mode, we do not cause any status  changes
       for  the	mailbox	on the server. The IMAP	server will store a special e-
       mail into your mailbox if it is in UNIX format. This e-mail allows  the
       server  to  keep	 track of the new and old e-mails. The server will not
       report this e-mail into the number of e-mails, so  that	if  you	 check
       your UNIX mailbox directly the number of	messages will be one more.

	      prints a short description and usage message.

	      Version control. Prints out the version of the program.

	      Verbose  mode.  In  this mode, asmail will print the information
	      about mailboxes onto the controlling terminal.  The  information
	      includes:	 number	of updates requested, per mailbox: thread PID,
	      [R]unning	or idle, any errors are	 signalled  with  leters  (see
	      above)  and  the	number	of e-mails in the format new/old. This
	      mode is useful for debugging or could be used to	monitor	 mail-
	      boxes without X Windows interface	(give the -nox option).

       -f resource file
	      Specifies	 the  alternative location for the resource file.  The
	      default location is ~/.asmailrc If the alternative file is spec-
	      ified, the default location is ignored.

       -geometry X geometry specification
	      Specifies	the size and position of the application on the	screen
	      in the standard X11 format  (see	XParseGeometry	(3x)  for  de-


	      Forces  asmail  to  ignore  the  resource	 file  even  if	one is
	      present. asmail will run with all	default	settings and check the
	      Unix mailbox specified by	the $MAIL environment variable.

	      Starts  the  asmail application in the terminal-only mode. The X
	      Windows interface	is not	started.  The  configuration  file  is
	      still parsed as usual though.

	      This option implies -v option.

	      Usually,	asmail	will  check that the resource file has the 600
	      mode, that is there are no access	rights for "group"  and	 "oth-
	      ers".  If	 such  access rights are granted, asmail will complain
	      and exit.	This is	done to	make you remember  the	passwords  you
	      put into the resource file.  If there are	no passwords stored in
	      the file (e.g. you are using UNIX	mailbox	on the local  machine)
	      the check	is not applied.

	      This  option forces asmail to continue operation even if the re-
	      source file has insecure permissions and passwords are stored in
	      that file.

	      This option will cause asmail to start up	as an icon rather than
	      as a normal window. The application can still be de-iconized and
	      iconized as usual.

	      This  option will	cause asmail to	start up in a so-called	"with-
	      drawn" mode. This	mode is	used by	WindowMaker window manager  to
	      dock the application into	their version of the Wharf.

       The syntax of the resource file is described in a separate man page un-
       der asmailrc (5).

       asmail can be called in different ways.	The most common	invocation  is
       the command line:

	    user@host[1]% asmail &

       Another way to call asmail is from the window manager:

	    *Wharf "asmail" nil	Swallow	"asmail" /usr/local/bin/asmail &

       This line, when placed in the wharf file	in the users Afterstep config-
       uration directory will cause asmail to become a button on the Wharf (1)
       button bar under	the afterstep (1) window manager.

       My programs do not have bugs, they just develop random features ;-)

       Well,  there are	limitations. All the strings for the color names, file
       names, and other	strings	have the length	limit of 256 characters	 (ter-
       minating	 zero  included).   The	 program will complain about very long
       names in	the configuration file.

       The number of mailboxes is not limited by the space on the icon but the
       stats  will be chopped (not shown) if you have too many and they	do not
       fit into	the icon.  Make	sure you pick up a tall	icon if	you have  many
       mailboxes  and  want to see info	on each	of them	because	they are shown
       from the	top down and there is no way to	change this.

       The information about mailboxes will not	appear when you	 use  "shaped"
       windows with transparency if it is printed in the transparent area.

       asmail  may  interfere  with  your mail client program when you use the
       POP3 server. There is no	way to login to	the POP3  server  twice	 (from
       the mail	client and asmail), so there is	an inherent race condition be-
       tween the two.  The one that tries to log in second, will fail.	asmail
       logs  out  immediately  after  checking so your mail client will	have a
       much higher chance of precluding	asmail from logging in than the	 other
       way around.

       If  the	program	 is not	satisfied with the specification of one	of the
       mailboxes, it will print	an error message,  set	the  status  for  that
       mailbox	to F (Failed) and exit the thread (only	the thread that	is re-
       sponsible for handling that particular mailbox).	Other  mailboxes  will
       be checked normally.  Check the standard	output of the tool to see what
       the problem is.


       asmailrc(5) afterstep(1)

       Copyright (c) 2002-2007	Albert Dorofeev	<>

       Distributed under GNU General Public License v2 ; see LICENSE file  for
       more informations.

       Albert "Tigr" Dorofeev <>

       See the README file for credits.

3rd Berkeley Distribution	  09 Apr 2007			     asmail(1)


Want to link to this manual page? Use this URL:

home | help