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
18 "Mail::Box::File" is the base-class for all file-based folders: folders
19 which bundle multiple messages into one single file. Usually, these
20 messages are separated by a special line which indicates the start of
21 the next one.
22
24 overload: ""
25 See "OVERLOADED" in Mail::Box
26 overload: @{}
28 See "OVERLOADED" in Mail::Box
29 overload: cmp
31 See "OVERLOADED" in Mail::Box
32
34 Constructors
35 Mail::Box::File->new(OPTIONS)
36 -Option --Defined in --Default
37 access Mail::Box 'r'
38 body_delayed_type Mail::Box Mail::Message::Body::Delayed
39 body_type <see description>
40 coerce_options Mail::Box []
41 create Mail::Box <false>
42 extract Mail::Box 10240
43 field_type Mail::Box undef
44 fix_headers Mail::Box <false>
45 folder Mail::Box $ENV{MAIL}
46 folderdir Mail::Box $ENV{HOME}.'/Mail'
47 head_delayed_type Mail::Box Mail::Message::Head::Delayed
48 head_type Mail::Box Mail::Message::Head::Complete
49 keep_dups Mail::Box <false>
50 lock_extension '.lock'
51 lock_file Mail::Box <foldername><lock-extension>
52 lock_timeout Mail::Box 1 hour
53 lock_type Mail::Box Mail::Box::Locker::DotLock
54 lock_wait Mail::Box 10 seconds
55 locker Mail::Box undef
56 log Mail::Reporter 'WARNINGS'
57 manager Mail::Box undef
58 message_type Mail::Box Mail::Box::File::Message
59 multipart_type Mail::Box Mail::Message::Body::Multipart
60 remove_when_empty Mail::Box <true>
61 save_on_exit Mail::Box <true>
62 trace Mail::Reporter 'WARNINGS'
63 trusted Mail::Box <depends on folder location>
64 write_policy undef
65 access => MODE
67 body_delayed_type => CLASS
68 body_type => CLASS|CODE
69 The default "body_type" option for "File" folders, which will
70 cause messages larger than 10kB to be stored in files and smaller
71 files in memory, is implemented like this:
72 sub determine_body_type($$)
74 { my $head = shift;
75 my $size = shift || 0;
76 'Mail::Message::Body::'
77 . ($size > 10000 ? 'File' : 'Lines');
78 }
79 coerce_options => ARRAY
81 create => BOOLEAN
82 extract => INTEGER | CODE | METHOD | 'LAZY'|'ALWAYS'
83 field_type => CLASS
84 fix_headers => BOOLEAN
85 folder => FOLDERNAME
86 folderdir => DIRECTORY
87 head_delayed_type => CLASS
88 head_type => CLASS
89 keep_dups => BOOLEAN
90 lock_extension => FILENAME|STRING
91 When the dotlock locking mechanism is used, the lock is created
92 with a hardlink to the folder file. For "Mail::Box::File" type
93 of folders, this file is by default named as the folder-file
94 itself followed by ".lock". For example: the "Mail/inbox" folder
95 file will have a hardlink made as "Mail/inbox.lock".
96 You may specify an absolute filename, a relative (to the folder's
98 directory) filename, or an extension (preceded by a dot). So
99 valid examples are:
100 .lock # appended to the folder's filename
102 my_own_lockfile.test # full filename, same dir
103 /etc/passwd # somewhere else
104 When the program runs with less priviledges (as normal user),
106 often the default inbox folder can not be locked with the
107 lockfile name which is produced by default.
108 lock_file => FILENAME
110 lock_timeout => SECONDS
111 lock_type => CLASS|STRING|ARRAY
112 lock_wait => SECONDS
113 locker => OBJECT
114 log => LEVEL
115 manager => MANAGER
116 message_type => CLASS
117 multipart_type => CLASS
118 remove_when_empty => BOOLEAN
119 save_on_exit => BOOLEAN
120 trace => LEVEL
121 trusted => BOOLEAN
122 write_policy => 'REPLACE'|'INPLACE'|undef
123 Sets the default write policy, as default for a later call to
124 write(policy). With "undef", the best policy is autodetected.
125 The folder
127 $obj->addMessage(MESSAGE, OPTIONS)
128 See "The folder" in Mail::Box
129 $obj->addMessages(MESSAGE [, MESSAGE, ...])
131 See "The folder" in Mail::Box
132 Mail::Box::File->appendMessages(OPTIONS)
134 Appending messages to a file based folder which is not opened is a
135 little risky. In practice, this is often done without locking the
136 folder. So, another application may write to the folder at the
137 same time... :( Hopefully, all goes fast enough that the chance on
138 collition is small.
139 All OPTIONS of Mail::Box::Mbox::new() can be supplied.
141 -Option --Defined in --Default
143 folder Mail::Box <required>
144 lock_type NONE
145 message Mail::Box undef
146 messages Mail::Box undef
147 share Mail::Box <false>
148 folder => FOLDERNAME
150 lock_type => ...
151 See Mail::Box::new(lock_type) for possible values.
152 message => MESSAGE
154 messages => ARRAY-OF-MESSAGES
155 share => BOOLEAN
156 $obj->close(OPTIONS)
157 See "The folder" in Mail::Box
158 $obj->copyTo(FOLDER, OPTIONS)
160 See "The folder" in Mail::Box
161 $obj->delete(OPTIONS)
163 See "The folder" in Mail::Box
164 $obj->filename
166 Returns the filename for this folder, which may be an absolute or
167 relative path to the file.
168 example:
170 print $folder->filename;
172 $obj->folderdir([DIRECTORY])
174 See "The folder" in Mail::Box
175 $obj->name
177 See "The folder" in Mail::Box
178 $obj->organization
180 See "The folder" in Mail::Box
181 $obj->size
183 See "The folder" in Mail::Box
184 $obj->type
186 See "The folder" in Mail::Box
187 $obj->update(OPTIONS)
189 See "The folder" in Mail::Box
190 $obj->url
192 See "The folder" in Mail::Box
193 Folder flags
195 $obj->access
196 See "Folder flags" in Mail::Box
197 $obj->isModified
199 See "Folder flags" in Mail::Box
200 $obj->modified([BOOLEAN])
202 See "Folder flags" in Mail::Box
203 $obj->writable
205 See "Folder flags" in Mail::Box
206 The messages
208 $obj->current([NUMBER|MESSAGE|MESSAGE-ID])
209 See "The messages" in Mail::Box
210 $obj->find(MESSAGE-ID)
212 See "The messages" in Mail::Box
213 $obj->findFirstLabeled(LABEL, [BOOLEAN, [ARRAY-OF-MSGS]])
215 See "The messages" in Mail::Box
216 $obj->message(INDEX [,MESSAGE])
218 See "The messages" in Mail::Box
219 $obj->messageId(MESSAGE-ID [,MESSAGE])
221 See "The messages" in Mail::Box
222 $obj->messageIds
224 See "The messages" in Mail::Box
225 $obj->messages(['ALL',RANGE,'ACTIVE','DELETED',LABEL,!LABEL,FILTER])
227 See "The messages" in Mail::Box
228 $obj->nrMessages(OPTIONS)
230 See "The messages" in Mail::Box
231 $obj->scanForMessages(MESSAGE, MESSAGE-IDS, TIMESPAN, WINDOW)
233 See "The messages" in Mail::Box
234 Sub-folders
236 $obj->listSubFolders(OPTIONS)
237 Mail::Box::File->listSubFolders(OPTIONS)
238 See "Sub-folders" in Mail::Box
240 $obj->nameOfSubFolder(SUBNAME, [PARENTNAME])
242 Mail::Box::File->nameOfSubFolder(SUBNAME, [PARENTNAME])
243 See "Sub-folders" in Mail::Box
245 $obj->openRelatedFolder(OPTIONS)
247 See "Sub-folders" in Mail::Box
248 $obj->openSubFolder(SUBNAME, OPTIONS)
250 See "Sub-folders" in Mail::Box
251 $obj->topFolderWithMessages
253 Mail::Box::File->topFolderWithMessages
254 See "Sub-folders" in Mail::Box
256 Internals
258 $obj->coerce(MESSAGE, OPTIONS)
259 See "Internals" in Mail::Box
260 $obj->create(FOLDERNAME, OPTIONS)
262 Mail::Box::File->create(FOLDERNAME, OPTIONS)
263 -Option --Defined in--Default
265 folderdir Mail::Box undef
266 folderdir => DIRECTORY
268 $obj->determineBodyType(MESSAGE, HEAD)
269 See "Internals" in Mail::Box
270 $obj->folderToFilename(FOLDERNAME, FOLDERDIR, [SUBEXT])
272 Mail::Box::File->folderToFilename(FOLDERNAME, FOLDERDIR, [SUBEXT])
273 Translate a folder name into a filename, using the FOLDERDIR value
275 to replace a leading "=". SUBEXT is only used for MBOX folders.
276 Mail::Box::File->foundIn([FOLDERNAME], OPTIONS)
278 See "Internals" in Mail::Box
279 $obj->lineSeparator([STRING|'CR'|'LF'|'CRLF'])
281 See "Internals" in Mail::Box
282 $obj->locker
284 See "Internals" in Mail::Box
285 $obj->messageCreateOptions([TYPE, CONFIG])
287 Returns a key-value list of options to be used each time a new
288 message is read from a file. The list is preceded by the TYPE of
289 message which has to be created.
290 This data is used by readMessages() and updateMessages(). With
292 TYPE and CONFIG, a new configuration is set.
293 $obj->moveAwaySubFolder(DIRECTORY, EXTENSION)
295 The DIRECTORY is renamed by appending the EXTENSION, which defaults
296 to ".d", to make place for a folder file on that specific location.
297 "false" is returned if this failed.
298 $obj->parser
300 Create a parser for this mailbox. The parser stays alive as long
301 as the folder is open.
302 $obj->read(OPTIONS)
304 See "Internals" in Mail::Box
305 $obj->readMessages(OPTIONS)
307 See "Internals" in Mail::Box
308 $obj->storeMessage(MESSAGE)
310 See "Internals" in Mail::Box
311 $obj->toBeThreaded(MESSAGES)
313 See "Internals" in Mail::Box
314 $obj->toBeUnthreaded(MESSAGES)
316 See "Internals" in Mail::Box
317 $obj->updateMessages(OPTIONS)
319 For file based folders, the file handle stays open until the folder
320 is closed. Update is therefore rather simple: move to the end of
321 the last known message, and continue reading...
322 $obj->write(OPTIONS)
324 -Option --Defined in --Default
325 force Mail::Box <false>
326 policy undef
327 save_deleted Mail::Box <false>
328 force => BOOLEAN
330 policy => 'REPLACE'|'INPLACE'|undef
331 In what way will the mail folder be updated. If not specified
332 during the write, the value of the new(write_policy) at folder
333 creation is taken.
334 Valid values:
336 · "REPLACE"
338 First a new folder is written in the same directory as the
340 folder which has to be updated, and then a call to move will
341 throw away the old immediately replacing it by the new.
342 Writing in "REPLACE" module is slightly optimized: messages
344 which are not modified are copied from file to file, byte by
345 byte. This is much faster than printing the data which is
346 will be done for modified messages.
347 · "INPLACE"
349 The original folder file will be opened read/write. All
351 message which where not changed will be left untouched, until
352 the first deleted or modified message is detected. All
353 further messages are printed again.
354 · "undef"
356 As default, or when "undef" is explicitly specified, first
358 "REPLACE" mode is tried. Only when that fails, an "INPLACE"
359 update is performed.
360 "INPLACE" will be much faster than "REPLACE" when applied on
362 large folders, however requires the "truncate" function to be
363 implemented on your operating system (at least available for
364 recent versions of Linux, Solaris, Tru64, HPUX). It is also
365 dangerous: when the program is interrupted during the update
366 process, the folder is corrupted. Data may be lost.
367 However, in some cases it is not possible to write the folder
369 with "REPLACE". For instance, the usual incoming mail folder on
370 UNIX is stored in a directory where a user can not write. Of
371 course, the "root" and "mail" users can, but if you want to use
372 this Perl module with permission of a normal user, you can only
373 get it to work in "INPLACE" mode. Be warned that in this case
374 folder locking via a lockfile is not possible as well.
375 save_deleted => BOOLEAN
377 $obj->writeMessages(OPTIONS)
378 See "Internals" in Mail::Box
379 Other methods
381 $obj->timespan2seconds(TIME)
382 Mail::Box::File->timespan2seconds(TIME)
383 See "Other methods" in Mail::Box
385 Error handling
387 $obj->AUTOLOAD
388 See "Error handling" in Mail::Reporter
389 $obj->addReport(OBJECT)
391 See "Error handling" in Mail::Reporter
392 $obj->defaultTrace([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL, CALLBACK])
394 Mail::Box::File->defaultTrace([LEVEL]|[LOGLEVEL,
395 TRACELEVEL]|[LEVEL, CALLBACK])
396 See "Error handling" in Mail::Reporter
398 $obj->errors
400 See "Error handling" in Mail::Reporter
401 $obj->log([LEVEL [,STRINGS]])
403 Mail::Box::File->log([LEVEL [,STRINGS]])
404 See "Error handling" in Mail::Reporter
406 $obj->logPriority(LEVEL)
408 Mail::Box::File->logPriority(LEVEL)
409 See "Error handling" in Mail::Reporter
411 $obj->logSettings
413 See "Error handling" in Mail::Reporter
414 $obj->notImplemented
416 See "Error handling" in Mail::Reporter
417 $obj->report([LEVEL])
419 See "Error handling" in Mail::Reporter
420 $obj->reportAll([LEVEL])
422 See "Error handling" in Mail::Reporter
423 $obj->trace([LEVEL])
425 See "Error handling" in Mail::Reporter
426 $obj->warnings
428 See "Error handling" in Mail::Reporter
429 Cleanup
431 $obj->DESTROY
432 See "Cleanup" in Mail::Box
433 $obj->inGlobalDestruction
435 See "Cleanup" in Mail::Reporter
436 DETAILS
438 File based folders
439 File based folders maintain a folder (a set of messages) in one single
441 file. The advantage is that your folder has only one single name,
442 which speeds-up access to all messages at once.
443 The disadvantage over directory based folder (see Mail::Box::Dir) is
445 that you have to construct some means to keep all message apart, for
446 instance by adding a message separator, and this will cause problems.
447 Where access to all messages at once is faster in file based folders,
448 access to a single message is (much) slower, because the whole folder
449 must be read.
450
452 Error: Cannot append messages to folder file $filename: $!
453 Appending messages to a not-opened file-organized folder may fail
454 when the operating system does not allow write access to the file
455 at hand.
456 Error: Cannot create directory $dir for folder $name.
458 While creating a file-organized folder, at most one level of
459 directories is created above it. Apparently, more levels of
460 directories are needed, or the operating system does not allow you
461 to create the directory.
462 Error: Cannot create folder file $name: $!
464 The file-organized folder file cannot be created for the indicated
465 reason. In common cases, the operating system does not grant you
466 write access to the directory where the folder file should be
467 stored.
468 Error: Cannot get a lock on $type folder $self.
470 A lock is required to get access to the folder. If no locking is
471 needed, specify the NONE lock type.
472 Error: Cannot move away sub-folder $dir
474 Warning: Cannot remove folder $name file $filename: $!
475 Writing an empty folder will usually cause that folder to be
476 removed, which fails for the indicated reason.
477 new(remove_when_empty)
478 Warning: Cannot remove folder $name file $filename: $!
480 Writing an empty folder will usually cause that folder to be
481 removed, which fails for the indicated reason.
482 new(remove_when_empty) controls whether the empty folder will
483 removed; setting it to false (0) may be needed to avoid this
484 message.
485 Error: Cannot replace $filename by $tempname, to update folder $name:
487 $!
488 The replace policy wrote a new folder file to update the existing,
489 but was unable to give the final touch: replacing the old version
490 of the folder file for the indicated reason.
491 Warning: Changes not written to read-only folder $self.
493 You have opened the folder read-only --which is the default set by
494 new(access)--, made modifications, and now want to close it. Set
495 close(force) if you want to overrule the access mode, or close the
496 folder with close(write) set to "NEVER".
497 Error: Copying failed for one message.
499 For some reason, for instance disc full, removed by external
500 process, or read-protection, it is impossible to copy one of the
501 messages. Copying will proceed for the other messages.
502 Error: Destination folder $name is not writable.
504 The folder where the messages are copied to is not opened with
505 write access (see new(access)). This has no relation with write
506 permission to the folder which is controled by your operating
507 system.
508 Warning: Different messages with id $msgid
510 The message id is discovered more than once within the same folder,
511 but the content of the message seems to be different. This should
512 not be possible: each message must be unique.
513 Error: File too short to get write message $nr ($size, $need)
515 Mail::Box is lazy: it tries to leave messages in the folders until
516 they are used, which saves time and memory usage. When this
517 message appears, something is terribly wrong: some lazy message are
518 needed for updating the folder, but they cannot be retreived from
519 the original file anymore. In this case, messages can be lost.
520 This message does appear regularly on Windows systems when using
522 the 'replace' write policy. Please help to find the cause,
523 probably something to do with Windows incorrectly handling multiple
524 filehandles open in the same file.
525 Warning: Folder $name file $filename is write-protected.
527 The folder is opened writable or for appending via new(access), but
528 the operating system does not permit writing to the file. The
529 folder will be opened read-only.
530 Error: Folder $name not deleted: not writable.
532 The folder must be opened with write access via new(access),
533 otherwise removing it will be refused. So, you may have write-
534 access according to the operating system, but that will not
535 automatically mean that this "delete" method permits you to. The
536 reverse remark is valid as well.
537 Error: Invalid timespan '$timespan' specified.
539 The string does not follow the strict rules of the time span syntax
540 which is permitted as parameter.
541 Warning: Message-id '$msgid' does not contain a domain.
543 According to the RFCs, message-ids need to contain a unique random
544 part, then an "@", and then a domain name. This is made to avoid
545 the creation of two messages with the same id. The warning emerges
546 when the "@" is missing from the string.
547 Error: Package $package does not implement $method.
549 Fatal error: the specific package (or one of its superclasses) does
550 not implement this method where it should. This message means that
551 some other related classes do implement this method however the
552 class at hand does not. Probably you should investigate this and
553 probably inform the author of the package.
554 Error: Unable to create subfolder $name of $folder.
556 The copy includes the subfolders, but for some reason it was not
557 possible to copy one of these. Copying will proceed for all other
558 sub-folders.
559 Error: Unable to update folder $self.
561 When a folder is to be written, both replace and inplace write
562 policies are tried, If both fail, the whole update fails. You may
563 see other, related, error messages to indicate the real problem.
564
566 This module is part of Mail-Box distribution version 2.097, built on
567 January 26, 2011. Website: http://perl.overmeer.net/mailbox/
568
570 Copyrights 2001-2011 by Mark Overmeer. For other contributors see
571 ChangeLog.
572 This program is free software; you can redistribute it and/or modify it
574 under the same terms as Perl itself. See
575 http://www.perl.com/perl/misc/Artistic.html
576perl v5.12.3 2011-01-26 Mail::Box::File(3)