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

FreeBSD Manual Pages

  
 
  

home | help
Mail::Box::MH(3)      User Contributed Perl Documentation     Mail::Box::MH(3)

NAME
       Mail::Box::MH - handle MH folders

INHERITANCE
	Mail::Box::MH
	  is a Mail::Box::Dir
	  is a Mail::Box
	  is a Mail::Reporter

SYNOPSIS
	use Mail::Box::MH;
	my $folder = new Mail::Box::MH folder => $ENV{MAIL}, ...;

DESCRIPTION
       This documentation describes how	MH mailboxes work, and what you	can do
       with the	MH folder object "Mail::Box::MH".

       See documentation in the	base class.

OVERLOADED
       See documentation in the	base class.

       overload: ""()
	   See "OVERLOADED" in Mail::Box

       overload: @{}()
	   See "OVERLOADED" in Mail::Box

       overload: cmp()
	   See "OVERLOADED" in Mail::Box

METHODS
       See documentation in the	base class.

   Constructors
       See documentation in the	base class.

       Mail::Box::MH->new(OPTIONS)
	    -Option	      --Defined	in     --Default
	     access		Mail::Box	 'r'
	     body_delayed_type	Mail::Box	 Mail::Message::Body::Delayed
	     body_type		Mail::Box	 Mail::Message::Body::Lines
	     coerce_options	Mail::Box	 []
	     create		Mail::Box	 <false>
	     directory		Mail::Box::Dir	 <derived from folder name>
	     extract		Mail::Box	 10240
	     field_type		Mail::Box	 undef
	     fix_headers	Mail::Box	 <false>
	     folder		Mail::Box	 $ENV{MAIL}
	     folderdir		Mail::Box	 $ENV{HOME}/.mh
	     head_delayed_type	Mail::Box	 Mail::Message::Head::Delayed
	     head_type		Mail::Box	 Mail::Message::Head::Complete
	     index				 undef
	     index_filename			 <foldername>/.index
	     index_type				 Mail::Box::MH::Index
	     keep_dups		Mail::Box	 <false>
	     keep_index				 0
	     labels				 undef
	     labels_filename			 <foldername>/.mh_sequence
	     labels_type			 Mail::Box::MH::Labels
	     lock_file		Mail::Box	 <index_file>
	     lock_timeout	Mail::Box	 1 hour
	     lock_type		Mail::Box	 Mail::Box::Locker::DotLock
	     lock_wait		Mail::Box	 10 seconds
	     locker		Mail::Box	 undef
	     log		Mail::Reporter	 'WARNINGS'
	     manager		Mail::Box	 undef
	     message_type	Mail::Box	 <folder-class>::Message
	     multipart_type	Mail::Box	 Mail::Message::Body::Multipart
	     remove_when_empty	Mail::Box	 <true>
	     save_on_exit	Mail::Box	 <true>
	     trace		Mail::Reporter	 'WARNINGS'
	     trusted		Mail::Box	 <depends on folder location>

	   access => MODE
	   body_delayed_type =>	CLASS
	   body_type =>	CLASS|CODE
	   coerce_options => ARRAY
	   create => BOOLEAN
	   directory =>	DIRECTORY
	   extract => INTEGER |	CODE | METHOD |	'LAZY'|'ALWAYS'
	   field_type => CLASS
	   fix_headers => BOOLEAN
	   folder => FOLDERNAME
	   folderdir =>	DIRECTORY
	   head_delayed_type =>	CLASS
	   head_type =>	CLASS
	   index => OBJECT
	     You may specify an	OBJECT of a type which extends
	     Mail::Box::MH::Index (at least implements a "get()" method), as
	     alternative for an	index file reader as created by
	     "Mail::Box::MH".

	   index_filename => FILENAME
	     The FILENAME which	is used	in each	directory to store the headers
	     of	all mails. The filename	shall not contain a directory path.
	     (e.g. Do not use "/usr/people/jan/.index",	nor "subdir/.index",
	     but say ".index".)

	   index_type => CLASS
	   keep_dups =>	BOOLEAN
	   keep_index => BOOLEAN
	     Keep an index file	of the specified mailbox, one file per
	     directory.	 Using an index	file will speed	up things
	     considerably, because it avoids reading all the message files the
	     moment that you open the folder.  When you	open a folder, you can
	     use the index file	to retrieve information	such as	the subject of
	     each message, instead of having to	read possibly thousands	of
	     messages.

	   labels => OBJECT
	     You may specify an	OBJECT of a type which extends
	     Mail::Box::MH::Labels (at least implements	the "get()" method),
	     as	alternative for	labels file reader as created by
	     "Mail::Box::MH".

	   labels_filename => FILENAME
	     In	MH-folders, messages can be labeled, for instance based	on the
	     sender or whether it is read or not.  This	status is kept in a
	     file which	is usually called ".mh_sequences", but that name can
	     be	overruled with this flag.

	   labels_type => CLASS
	   lock_file =>	FILENAME
	   lock_timeout	=> SECONDS
	   lock_type =>	CLASS|STRING|ARRAY
	   lock_wait =>	SECONDS
	   locker => OBJECT
	   log => LEVEL
	   manager => MANAGER
	   message_type	=> CLASS
	   multipart_type => CLASS
	   remove_when_empty =>	BOOLEAN
	   save_on_exit	=> BOOLEAN
	   trace => LEVEL
	   trusted => BOOLEAN

   The folder
       See documentation in the	base class.

       $obj->addMessage(MESSAGE, OPTIONS)
	   See "The folder" in Mail::Box

       $obj->addMessages(MESSAGE [, MESSAGE, ...])
	   See "The folder" in Mail::Box

       Mail::Box::MH->appendMessages(OPTIONS)
	   Append a message to a folder	which is not open.

	    -Option  --Defined in     --Default
	     folder    Mail::Box	<required>
	     message   Mail::Box	undef
	     messages  Mail::Box	undef
	     share     Mail::Box	<false>

	   folder => FOLDERNAME
	   message => MESSAGE
	   messages => ARRAY-OF-MESSAGES
	   share => BOOLEAN
       $obj->close(OPTIONS)
	   See "The folder" in Mail::Box

       $obj->copyTo(FOLDER, OPTIONS)
	   See "The folder" in Mail::Box

       $obj->delete(OPTIONS)
	   See "The folder" in Mail::Box

       $obj->directory()
	   See "The folder" in Mail::Box::Dir

       $obj->folderdir([DIRECTORY])
	   See "The folder" in Mail::Box

       $obj->name()
	   See "The folder" in Mail::Box

       $obj->organization()
	   See "The folder" in Mail::Box

       $obj->size()
	   See "The folder" in Mail::Box

       $obj->type()
	   See "The folder" in Mail::Box

       $obj->update(OPTIONS)
	   See "The folder" in Mail::Box

       $obj->url()
	   See "The folder" in Mail::Box

   Folder flags
       See documentation in the	base class.

       $obj->access()
	   See "Folder flags" in Mail::Box

       $obj->isModified()
	   See "Folder flags" in Mail::Box

       $obj->modified([BOOLEAN])
	   See "Folder flags" in Mail::Box

       $obj->writable()
	   See "Folder flags" in Mail::Box

   The messages
       See documentation in the	base class.

       $obj->current([NUMBER|MESSAGE|MESSAGE-ID])
	   See "The messages" in Mail::Box

       $obj->find(MESSAGE-ID)
	   See "The messages" in Mail::Box

       $obj->findFirstLabeled(LABEL, [BOOLEAN, [ARRAY-OF-MSGS]])
	   See "The messages" in Mail::Box

       $obj->message(INDEX [,MESSAGE])
	   See "The messages" in Mail::Box

       $obj->messageId(MESSAGE-ID [,MESSAGE])
	   See "The messages" in Mail::Box

       $obj->messageIds()
	   See "The messages" in Mail::Box

       $obj->messages(['ALL',RANGE,'ACTIVE','DELETED',LABEL,!LABEL,FILTER])
	   See "The messages" in Mail::Box

       $obj->nrMessages(OPTIONS)
	   See "The messages" in Mail::Box

       $obj->scanForMessages(MESSAGE, MESSAGE-IDS, TIMESPAN, WINDOW)
	   See "The messages" in Mail::Box

   Sub-folders
       See documentation in the	base class.

       $obj->listSubFolders(OPTIONS)
       Mail::Box::MH->listSubFolders(OPTIONS)
	   See "Sub-folders" in	Mail::Box

       $obj->nameOfSubFolder(SUBNAME, [PARENTNAME])
       Mail::Box::MH->nameOfSubFolder(SUBNAME, [PARENTNAME])
	   See "Sub-folders" in	Mail::Box

       $obj->openRelatedFolder(OPTIONS)
	   See "Sub-folders" in	Mail::Box

       $obj->openSubFolder(SUBNAME, OPTIONS)
	   See "Sub-folders" in	Mail::Box

       $obj->topFolderWithMessages()
       Mail::Box::MH->topFolderWithMessages()
	   See "Sub-folders" in	Mail::Box

   Internals
       See documentation in the	base class.

       $obj->coerce(MESSAGE, OPTIONS)
	   See "Internals" in Mail::Box

       $obj->create(FOLDERNAME,	OPTIONS)
       Mail::Box::MH->create(FOLDERNAME, OPTIONS)
	    -Option   --Defined	in--Default
	     folderdir	Mail::Box   undef

	   folderdir =>	DIRECTORY
       $obj->determineBodyType(MESSAGE,	HEAD)
	   See "Internals" in Mail::Box

       $obj->folderToDirectory(FOLDERNAME, FOLDERDIR)
	   See "Internals" in Mail::Box::Dir

       Mail::Box::MH->foundIn([FOLDERNAME], OPTIONS)
	   See "Internals" in Mail::Box

       $obj->highestMessageNumber()
	   Returns the highest number which is used in the folder to store a
	   file.  This method may be called when the folder is read (then this
	   number can be derived without file-system access), but also when
	   the folder is not read (yet).

       $obj->index()
	   Create a index reader/writer	object.

       $obj->labels()
	   Create a label reader/writer	object.

       $obj->lineSeparator([STRING|'CR'|'LF'|'CRLF'])
	   See "Internals" in Mail::Box

       $obj->locker()
	   See "Internals" in Mail::Box

       $obj->read(OPTIONS)
	   See "Internals" in Mail::Box

       $obj->readMessageFilenames(DIRECTORY)
	   See "Internals" in Mail::Box::Dir

       $obj->readMessages(OPTIONS)
	   See "Internals" in Mail::Box

       $obj->storeMessage(MESSAGE)
	   See "Internals" in Mail::Box

       $obj->toBeThreaded(MESSAGES)
	   See "Internals" in Mail::Box

       $obj->toBeUnthreaded(MESSAGES)
	   See "Internals" in Mail::Box

       $obj->updateMessages(OPTIONS)
	   See "Internals" in Mail::Box

       $obj->write(OPTIONS)
	   See "Internals" in Mail::Box

       $obj->writeMessages(OPTIONS)
	    -Option  --Defined in     --Default
	     messages  Mail::Box	<required>
	     renumber			<true>

	   messages => ARRAY
	   renumber => BOOLEAN
	     Permit renumbering	of message.  By	default	this is	true, but for
	     some unknown reason, you may be thinking that messages should not
	     be	renumbered.

   Other methods
       See documentation in the	base class.

       $obj->timespan2seconds(TIME)
       Mail::Box::MH->timespan2seconds(TIME)
	   See "Other methods" in Mail::Box

   Error handling
       See documentation in the	base class.

       $obj->AUTOLOAD()
	   See "Error handling"	in Mail::Reporter

       $obj->addReport(OBJECT)
	   See "Error handling"	in Mail::Reporter

       $obj->defaultTrace([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL, CALLBACK])
       Mail::Box::MH->defaultTrace([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL,
       CALLBACK])
	   See "Error handling"	in Mail::Reporter

       $obj->errors()
	   See "Error handling"	in Mail::Reporter

       $obj->log([LEVEL	[,STRINGS]])
       Mail::Box::MH->log([LEVEL [,STRINGS]])
	   See "Error handling"	in Mail::Reporter

       $obj->logPriority(LEVEL)
       Mail::Box::MH->logPriority(LEVEL)
	   See "Error handling"	in Mail::Reporter

       $obj->logSettings()
	   See "Error handling"	in Mail::Reporter

       $obj->notImplemented()
	   See "Error handling"	in Mail::Reporter

       $obj->report([LEVEL])
	   See "Error handling"	in Mail::Reporter

       $obj->reportAll([LEVEL])
	   See "Error handling"	in Mail::Reporter

       $obj->trace([LEVEL])
	   See "Error handling"	in Mail::Reporter

       $obj->warnings()
	   See "Error handling"	in Mail::Reporter

   Cleanup
       See documentation in the	base class.

       $obj->DESTROY()
	   See "Cleanup" in Mail::Box

