1Mail::Box::File(3) User Contributed Perl Documentation Mail::Box::File(3)
2
6 Mail::Box::File - handle file-based folders
7
9 Mail::Box::File
10 is a Mail::Box
11 is a Mail::Reporter
12 Mail::Box::File is extended by
14 Mail::Box::Dbx
15 Mail::Box::Mbox
16
19 "Mail::Box::File" is the base-class for all file-based folders: folders
20 which bundle multiple messages into one single file. Usually, these
21 messages are separated by a special line which indicates the start of
22 the next one.
23
25 overload: ""
26 See "OVERLOADED" in Mail::Box
28 overload: @{}
30 See "OVERLOADED" in Mail::Box
32 overload: cmp
34 See "OVERLOADED" in Mail::Box
36
38 Constructors
39 Mail::Box::File->new(OPTIONS)
41 Option --Defined in --Default
43 access Mail::Box 'r'
44 body_delayed_type Mail::Box Mail::Message::Body::Delayed
45 body_type <see description>
46 coerce_options Mail::Box []
47 create Mail::Box <false>
48 extract Mail::Box 10240
49 field_type Mail::Box undef
50 fix_headers Mail::Box <false>
51 folder Mail::Box $ENV{MAIL}
52 folderdir Mail::Box $ENV{HOME}.'/Mail'
53 head_delayed_type Mail::Box Mail::Message::Head::Delayed
54 head_type Mail::Box Mail::Message::Head::Complete
55 keep_dups Mail::Box <false>
56 lock_extension '.lock'
57 lock_file Mail::Box <foldername><lock-extension>
58 lock_timeout Mail::Box 1 hour
59 lock_type Mail::Box Mail::Box::Locker::DotLock
60 lock_wait Mail::Box 10 seconds
61 locker Mail::Box undef
62 log Mail::Reporter 'WARNINGS'
63 manager Mail::Box undef
64 message_type Mail::Box Mail::Box::File::Message
65 multipart_type Mail::Box Mail::Message::Body::Multipart
66 remove_when_empty Mail::Box <true>
67 save_on_exit Mail::Box <true>
68 trace Mail::Reporter 'WARNINGS'
69 trusted Mail::Box <depends on folder location>
70 write_policy undef
71 . access MODE
73 . body_delayed_type CLASS
75 . body_type CLASS⎪CODE
77 The default "body_type" option for "File" folders, which will
79 cause messages larger than 10kB to be stored in files and
80 smaller files in memory, is implemented like this:
81 sub determine_body_type($$)
83 { my $head = shift;
84 my $size = shift ⎪⎪ 0;
85 'Mail::Message::Body::'
86 . ($size > 10000 ? 'File' : 'Lines');
87 }
88 . coerce_options ARRAY
90 . create BOOLEAN
92 . extract INTEGER ⎪ CODE ⎪ METHOD ⎪ 'LAZY'⎪'ALWAYS'
94 . field_type CLASS
96 . fix_headers BOOLEAN
98 . folder FOLDERNAME
100 . folderdir DIRECTORY
102 . head_delayed_type CLASS
104 . head_type CLASS
106 . keep_dups BOOLEAN
108 . lock_extension FILENAME⎪STRING
110 When the dotlock locking mechanism is used, the lock is created
112 with a hardlink to the folder file. For "Mail::Box::File" type
113 of folders, this file is by default named as the folder-file
114 itself followed by ".lock". For example: the "Mail/inbox"
115 folder file will have a hardlink made as "Mail/inbox.lock".
116 You may specify an absolute filename, a relative (to the
118 folder's directory) filename, or an extension (preceded by a
119 dot). So valid examples are:
120 .lock # appended to the folder's filename
122 my_own_lockfile.test # full filename, same dir
123 /etc/passwd # somewhere else
124 When the program runs with less priviledges (as normal user),
126 often the default inbox folder can not be locked with the lock‐
127 file name which is produced by default.
128 . lock_file FILENAME
130 . lock_timeout SECONDS
132 . lock_type CLASS⎪STRING⎪ARRAY
134 . lock_wait SECONDS
136 . locker OBJECT
138 . log LEVEL
140 . manager MANAGER
142 . message_type CLASS
144 . multipart_type CLASS
146 . remove_when_empty BOOLEAN
148 . save_on_exit BOOLEAN
150 . trace LEVEL
152 . trusted BOOLEAN
154 . write_policy 'REPLACE'⎪'INPLACE'⎪undef
156 Sets the default write policy, as default for a later call to
158 write(policy). With "undef", the best policy is autodetected.
159 The folder
161 $obj->addMessage(MESSAGE, OPTIONS)
163 See "The folder" in Mail::Box
165 $obj->addMessages(MESSAGE [, MESSAGE, ...])
167 See "The folder" in Mail::Box
169 Mail::Box::File->appendMessages(OPTIONS)
171 Appending messages to a file based folder which is not opened is a
173 little risky. In practice, this is often done without locking the
174 folder. So, an other application may write to the folder at the
175 same time... :( Hopefully, all goes fast enough that the chance on
176 collition is small.
177 All OPTIONS of Mail::Box::Mbox::new() can be supplied.
179 Option --Defined in --Default
181 folder Mail::Box <required>
182 lock_type NONE
183 message Mail::Box undef
184 messages Mail::Box undef
185 share Mail::Box <false>
186 . folder FOLDERNAME
188 . lock_type ...
190 See Mail::Box::new(lock_type) for possible values.
192 . message MESSAGE
194 . messages ARRAY-OF-MESSAGES
196 . share BOOLEAN
198 $obj->close(OPTIONS)
200 See "The folder" in Mail::Box
202 $obj->copyTo(FOLDER, OPTIONS)
204 See "The folder" in Mail::Box
206 $obj->delete(OPTIONS)
208 See "The folder" in Mail::Box
210 $obj->filename
212 Returns the filename for this folder, which may be an absolute or
214 relative path to the file.
215 Example:
217 print $folder->filename;
219 $obj->folderdir([DIRECTORY])
221 See "The folder" in Mail::Box
223 $obj->name
225 See "The folder" in Mail::Box
227 $obj->organization
229 See "The folder" in Mail::Box
231 $obj->size
233 See "The folder" in Mail::Box
235 $obj->type
237 See "The folder" in Mail::Box
239 $obj->update(OPTIONS)
241 See "The folder" in Mail::Box
243 $obj->url
245 See "The folder" in Mail::Box
247 Folder flags
249 $obj->access
251 See "Folder flags" in Mail::Box
253 $obj->isModified
255 See "Folder flags" in Mail::Box
257 $obj->modified([BOOLEAN])
259 See "Folder flags" in Mail::Box
261 $obj->writable
263 See "Folder flags" in Mail::Box
265 The messages
267 $obj->current([NUMBER⎪MESSAGE⎪MESSAGE-ID])
269 See "The messages" in Mail::Box
271 $obj->find(MESSAGE-ID)
273 See "The messages" in Mail::Box
275 $obj->findFirstLabeled(LABEL, [BOOLEAN, [ARRAY-OF-MSGS]])
277 See "The messages" in Mail::Box
279 $obj->message(INDEX [,MESSAGE])
281 See "The messages" in Mail::Box
283 $obj->messageId(MESSAGE-ID [,MESSAGE])
285 See "The messages" in Mail::Box
287 $obj->messageIds
289 See "The messages" in Mail::Box
291 $obj->messages(['ALL',RANGE,'ACTIVE','DELETED',LABEL,!LABEL,FILTER])
293 See "The messages" in Mail::Box
295 $obj->nrMessages(OPTIONS)
297 See "The messages" in Mail::Box
299 $obj->scanForMessages(MESSAGE, MESSAGE-IDS, TIMESPAN, WINDOW)
301 See "The messages" in Mail::Box
303 Sub-folders
305 $obj->listSubFolders(OPTIONS)
307 Mail::Box::File->listSubFolders(OPTIONS)
309 See "Sub-folders" in Mail::Box
311 $obj->nameOfSubFolder(SUBNAME, [PARENTNAME])
313 Mail::Box::File->nameOfSubFolder(SUBNAME, [PARENTNAME])
315 See "Sub-folders" in Mail::Box
317 $obj->openRelatedFolder(OPTIONS)
319 See "Sub-folders" in Mail::Box
321 $obj->openSubFolder(SUBNAME, OPTIONS)
323 See "Sub-folders" in Mail::Box
325 $obj->topFolderWithMessages
327 Mail::Box::File->topFolderWithMessages
329 See "Sub-folders" in Mail::Box
331 Internals
333 $obj->coerce(MESSAGE, OPTIONS)
335 See "Internals" in Mail::Box
337 $obj->create(FOLDERNAME, OPTIONS)
339 Mail::Box::File->create(FOLDERNAME, OPTIONS)
341 Option --Defined in--Default
343 folderdir Mail::Box undef
344 . folderdir DIRECTORY
346 $obj->determineBodyType(MESSAGE, HEAD)
348 See "Internals" in Mail::Box
350 $obj->folderToFilename(FOLDERNAME, FOLDERDIR, [SUBEXT])
352 Mail::Box::File->folderToFilename(FOLDERNAME, FOLDERDIR, [SUBEXT])
354 Translate a folder name into a filename, using the FOLDERDIR value
356 to replace a leading "=". SUBEXT is only used for MBOX folders.
357 Mail::Box::File->foundIn([FOLDERNAME], OPTIONS)
359 See "Internals" in Mail::Box
361 $obj->lineSeparator([STRING⎪'CR'⎪'LF'⎪'CRLF'])
363 See "Internals" in Mail::Box
365 $obj->locker
367 See "Internals" in Mail::Box
369 $obj->messageCreateOptions([TYPE, CONFIG])
371 Returns a key-value list of options to be used each time a new mes‐
373 sage is read from a file. The list is preceeded by the TYPE of
374 message which has to be created.
375 This data is used by readMessages() and updateMessages(). With
377 TYPE and CONFIG, a new configuration is set.
378 $obj->moveAwaySubFolder(DIRECTORY, EXTENSION)
380 The DIRECTORY is renamed by appending the EXTENSION, which defaults
382 to ".d", to make place for a folder file on that specific location.
383 "false" is returned if this failed.
384 $obj->parser
386 Create a parser for this mailbox. The parser stays alive as long
388 as the folder is open.
389 $obj->read(OPTIONS)
391 See "Internals" in Mail::Box
393 $obj->readMessages(OPTIONS)
395 See "Internals" in Mail::Box
397 $obj->storeMessage(MESSAGE)
399 See "Internals" in Mail::Box
401 $obj->toBeThreaded(MESSAGES)
403 See "Internals" in Mail::Box
405 $obj->toBeUnthreaded(MESSAGES)
407 See "Internals" in Mail::Box
409 $obj->updateMessages(OPTIONS)
411 For file based folders, the file handle stays open until the folder
413 is closed. Update is therefore rather simple: move to the end of
414 the last known message, and continue reading...
415 $obj->write(OPTIONS)
417 Option --Defined in --Default
419 force Mail::Box <false>
420 policy undef
421 save_deleted Mail::Box <false>
422 . force BOOLEAN
424 . policy 'REPLACE'⎪'INPLACE'⎪undef
426 In what way will the mail folder be updated. If not specified
428 during the write, the value of the new(write_policy) at folder
429 creation is taken.
430 Valid values:
432 * "REPLACE"
434 First a new folder is written in the same directory as the
435 folder which has to be updated, and then a call to move
436 will throw away the old immediately replacing it by the
437 new.
438 Writing in "REPLACE" module is slightly optimized: messages
440 which are not modified are copied from file to file, byte
441 by byte. This is much faster than printing the data which
442 is will be done for modified messages.
443 * "INPLACE"
445 The original folder file will be opened read/write. All
446 message which where not changed will be left untouched,
447 until the first deleted or modified message is detected.
448 All further messages are printed again.
449 * "undef"
451 As default, or when "undef" is explicitly specified, first
452 "REPLACE" mode is tried. Only when that fails, an
453 "INPLACE" update is performed.
454 "INPLACE" will be much faster than "REPLACE" when applied on
456 large folders, however requires the "truncate" function to be
457 implemented on your operating system (at least available for
458 recent versions of Linux, Solaris, Tru64, HPUX). It is also
459 dangerous: when the program is interrupted during the update
460 process, the folder is corrupted. Data may be lost.
461 However, in some cases it is not possible to write the folder
463 with "REPLACE". For instance, the usual incoming mail folder
464 on UNIX is stored in a directory where a user can not write.
465 Of course, the "root" and "mail" users can, but if you want to
466 use this Perl module with permission of a normal user, you can
467 only get it to work in "INPLACE" mode. Be warned that in this
468 case folder locking via a lockfile is not possible as well.
469 . save_deleted BOOLEAN
471 $obj->writeMessages(OPTIONS)
473 See "Internals" in Mail::Box
475 File based folders
477 File based folders maintain a folder (a set of messages) in one single
479 file. The advantage is that your folder has only one single name,
480 which speeds-up access to all messages at once.
481 The disadvantage over directory based folder (see Mail::Box::Dir) is
483 that you have to construct some means to keep all message apart, for
484 instance by adding a message separator, and this will cause problems.
485 Where access to all messages at once is faster in file based folders,
486 access to a single message is (much) slower, because the whole folder
487 must be read.
488 File based folders
490 File based folders maintain a folder (a set of messages) in one single
492 file. The advantage is that your folder has only one single name,
493 which speeds-up access to all messages at once.
494 The disadvantage over directory based folder (see Mail::Box::Dir) is
496 that you have to construct some means to keep all message apart, for
497 instance by adding a message separator, and this will cause problems.
498 Where access to all messages at once is faster in file based folders,
499 access to a single message is (much) slower, because the whole folder
500 must be read.
501 Other methods
503 $obj->timespan2seconds(TIME)
505 Mail::Box::File->timespan2seconds(TIME)
507 See "Other methods" in Mail::Box
509 Error handling
511 $obj->AUTOLOAD
513 See "Error handling" in Mail::Reporter
515 $obj->addReport(OBJECT)
517 See "Error handling" in Mail::Reporter
519 $obj->defaultTrace([LEVEL]⎪[LOGLEVEL, TRACELEVEL]⎪[LEVEL, CALLBACK])
521 Mail::Box::File->defaultTrace([LEVEL]⎪[LOGLEVEL, TRACELEVEL]⎪[LEVEL,
523 CALLBACK])
524 See "Error handling" in Mail::Reporter
526 $obj->errors
528 See "Error handling" in Mail::Reporter
530 $obj->log([LEVEL [,STRINGS]])
532 Mail::Box::File->log([LEVEL [,STRINGS]])
534 See "Error handling" in Mail::Reporter
536 $obj->logPriority(LEVEL)
538 Mail::Box::File->logPriority(LEVEL)
540 See "Error handling" in Mail::Reporter
542 $obj->logSettings
544 See "Error handling" in Mail::Reporter
546 $obj->notImplemented
548 See "Error handling" in Mail::Reporter
550 $obj->report([LEVEL])
552 See "Error handling" in Mail::Reporter
554 $obj->reportAll([LEVEL])
556 See "Error handling" in Mail::Reporter
558 $obj->trace([LEVEL])
560 See "Error handling" in Mail::Reporter
562 $obj->warnings
564 See "Error handling" in Mail::Reporter
566 Cleanup
568 $obj->DESTROY
570 See "Cleanup" in Mail::Box
572 $obj->inGlobalDestruction
574 See "Cleanup" in Mail::Reporter
576
579 Error: Cannot append messages to folder file $filename: $!
580 Appending messages to a not-opened file-organized folder may fail when
582 the operating system does not allow write access to the file at hand.
583 Error: Cannot create directory $dir for folder $name.
585 While creating a file-organized folder, at most one level of directo‐
587 ries is created above it. Apparently, more levels of directories are
588 needed, or the operating system does not allow you to create the direc‐
589 tory.
590 Error: Cannot create folder file $name: $!
592 The file-organized folder file cannot be created for the indicated rea‐
594 son. In common cases, the operating system does not grant you write
595 access to the directory where the folder file should be stored.
596 Error: Cannot get a lock on $type folder $self.
598 A lock is required to get access to the folder. If no locking is
600 needed, specify the NONE lock type.
601 Error: Cannot move away sub-folder $dir
603 Warning: Cannot remove folder $name file $filename: $!
605 Writing an empty folder will usually cause that folder to be removed,
607 which fails for the indicated reason. new(remove_when_empty)
608 Warning: Cannot remove folder $name file $filename: $!
610 Writing an empty folder will usually cause that folder to be removed,
612 which fails for the indicated reason. new(remove_when_empty) controls
613 whether the empty folder will removed; setting it to false (0) may be
614 needed to avoid this message.
615 Error: Cannot replace $filename by $tempname, to update folder $name:
617 $!
618 The replace policy wrote a new folder file to update the existing, but
620 was unable to give the final touch: replacing the old version of the
621 folder file for the indicated reason.
622 Warning: Changes not written to read-only folder $self.
624 You have opened the folder read-only --which is the default set by
626 new(access)--, made modifications, and now want to close it. Set
627 close(force) if you want to overrule the access mode, or close the
628 folder with close(write) set to "NEVER".
629 Error: Copying failed for one message.
631 For some reason, for instance disc full, removed by external process,
633 or read-protection, it is impossible to copy one of the messages.
634 Copying will proceed for the other messages.
635 Error: Destination folder $name is not writable.
637 The folder where the messages are copied to is not opened with write
639 access (see new(access)). This has no relation with write permission
640 to the folder which is controled by your operating system.
641 Warning: Different messages with id $msgid
643 The message id is discovered more than once within the same folder, but
645 the content of the message seems to be different. This should not be
646 possible: each message must be unique.
647 Error: File too short to get write message $nr ($size, $need)
649 Mail::Box is lazy: it tries to leave messages in the folders until they
651 are used, which saves time and memory usage. When this message
652 appears, something is terribly wrong: some lazy message are needed for
653 updating the folder, but they cannot be retreived from the original
654 file anymore. In this case, messages can be lost.
655 This message does appear regularly on Windows systems when using the
657 'replace' write policy. Please help to find the cause, probably some‐
658 thing to do with Windows incorrectly handling multiple filehandles open
659 in the same file.
660 Warning: Folder $name file $filename is write-protected.
662 The folder is opened writable or for appending via new(access), but the
664 operating system does not permit writing to the file. The folder will
665 be opened read-only.
666 Error: Folder $name not deleted: not writable.
668 The folder must be opened with write access via new(access), otherwise
670 removing it will be refused. So, you may have write-access according
671 to the operating system, but that will not automatically mean that this
672 "delete" method permits you to. The reverse remark is valid as well.
673 Error: Invalid timespan '$timespan' specified.
675 The string does not follow the strict rules of the time span syntax
677 which is permitted as parameter.
678 Warning: Message-id '$msgid' does not contain a domain.
680 According to the RFCs, message-ids need to contain a unique random
682 part, then an "@", and then a domain name. This is made to avoid the
683 creation of two messages with the same id. The warning emerges when
684 the "@" is missing from the string.
685 Error: Package $package does not implement $method.
687 Fatal error: the specific package (or one of its superclasses) does not
689 implement this method where it should. This message means that some
690 other related classes do implement this method however the class at
691 hand does not. Probably you should investigate this and probably
692 inform the author of the package.
693 Error: Unable to create subfolder $name of $folder.
695 The copy includes the subfolders, but for some reason it was not possi‐
697 ble to copy one of these. Copying will proceed for all other sub-fold‐
698 ers.
699 Error: Unable to update folder $self.
701 When a folder is to be written, both replace and inplace write policies
703 are tried, If both fail, the whole update fails. You may see other,
704 related, error messages to indicate the real problem.
705
707 This module is part of Mail-Box distribution version 2.070, built on
708 March 25, 2007. Website: http://perl.overmeer.net/mailbox/
709
711 Copyrights 2001-2007 by Mark Overmeer.For other contributors see
712 ChangeLog.
713 This program is free software; you can redistribute it and/or modify it
715 under the same terms as Perl itself. See
716 http://www.perl.com/perl/misc/Artistic.html
717perl v5.8.8 2007-03-25 Mail::Box::File(3)