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 Extends "DESCRIPTION" in Mail::Box.
25
27 Extends "OVERLOADED" in Mail::Box.
28 overload: ""
30 Inherited, see "OVERLOADED" in Mail::Box
31 overload: @{}
33 Inherited, see "OVERLOADED" in Mail::Box
34 overload: cmp
36 Inherited, see "OVERLOADED" in Mail::Box
37
39 Extends "METHODS" in Mail::Box.
40 Constructors
42 Extends "Constructors" in Mail::Box.
43 Mail::Box::File->new(%options)
45 -Option --Defined in --Default
46 access Mail::Box 'r'
47 body_delayed_type Mail::Box Mail::Message::Body::Delayed
48 body_type <see description>
49 coerce_options Mail::Box []
50 create Mail::Box <false>
51 extract Mail::Box 10240
52 field_type Mail::Box undef
53 fix_headers Mail::Box <false>
54 folder Mail::Box $ENV{MAIL}
55 folderdir Mail::Box $ENV{HOME}.'/Mail'
56 head_delayed_type Mail::Box Mail::Message::Head::Delayed
57 head_type Mail::Box Mail::Message::Head::Complete
58 keep_dups Mail::Box <false>
59 lock_extension '.lock'
60 lock_file Mail::Box <foldername><lock-extension>
61 lock_timeout Mail::Box 1 hour
62 lock_type Mail::Box Mail::Box::Locker::DotLock
63 lock_wait Mail::Box 10 seconds
64 locker Mail::Box undef
65 log Mail::Reporter 'WARNINGS'
66 manager Mail::Box undef
67 message_type Mail::Box Mail::Box::File::Message
68 multipart_type Mail::Box Mail::Message::Body::Multipart
69 remove_when_empty Mail::Box <true>
70 save_on_exit Mail::Box <true>
71 trace Mail::Reporter 'WARNINGS'
72 trusted Mail::Box <depends on folder location>
73 write_policy undef
74 access => MODE
76 body_delayed_type => CLASS
77 body_type => CLASS|CODE
78 The default "body_type" option for "File" folders, which will
79 cause messages larger than 10kB to be stored in files and smaller
80 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
91 extract => INTEGER | CODE | METHOD | 'LAZY'|'ALWAYS'
92 field_type => CLASS
93 fix_headers => BOOLEAN
94 folder => FOLDERNAME
95 folderdir => DIRECTORY
96 head_delayed_type => CLASS
97 head_type => CLASS
98 keep_dups => BOOLEAN
99 lock_extension => FILENAME|STRING
100 When the dotlock locking mechanism is used, the lock is created
101 with a hardlink to the folder file. For "Mail::Box::File" type
102 of folders, this file is by default named as the folder-file
103 itself followed by ".lock". For example: the "Mail/inbox" folder
104 file will have a hardlink made as "Mail/inbox.lock".
105 You may specify an absolute filename, a relative (to the folder's
107 directory) filename, or an extension (preceded by a dot). So
108 valid examples are:
109 .lock # appended to the folder's filename
111 my_own_lockfile.test # full filename, same dir
112 /etc/passwd # somewhere else
113 When the program runs with less privileges (as normal user),
115 often the default inbox folder can not be locked with the
116 lockfile name which is produced by default.
117 lock_file => FILENAME
119 lock_timeout => SECONDS
120 lock_type => CLASS|STRING|ARRAY
121 lock_wait => SECONDS
122 locker => OBJECT
123 log => LEVEL
124 manager => MANAGER
125 message_type => CLASS
126 multipart_type => CLASS
127 remove_when_empty => BOOLEAN
128 save_on_exit => BOOLEAN
129 trace => LEVEL
130 trusted => BOOLEAN
131 write_policy => 'REPLACE'|'INPLACE'|undef
132 Sets the default write policy, as default for a later call to
133 write(policy). With "undef", the best policy is autodetected.
134 The folder
136 Extends "The folder" in Mail::Box.
137 $obj->addMessage($message, %options)
139 Inherited, see "The folder" in Mail::Box
140 $obj->addMessages(@messages)
142 Inherited, see "The folder" in Mail::Box
143 Mail::Box::File->appendMessages(%options)
145 Appending messages to a file based folder which is not opened is a
146 little risky. In practice, this is often done without locking the
147 folder. So, another application may write to the folder at the
148 same time... :( Hopefully, all goes fast enough that the chance on
149 collision is small.
150 All %options of Mail::Box::Mbox::new() can be supplied.
152 -Option --Defined in --Default
154 folder Mail::Box <required>
155 lock_type NONE
156 message Mail::Box undef
157 messages Mail::Box undef
158 share Mail::Box <false>
159 folder => FOLDERNAME
161 lock_type => ...
162 See Mail::Box::new(lock_type) for possible values.
163 message => MESSAGE
165 messages => ARRAY-OF-MESSAGES
166 share => BOOLEAN
167 $obj->close(%options)
168 Inherited, see "The folder" in Mail::Box
169 $obj->copyTo($folder, %options)
171 Inherited, see "The folder" in Mail::Box
172 $obj->delete(%options)
174 Inherited, see "The folder" in Mail::Box
175 $obj->filename()
177 Returns the filename for this folder, which may be an absolute or
178 relative path to the file.
179 example:
181 print $folder->filename;
183 $obj->folderdir( [$directory] )
185 Inherited, see "The folder" in Mail::Box
186 $obj->name()
188 Inherited, see "The folder" in Mail::Box
189 $obj->organization()
191 Inherited, see "The folder" in Mail::Box
192 $obj->size()
194 Inherited, see "The folder" in Mail::Box
195 $obj->type()
197 Inherited, see "The folder" in Mail::Box
198 $obj->update(%options)
200 Inherited, see "The folder" in Mail::Box
201 $obj->url()
203 Inherited, see "The folder" in Mail::Box
204 Folder flags
206 Extends "Folder flags" in Mail::Box.
207 $obj->access()
209 Inherited, see "Folder flags" in Mail::Box
210 $obj->isModified()
212 Inherited, see "Folder flags" in Mail::Box
213 $obj->modified( [BOOLEAN] )
215 Inherited, see "Folder flags" in Mail::Box
216 $obj->writable()
218 Inherited, see "Folder flags" in Mail::Box
219 The messages
221 Extends "The messages" in Mail::Box.
222 $obj->current( [$number|$message|$message_id] )
224 Inherited, see "The messages" in Mail::Box
225 $obj->find($message_id)
227 Inherited, see "The messages" in Mail::Box
228 $obj->findFirstLabeled( $label, [BOOLEAN, [$msgs]] )
230 Inherited, see "The messages" in Mail::Box
231 $obj->message( $index, [$message] )
233 Inherited, see "The messages" in Mail::Box
234 $obj->messageId( $message_id, [$message] )
236 Inherited, see "The messages" in Mail::Box
237 $obj->messageIds()
239 Inherited, see "The messages" in Mail::Box
240 $obj->messages( <'ALL'|$range|'ACTIVE'|'DELETED'|$label|
242 !$label|$filter> )
243 Inherited, see "The messages" in Mail::Box
244 $obj->nrMessages(%options)
246 Inherited, see "The messages" in Mail::Box
247 $obj->scanForMessages($message, $message_ids, $timespan, $window)
249 Inherited, see "The messages" in Mail::Box
250 Sub-folders
252 Extends "Sub-folders" in Mail::Box.
253 $obj->listSubFolders(%options)
255 Mail::Box::File->listSubFolders(%options)
256 Inherited, see "Sub-folders" in Mail::Box
257 $obj->nameOfSubFolder( $subname, [$parentname] )
259 Mail::Box::File->nameOfSubFolder( $subname, [$parentname] )
260 Inherited, see "Sub-folders" in Mail::Box
261 $obj->openRelatedFolder(%options)
263 Inherited, see "Sub-folders" in Mail::Box
264 $obj->openSubFolder($subname, %options)
266 Inherited, see "Sub-folders" in Mail::Box
267 $obj->topFolderWithMessages()
269 Mail::Box::File->topFolderWithMessages()
270 Inherited, see "Sub-folders" in Mail::Box
271 Internals
273 Extends "Internals" in Mail::Box.
274 $obj->coerce($message, %options)
276 Inherited, see "Internals" in Mail::Box
277 $obj->create($foldername, %options)
279 Mail::Box::File->create($foldername, %options)
280 -Option --Defined in--Default
281 folderdir Mail::Box undef
282 folderdir => DIRECTORY
284 $obj->determineBodyType($message, $head)
285 Inherited, see "Internals" in Mail::Box
286 $obj->folderToFilename( $foldername, $folderdir, [$subext] )
288 Mail::Box::File->folderToFilename( $foldername, $folderdir, [$subext] )
289 Translate a folder name into a filename, using the $folderdir value
290 to replace a leading "=". $subext is only used for MBOX folders.
291 Mail::Box::File->foundIn( [$foldername], %options )
293 Inherited, see "Internals" in Mail::Box
294 $obj->lineSeparator( [<STRING|'CR'|'LF'|'CRLF'>] )
296 Inherited, see "Internals" in Mail::Box
297 $obj->locker()
299 Inherited, see "Internals" in Mail::Box
300 $obj->messageCreateOptions( [$type, $config] )
302 Returns a key-value list of options to be used each time a new
303 message is read from a file. The list is preceded by the $type of
304 message which has to be created.
305 This data is used by readMessages() and updateMessages(). With
307 $type and $config, a new configuration is set.
308 $obj->moveAwaySubFolder($directory, $extension)
310 The $directory is renamed by appending the $extension, which
311 defaults to ".d", to make place for a folder file on that specific
312 location. "false" is returned if this failed.
313 $obj->parser()
315 Create a parser for this mailbox. The parser stays alive as long
316 as the folder is open.
317 $obj->read(%options)
319 Inherited, see "Internals" in Mail::Box
320 $obj->readMessages(%options)
322 Inherited, see "Internals" in Mail::Box
323 $obj->storeMessage($message)
325 Inherited, see "Internals" in Mail::Box
326 $obj->toBeThreaded($messages)
328 Inherited, see "Internals" in Mail::Box
329 $obj->toBeUnthreaded($messages)
331 Inherited, see "Internals" in Mail::Box
332 $obj->updateMessages(%options)
334 For file based folders, the file handle stays open until the folder
335 is closed. Update is therefore rather simple: move to the end of
336 the last known message, and continue reading...
337 $obj->write(%options)
339 -Option --Defined in --Default
340 force Mail::Box <false>
341 policy undef
342 save_deleted Mail::Box <false>
343 force => BOOLEAN
345 policy => 'REPLACE'|'INPLACE'|undef
346 In what way will the mail folder be updated. If not specified
347 during the write, the value of the new(write_policy) at folder
348 creation is taken.
349 Valid values:
351 • "REPLACE"
353 First a new folder is written in the same directory as the
355 folder which has to be updated, and then a call to move will
356 throw away the old immediately replacing it by the new.
357 Writing in "REPLACE" module is slightly optimized: messages
359 which are not modified are copied from file to file, byte by
360 byte. This is much faster than printing the data which is
361 will be done for modified messages.
362 • "INPLACE"
364 The original folder file will be opened read/write. All
366 message which where not changed will be left untouched, until
367 the first deleted or modified message is detected. All
368 further messages are printed again.
369 • "undef"
371 As default, or when "undef" is explicitly specified, first
373 "REPLACE" mode is tried. Only when that fails, an "INPLACE"
374 update is performed.
375 "INPLACE" will be much faster than "REPLACE" when applied on
377 large folders, however requires the "truncate" function to be
378 implemented on your operating system (at least available for
379 recent versions of Linux, Solaris, Tru64, HPUX). It is also
380 dangerous: when the program is interrupted during the update
381 process, the folder is corrupted. Data may be lost.
382 However, in some cases it is not possible to write the folder
384 with "REPLACE". For instance, the usual incoming mail folder on
385 UNIX is stored in a directory where a user can not write. Of
386 course, the "root" and "mail" users can, but if you want to use
387 this Perl module with permission of a normal user, you can only
388 get it to work in "INPLACE" mode. Be warned that in this case
389 folder locking via a lockfile is not possible as well.
390 save_deleted => BOOLEAN
392 $obj->writeMessages(%options)
393 Inherited, see "Internals" in Mail::Box
394 Other methods
396 Extends "Other methods" in Mail::Box.
397 $obj->timespan2seconds($time)
399 Mail::Box::File->timespan2seconds($time)
400 Inherited, see "Other methods" in Mail::Box
401 Error handling
403 Extends "Error handling" in Mail::Box.
404 $obj->AUTOLOAD()
406 Inherited, see "Error handling" in Mail::Reporter
407 $obj->addReport($object)
409 Inherited, see "Error handling" in Mail::Reporter
410 $obj->defaultTrace( [$level]|[$loglevel, $tracelevel]|[$level,
412 $callback] )
413 Mail::Box::File->defaultTrace( [$level]|[$loglevel,
414 $tracelevel]|[$level, $callback] )
415 Inherited, see "Error handling" in Mail::Reporter
416 $obj->errors()
418 Inherited, see "Error handling" in Mail::Reporter
419 $obj->log( [$level, [$strings]] )
421 Mail::Box::File->log( [$level, [$strings]] )
422 Inherited, see "Error handling" in Mail::Reporter
423 $obj->logPriority($level)
425 Mail::Box::File->logPriority($level)
426 Inherited, see "Error handling" in Mail::Reporter
427 $obj->logSettings()
429 Inherited, see "Error handling" in Mail::Reporter
430 $obj->notImplemented()
432 Inherited, see "Error handling" in Mail::Reporter
433 $obj->report( [$level] )
435 Inherited, see "Error handling" in Mail::Reporter
436 $obj->reportAll( [$level] )
438 Inherited, see "Error handling" in Mail::Reporter
439 $obj->trace( [$level] )
441 Inherited, see "Error handling" in Mail::Reporter
442 $obj->warnings()
444 Inherited, see "Error handling" in Mail::Reporter
445 Cleanup
447 Extends "Cleanup" in Mail::Box.
448 $obj->DESTROY()
450 Inherited, see "Cleanup" in Mail::Box
451 DETAILS
453 File based folders
454 File based folders maintain a folder (a set of messages) in one single
456 file. The advantage is that your folder has only one single name,
457 which speeds-up access to all messages at once.
458 The disadvantage over directory based folder (see Mail::Box::Dir) is
460 that you have to construct some means to keep all message apart, for
461 instance by adding a message separator, and this will cause problems.
462 Where access to all messages at once is faster in file based folders,
463 access to a single message is (much) slower, because the whole folder
464 must be read.
465
467 Extends "DETAILS" in Mail::Box.
468
470 Error: Cannot append messages to folder file $filename: $!
471 Appending messages to a not-opened file-organized folder may fail
472 when the operating system does not allow write access to the file
473 at hand.
474 Error: Cannot create directory $dir for folder $name.
476 While creating a file-organized folder, at most one level of
477 directories is created above it. Apparently, more levels of
478 directories are needed, or the operating system does not allow you
479 to create the directory.
480 Error: Cannot create folder file $name: $!
482 The file-organized folder file cannot be created for the indicated
483 reason. In common cases, the operating system does not grant you
484 write access to the directory where the folder file should be
485 stored.
486 Error: Cannot get a lock on $type folder $self.
488 A lock is required to get access to the folder. If no locking is
489 needed, specify the NONE lock type.
490 Error: Cannot move away sub-folder $dir
492 Warning: Cannot remove folder $name file $filename: $!
493 Writing an empty folder will usually cause that folder to be
494 removed, which fails for the indicated reason.
495 new(remove_when_empty)
496 Warning: Cannot remove folder $name file $filename: $!
498 Writing an empty folder will usually cause that folder to be
499 removed, which fails for the indicated reason.
500 new(remove_when_empty) controls whether the empty folder will
501 removed; setting it to false (0) may be needed to avoid this
502 message.
503 Error: Cannot replace $filename by $tempname, to update folder $name:
505 $!
506 The replace policy wrote a new folder file to update the existing,
507 but was unable to give the final touch: replacing the old version
508 of the folder file for the indicated reason.
509 Warning: Changes not written to read-only folder $self.
511 You have opened the folder read-only --which is the default set by
512 new(access)--, made modifications, and now want to close it. Set
513 close(force) if you want to overrule the access mode, or close the
514 folder with close(write) set to "NEVER".
515 Error: Copying failed for one message.
517 For some reason, for instance disc full, removed by external
518 process, or read-protection, it is impossible to copy one of the
519 messages. Copying will proceed for the other messages.
520 Error: Destination folder $name is not writable.
522 The folder where the messages are copied to is not opened with
523 write access (see new(access)). This has no relation with write
524 permission to the folder which is controlled by your operating
525 system.
526 Warning: Different messages with id $msgid
528 The message id is discovered more than once within the same folder,
529 but the content of the message seems to be different. This should
530 not be possible: each message must be unique.
531 Error: File too short to get write message $nr ($size, $need)
533 Mail::Box is lazy: it tries to leave messages in the folders until
534 they are used, which saves time and memory usage. When this
535 message appears, something is terribly wrong: some lazy message are
536 needed for updating the folder, but they cannot be retrieved from
537 the original file anymore. In this case, messages can be lost.
538 This message does appear regularly on Windows systems when using
540 the 'replace' write policy. Please help to find the cause,
541 probably something to do with Windows incorrectly handling multiple
542 filehandles open in the same file.
543 Warning: Folder $name file $filename is write-protected.
545 The folder is opened writable or for appending via new(access), but
546 the operating system does not permit writing to the file. The
547 folder will be opened read-only.
548 Error: Folder $name not deleted: not writable.
550 The folder must be opened with write access via new(access),
551 otherwise removing it will be refused. So, you may have write-
552 access according to the operating system, but that will not
553 automatically mean that this "delete" method permits you to. The
554 reverse remark is valid as well.
555 Error: Invalid timespan '$timespan' specified.
557 The string does not follow the strict rules of the time span syntax
558 which is permitted as parameter.
559 Warning: Message-id '$msgid' does not contain a domain.
561 According to the RFCs, message-ids need to contain a unique random
562 part, then an "@", and then a domain name. This is made to avoid
563 the creation of two messages with the same id. The warning emerges
564 when the "@" is missing from the string.
565 Error: Package $package does not implement $method.
567 Fatal error: the specific package (or one of its superclasses) does
568 not implement this method where it should. This message means that
569 some other related classes do implement this method however the
570 class at hand does not. Probably you should investigate this and
571 probably inform the author of the package.
572 Error: Unable to create subfolder $name of $folder.
574 The copy includes the subfolders, but for some reason it was not
575 possible to copy one of these. Copying will proceed for all other
576 sub-folders.
577 Error: Unable to update folder $self.
579 When a folder is to be written, both replace and inplace write
580 policies are tried, If both fail, the whole update fails. You may
581 see other, related, error messages to indicate the real problem.
582
584 This module is part of Mail-Box distribution version 3.009, built on
585 August 18, 2020. Website: http://perl.overmeer.net/CPAN/
586
588 Copyrights 2001-2020 by [Mark Overmeer]. For other contributors see
589 ChangeLog.
590 This program is free software; you can redistribute it and/or modify it
592 under the same terms as Perl itself. See http://dev.perl.org/licenses/
593perl v5.36.0 2023-01-20 Mail::Box::File(3)