DETAILS
       See documentation in the	base class.

   Different kinds of folders
       See documentation in the	base class.

   Available folder types
       See documentation in the	base class.

   Folder class	implementation
       See documentation in the	base class.

   How MH folders work
       MH-type folders use a directory to store	the messages of	one folder.
       Each message is stored in a separate file.  This	seems useful, because
       changes in a folder change only a few of	these small files, in contrast
       with file-based folders where changes in	a folder cause rewrites	of
       huge folder files.

       However,	MH-based folders perform very bad if you need header
       information of all messages.  For instance, if you want to have full
       knowledge about all message-threads (see	Mail::Box::Thread::Manager) in
       the folder, it requires to read all header lines	in all message files.
       And usually, reading your messages in threads is	desired.

       So, each	message	is written in a	separate file.	The filenames are
       numbers,	which count from 1.  Next to these message files, a directory
       may contain a file named	".mh_sequences", storing labels	which relate
       to the messages.	 Furthermore, a	folder-directory may contain sub-
       directories, which are seen as sub-folders.

   This	implementation
       This implementation supports the	".mh-sequences"	file and sub-folders.
       Next to this, considerable effort it made to avoid reading each
       message-file.  This should boost	performance of the MailBox
       distribution over other Perl-modules which are able to read folders.

       Folder types which store	their messages each in one file, together in
       one directory, are bad for performance.	Consider that you want to know
       the subjects of all messages, while browser through a folder with your
       mail-reading client.  This would	cause all message-files	to be read.

       Mail::Box::MH has two ways to try improve performance.  You can use an
       index-file, and use on delay-loading.  The combination performs even
       better.	Both are explained in the next sections.

   An index-file
       If you specify new(keep_index), then all	header-lines of	all messages
       from the	folder which have been read once, will also be written into
       one dedicated index-file	(one file per folder).	The default filename
       is ".index"

       However,	index-files are	not supported by any other reader which
       supports	MH (as far as I	know).	If you read the	folders	with such I
       client, it will not cause unrecoverable conflicts with this index-file,
       but at most be bad for performance.

       If you do not (want to) use an index-file, then delay-loading may save
       your day.

