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

FreeBSD Manual Pages

  
 
  

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

NAME
       Mail::Box::Mbox - handle	folders	in Mbox	format

INHERITANCE
	Mail::Box::Mbox
	  is a Mail::Box::File
	  is a Mail::Box
	  is a Mail::Reporter

SYNOPSIS
	use Mail::Box::Mbox;
	my $folder = Mail::Box::Mbox->new(folder => $ENV{MAIL},	...);

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

       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::Mbox->new(OPTIONS)
	    -Option		--Defined in	 --Default
	     access		  Mail::Box	   'r'
	     body_delayed_type	  Mail::Box	   Mail::Message::Body::Delayed
	     body_type		  Mail::Box::File  <see	description>
	     coerce_options	  Mail::Box	   []
	     create		  Mail::Box	   <false>
	     extract		  Mail::Box	   10240
	     field_type		  Mail::Box	   undef
	     fix_headers	  Mail::Box	   <false>
	     folder		  Mail::Box	   $ENV{MAIL}
	     folderdir		  Mail::Box	   $ENV{HOME}.'/Mail'
	     head_delayed_type	  Mail::Box	   Mail::Message::Head::Delayed
	     head_type		  Mail::Box	   Mail::Message::Head::Complete
	     keep_dups		  Mail::Box	   <false>
	     lock_extension	  Mail::Box::File  '.lock'
	     lock_file		  Mail::Box	   <foldername><lock-extension>
	     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	   Mail::Box::Mbox::Message
	     multipart_type	  Mail::Box	   Mail::Message::Body::Multipart
	     remove_when_empty	  Mail::Box	   <true>
	     save_on_exit	  Mail::Box	   <true>
	     subfolder_extension		   '.d'
	     trace		  Mail::Reporter   'WARNINGS'
	     trusted		  Mail::Box	   <depends on folder location>
	     write_policy	  Mail::Box::File  undef

	   access => MODE
	   body_delayed_type =>	CLASS
	   body_type =>	CLASS|CODE
	   coerce_options => ARRAY
	   create => BOOLEAN
	   extract => INTEGER |	CODE | METHOD |	'LAZY'|'ALWAYS'
	   field_type => CLASS
	   fix_headers => BOOLEAN
	   folder => FOLDERNAME
	   folderdir =>	DIRECTORY
	   head_delayed_type =>	CLASS
	   head_type =>	CLASS
	   keep_dups =>	BOOLEAN
	   lock_extension => FILENAME|STRING
	   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
	   subfolder_extension => STRING
	     Mbox folders do not support sub-folders.  However,	this module
	     can simulate sub-directories if the user wants it to.  When a
	     subfolder of folder "xyz" is created, we create a directory which
	     is	called "xyz.d" to contain them.	 This extension	".d" can be
	     changed using this	option.

	   trace => LEVEL
	   trusted => BOOLEAN
	   write_policy	=> 'REPLACE'|'INPLACE'|undef

   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::Mbox->appendMessages(OPTIONS)
	   See "METHODS" in Mail::Box::File

       $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->filename()
	   See "The folder" in Mail::Box::File

       $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::Mbox->listSubFolders(OPTIONS)
	    -Option		--Defined in	 --Default
	     check		  Mail::Box	   <false>
	     folder		  Mail::Box	   <from calling object>
	     folderdir		  Mail::Box	   <from folder>
	     skip_empty		  Mail::Box	   <false>
	     subfolder_extension		   <from object>

	   check => BOOLEAN
	   folder => FOLDERNAME
	   folderdir =>	DIRECTORY
	   skip_empty => BOOL
	   subfolder_extension => STRING
	     When the method is	called on an open folder, the extension
	     defined by	it is used to detect sub-folders by default.
	     Otherwise,	'.d' is	taken.

       $obj->nameOfSubFolder(SUBNAME, [PARENTNAME])
       Mail::Box::Mbox->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::Mbox->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::Mbox->create(FOLDERNAME, OPTIONS)
	    -Option		--Defined in	 --Default
	     folderdir		  Mail::Box	   undef
	     subfolder_extension		   undef

	   folderdir =>	DIRECTORY
	   subfolder_extension => STRING
	     If	a directory is found on	the location of	the folder to be
	     created, this STRING is used to extend that directory name	with.
	     This will cause the directory to be seen as sub-folder for	the
	     created folder.  This argument is passed to folderToFilename().

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

       $obj->folderToFilename(FOLDERNAME, FOLDERDIR, [EXTENSION])
       Mail::Box::Mbox->folderToFilename(FOLDERNAME, FOLDERDIR,	[EXTENSION])
	   Translate a folder name into	a filename, using the FOLDERDIR	value
	   to replace a	leading	"=".  If no EXTENSION is specified and this
	   method is called as instance	method,	new(subfolder_extension) is
	   used.  Otherwise, the extension default to '.d'.

       Mail::Box::Mbox->foundIn([FOLDERNAME], [OPTIONS])
	   If no FOLDERNAME is specified, then the value of the	"folder"
	   option is taken.  A mbox folder is a	file which starts with a
	   separator line: a line with 'From ' as first	characters.  Blank
	   lines which start the file are ignored, which is not	for all	MUA's
	   acceptable.

	    -Option		--Defined in	 --Default
	     folder				   undef
	     folderdir		  Mail::Box	   undef
	     subfolder_extension		   <from object>

	   folder => FOLDERNAME
	   folderdir =>	DIRECTORY
	   subfolder_extension => STRING
       $obj->lineSeparator([STRING|'CR'|'LF'|'CRLF'])
	   See "Internals" in Mail::Box

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

       $obj->messageCreateOptions([TYPE, CONFIG])
	   See "Internals" in Mail::Box::File

       $obj->moveAwaySubFolder(DIRECTORY, EXTENSION)
	   See "Internals" in Mail::Box::File

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

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

       $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::File

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

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

   Other methods
       See documentation in the	base class.

       $obj->timespan2seconds(TIME)
       Mail::Box::Mbox->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::Mbox->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::Mbox->log([LEVEL [,STRINGS]])
	   See "Error handling"	in Mail::Reporter

       $obj->logPriority(LEVEL)
       Mail::Box::Mbox->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.

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 MBOX folders work
       MBOX folders store many messages	in one file.  Each message begins with
       a line which starts with	the string "From ".  Lines inside a message
       which accidentally start	with "From" are, in the	file, preceded by `>'.
       This character is stripped when the message is read.

       In this respect must be noted that the format of	the MBOX files is not
       strictly	defined.  The exact content of the separator lines differ
       between Mail User Agents	(MUA's).  Besides, some	MUAs (like mutt)
       forget to encode	the "From " lines within message bodies, breaking
       other parsers....

   Simulation of sub-folders
       MBOX folders do not have	a sub-folder concept as	directory based
       folders do, but this MBOX module	tries to simulate them.	 In this
       implementation a	directory like

	Mail/subject1/

       is taken	as an empty folder "Mail/subject1", with the folders in	that
       directory as sub-folders	for it.	 You may also use

	Mail/subject1
	Mail/subject1.d/

       where "Mail/subject1" is	the folder, and	the folders in the
       "Mail/subject1.d" directory are used as sub-folders.  If	your situation
       is similar to the first example and you want to put messages in that
       empty folder, the directory is automatically (and transparently)
       renamed,	so that	the second situation is	reached.

DIAGNOSTICS
       Error: Cannot append messages to	folder file $filename: $!
	   Appending messages to a not-opened file-organized folder may	fail
	   when	the operating system does not allow write access to the	file
	   at hand.

       Error: Cannot move away sub-folder $dir
       Warning:	Cannot remove folder $name file	$filename: $!
	   Writing an empty folder will	usually	cause that folder to be
	   removed, which fails	for the	indicated reason.
	   new(remove_when_empty)

       Warning:	Cannot remove folder $name file	$filename: $!
	   Writing an empty folder will	usually	cause that folder to be
	   removed, which fails	for the	indicated reason.
	   new(remove_when_empty) controls whether the empty folder will
	   removed; setting it to false	(0) may	be needed to avoid this
	   message.

       Error: Cannot replace $filename by $tempname, to	update folder $name:
       $!
	   The replace policy wrote a new folder file to update	the existing,
	   but was unable to give the final touch: replacing the old version
	   of the folder file for the indicated	reason.

       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: File too short to	get write message $nr ($size, $need)
	   Mail::Box is	lazy: it tries to leave	messages in the	folders	until
	   they	are used, which	saves time and memory usage.  When this
	   message appears, something is terribly wrong: some lazy message are
	   needed for updating the folder, but they cannot be retrieved	from
	   the original	file anymore.  In this case, messages can be lost.

	   This	message	does appear regularly on Windows systems when using
	   the 'replace' write policy.	Please help to find the	cause,
	   probably something to do with Windows incorrectly handling multiple
	   filehandles open in the same	file.

       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	update folder $self.
	   When	a folder is to be written, both	replace	and inplace write
	   policies are	tried,	If both	fail, the whole	update fails.  You may
	   see other, related, error messages to indicate the real problem.

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::Mbox(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::Mbox&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help