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

FreeBSD Manual Pages

  
 
  

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

NAME
       Mail::Box::File - handle	file-based folders

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

	Mail::Box::File	is extended by
	  Mail::Box::Dbx
	  Mail::Box::Mbox

SYNOPSIS
DESCRIPTION
       "Mail::Box::File" is the	base-class for all file-based folders: folders
       which bundle multiple messages into one single file.  Usually, these
       messages	are separated by a special line	which indicates	the start of
       the next	one.

       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::File->new(OPTIONS)
	    -Option	      --Defined	in     --Default
	     access		Mail::Box	 'r'
	     body_delayed_type	Mail::Box	 Mail::Message::Body::Delayed
	     body_type				 <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			 '.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::File::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>
	     write_policy			 undef

	   access => MODE
	   body_delayed_type =>	CLASS
	   body_type =>	CLASS|CODE
	     The default "body_type" option for	"File" folders,	which will
	     cause messages larger than	10kB to	be stored in files and smaller
	     files in memory, is implemented like this:

	      sub determine_body_type($$)
	      {	  my $head = shift;
		  my $size = shift || 0;
		  'Mail::Message::Body::'
		     . ($size >	10000 ?	'File' : 'Lines');
	      }

	   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
	     When the dotlock locking mechanism	is used, the lock is created
	     with a hardlink to	the folder file.  For "Mail::Box::File"	type
	     of	folders, this file is by default named as the folder-file
	     itself followed by	".lock".  For example: the "Mail/inbox"	folder
	     file will have a hardlink made as "Mail/inbox.lock".

	     You may specify an	absolute filename, a relative (to the folder's
	     directory)	filename, or an	extension (preceded by a dot).	So
	     valid examples are:

	      .lock	   # appended to the folder's filename
	      my_own_lockfile.test   # full filename, same dir
	      /etc/passwd	     # somewhere else

	     When the program runs with	less privileges	(as normal user),
	     often the default inbox folder can	not be locked with the
	     lockfile name which is produced by	default.

	   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
	   write_policy	=> 'REPLACE'|'INPLACE'|undef
	     Sets the default write policy, as default for a later call	to
	     write(policy).  With "undef", the best policy is autodetected.

   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::File->appendMessages(OPTIONS)
	   Appending messages to a file	based folder which is not opened is a
	   little risky.  In practice, this is often done without locking the
	   folder.  So,	another	application may	write to the folder at the
	   same	time...	:(  Hopefully, all goes	fast enough that the chance on
	   collition is	small.

	   All OPTIONS of Mail::Box::Mbox::new() can be	supplied.

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

	   folder => FOLDERNAME
	   lock_type =>	...
	     See Mail::Box::new(lock_type) for possible	values.

	   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->filename()
	   Returns the filename	for this folder, which may be an absolute or
	   relative path to the	file.

	   example:

	    print $folder->filename;

       $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::File->listSubFolders(OPTIONS)
	   See "Sub-folders" in	Mail::Box

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

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

       $obj->folderToFilename(FOLDERNAME, FOLDERDIR, [SUBEXT])
       Mail::Box::File->folderToFilename(FOLDERNAME, FOLDERDIR,	[SUBEXT])
	   Translate a folder name into	a filename, using the FOLDERDIR	value
	   to replace a	leading	"=".  SUBEXT is	only used for MBOX folders.

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

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

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

       $obj->messageCreateOptions([TYPE, CONFIG])
	   Returns a key-value list of options to be used each time a new
	   message is read from	a file.	 The list is preceded by the TYPE of
	   message which has to	be created.

	   This	data is	used by	readMessages() and updateMessages().  With
	   TYPE	and CONFIG, a new configuration	is set.

       $obj->moveAwaySubFolder(DIRECTORY, EXTENSION)
	   The DIRECTORY is renamed by appending the EXTENSION,	which defaults
	   to ".d", to make place for a	folder file on that specific location.
	   "false" is returned if this failed.

       $obj->parser()
	   Create a parser for this mailbox.  The parser stays alive as	long
	   as the folder is open.

       $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)
	   For file based folders, the file handle stays open until the	folder
	   is closed.  Update is therefore rather simple: move to the end of
	   the last known message, and continue	reading...

       $obj->write(OPTIONS)
	    -Option	 --Defined in	  --Default
	     force	   Mail::Box	    <false>
	     policy			    undef
	     save_deleted  Mail::Box	    <false>

	   force => BOOLEAN
	   policy => 'REPLACE'|'INPLACE'|undef
	     In	what way will the mail folder be updated.  If not specified
	     during the	write, the value of the	new(write_policy) at folder
	     creation is taken.

	     Valid values:

	     o	 "REPLACE"

		 First a new folder is written in the same directory as	the
		 folder	which has to be	updated, and then a call to move will
		 throw away the	old immediately	replacing it by	the new.

		 Writing in "REPLACE" module is	slightly optimized: messages
		 which are not modified	are copied from	file to	file, byte by
		 byte.	This is	much faster than printing the data which is
		 will be done for modified messages.

	     o	 "INPLACE"

		 The original folder file will be opened read/write.  All
		 message which where not changed will be left untouched, until
		 the first deleted or modified message is detected.  All
		 further messages are printed again.

	     o	 "undef"

		 As default, or	when "undef" is	explicitly specified, first
		 "REPLACE" mode	is tried.  Only	when that fails, an "INPLACE"
		 update	is performed.

	     "INPLACE" will be much faster than	"REPLACE" when applied on
	     large folders, however requires the "truncate" function to	be
	     implemented on your operating system (at least available for
	     recent versions of	Linux, Solaris,	Tru64, HPUX).  It is also
	     dangerous:	when the program is interrupted	during the update
	     process, the folder is corrupted.	Data may be lost.

	     However, in some cases it is not possible to write	the folder
	     with "REPLACE".  For instance, the	usual incoming mail folder on
	     UNIX is stored in a directory where a user	can not	write.	Of
	     course, the "root"	and "mail" users can, but if you want to use
	     this Perl module with permission of a normal user,	you can	only
	     get it to work in "INPLACE" mode.	Be warned that in this case
	     folder locking via	a lockfile is not possible as well.

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

   Other methods
       See documentation in the	base class.

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

       $obj->logPriority(LEVEL)
       Mail::Box::File->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
       File based folders

       File based folders maintain a folder (a set of messages)	in one single
       file.  The advantage is that your folder	has only one single name,
       which speeds-up access to all messages at once.

       The disadvantage	over directory based folder (see Mail::Box::Dir) is
       that you	have to	construct some means to	keep all message apart,	for
       instance	by adding a message separator, and this	will cause problems.
       Where access to all messages at once is faster in file based folders,
       access to a single message is (much) slower, because the	whole folder
       must be read.

DETAILS
       See documentation in the	base class.

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 create directory $dir for folder $name.
	   While creating a file-organized folder, at most one level of
	   directories is created above	it.  Apparently, more levels of
	   directories are needed, or the operating system does	not allow you
	   to create the directory.

       Error: Cannot create folder file	$name: $!
	   The file-organized folder file cannot be created for	the indicated
	   reason.  In common cases, the operating system does not grant you
	   write access	to the directory where the folder file should be
	   stored.

       Error: Cannot get a lock	on $type folder	$self.
	   A lock is required to get access to the folder.  If no locking is
	   needed, specify the NONE lock type.

       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.

       Warning:	Folder $name file $filename is write-protected.
	   The folder is opened	writable or for	appending via new(access), but
	   the operating system	does not permit	writing	to the file.  The
	   folder will be opened read-only.

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

home | help