DIAGNOSTICS
       Error: Cannot append message without lock on $folder.
	   It is impossible to append one or more messages to the folder which
	   is not opened, because locking it failes.  The folder may be	in use
	   by an other application, or you may need to specify some lock
	   related options (see	new()).

       Error: Cannot create MH folder $name: $!
	   For some reason, it is impossible to	create the folder.  Check the
	   permissions and the name of the folder.  Does the path to the
	   directory to	be created exist?

       Error: Cannot write folder $name	without	lock.
	   It is impossible to get a lock on the folder, which means that the
	   changes can not be made.  You may need to tune the lock related
	   options which are available at folder creation.

       Warning:	Changes	not written to read-only folder	$self.
	   You have opened the folder read-only	--which	is the default set by
	   new(access)--, made modifications, and now want to close it.	 Set
	   close(force)	if you want to overrule	the access mode, or close the
	   folder with close(write) set	to "NEVER".

       Error: Copying failed for one message.
	   For some reason, for	instance disc full, removed by external
	   process, or read-protection,	it is impossible to copy one of	the
	   messages.  Copying will proceed for the other messages.

       Error: Destination folder $name is not writable.
	   The folder where the	messages are copied to is not opened with
	   write access	(see new(access)).  This has no	relation with write
	   permission to the folder which is controled by your operating
	   system.

       Warning:	Different messages with	id $msgid
	   The message id is discovered	more than once within the same folder,
	   but the content of the message seems	to be different.  This should
	   not be possible: each message must be unique.

       Error: Folder $name is opened read-only
	   You can not write to	this folder unless you have opened the folder
	   to write or append with new(access),	or the "force" option is set
	   true.

       Error: Folder $name not deleted:	not writable.
	   The folder must be opened with write	access via new(access),
	   otherwise removing it will be refused.  So, you may have write-
	   access according to the operating system, but that will not
	   automatically mean that this	"delete" method	permits	you to.	 The
	   reverse remark is valid as well.

       Error: Invalid timespan '$timespan' specified.
	   The string does not follow the strict rules of the time span	syntax
	   which is permitted as parameter.

       Warning:	Message-id '$msgid' does not contain a domain.
	   According to	the RFCs, message-ids need to contain a	unique random
	   part, then an "@", and then a domain	name.  This is made to avoid
	   the creation	of two messages	with the same id.  The warning emerges
	   when	the "@"	is missing from	the string.

       Error: Package $package does not	implement $method.
	   Fatal error:	the specific package (or one of	its superclasses) does
	   not implement this method where it should. This message means that
	   some	other related classes do implement this	method however the
	   class at hand does not.  Probably you should	investigate this and
	   probably inform the author of the package.

       Error: Unable to	create subfolder $name of $folder.
	   The copy includes the subfolders, but for some reason it was	not
	   possible to copy one	of these.  Copying will	proceed	for all	other
	   sub-folders.

       Error: Unable to	write message for $folder to $filename:	$!
	   The new message could not be	written	to its new file, for the
	   specific reason.

       Error: Writing folder $name failed
	   For some reason (you	probably got more error	messages about this
	   problem) it is impossible to	write the folder, although you should
	   because there were changes made.

SEE ALSO
       This module is part of Mail-Box distribution version 2.109, built on
       August 19, 2013.	Website: http://perl.overmeer.net/mailbox/

LICENSE
       Copyrights 2001-2013 by [Mark Overmeer].	For other contributors see
       ChangeLog.

       This program is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself.  See
       http://www.perl.com/perl/misc/Artistic.html

perl v5.24.1			  2013-08-19		      Mail::Box::MH(3)

NAME | INHERITANCE | SYNOPSIS | DESCRIPTION | OVERLOADED | METHODS | DETAILS | DIAGNOSTICS | SEE ALSO | LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Mail::Box::MH&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help