1Mail::Box::File(3)    User Contributed Perl Documentation   Mail::Box::File(3)
2
3
4

NAME

6       Mail::Box::File - handle file-based folders
7

INHERITANCE

9        Mail::Box::File
10          is a Mail::Box
11          is a Mail::Reporter
12
13        Mail::Box::File is extended by
14          Mail::Box::Dbx
15          Mail::Box::Mbox
16

SYNOPSIS

DESCRIPTION

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
24       Extends "DESCRIPTION" in Mail::Box.
25

OVERLOADED

27       Extends "OVERLOADED" in Mail::Box.
28
29       overload: ""
30           Inherited, see "OVERLOADED" in Mail::Box
31
32       overload: @{}
33           Inherited, see "OVERLOADED" in Mail::Box
34
35       overload: cmp
36           Inherited, see "OVERLOADED" in Mail::Box
37

METHODS

39       Extends "METHODS" in Mail::Box.
40
41   Constructors
42       Extends "Constructors" in Mail::Box.
43
44       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
75           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
82              sub determine_body_type($$)
83              {   my $head = shift;
84                  my $size = shift || 0;
85                  'Mail::Message::Body::'
86                     . ($size > 10000 ? 'File' : 'Lines');
87              }
88
89           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
106             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
110              .lock        # appended to the folder's filename
111              my_own_lockfile.test   # full filename, same dir
112              /etc/passwd            # somewhere else
113
114             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
118           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
135   The folder
136       Extends "The folder" in Mail::Box.
137
138       $obj->addMessage($message, %options)
139           Inherited, see "The folder" in Mail::Box
140
141       $obj->addMessages(@messages)
142           Inherited, see "The folder" in Mail::Box
143
144       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
151           All %options of Mail::Box::Mbox::new() can be supplied.
152
153            -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
160           folder => FOLDERNAME
161           lock_type => ...
162             See Mail::Box::new(lock_type) for possible values.
163
164           message => MESSAGE
165           messages => ARRAY-OF-MESSAGES
166           share => BOOLEAN
167       $obj->close(%options)
168           Inherited, see "The folder" in Mail::Box
169
170       $obj->copyTo($folder, %options)
171           Inherited, see "The folder" in Mail::Box
172
173       $obj->delete(%options)
174           Inherited, see "The folder" in Mail::Box
175
176       $obj->filename()
177           Returns the filename for this folder, which may be an absolute or
178           relative path to the file.
179
180           example:
181
182            print $folder->filename;
183
184       $obj->folderdir( [$directory] )
185           Inherited, see "The folder" in Mail::Box
186
187       $obj->name()
188           Inherited, see "The folder" in Mail::Box
189
190       $obj->organization()
191           Inherited, see "The folder" in Mail::Box
192
193       $obj->size()
194           Inherited, see "The folder" in Mail::Box
195
196       $obj->type()
197           Inherited, see "The folder" in Mail::Box
198
199       $obj->update(%options)
200           Inherited, see "The folder" in Mail::Box
201
202       $obj->url()
203           Inherited, see "The folder" in Mail::Box
204
205   Folder flags
206       Extends "Folder flags" in Mail::Box.
207
208       $obj->access()
209           Inherited, see "Folder flags" in Mail::Box
210
211       $obj->isModified()
212           Inherited, see "Folder flags" in Mail::Box
213
214       $obj->modified( [BOOLEAN] )
215           Inherited, see "Folder flags" in Mail::Box
216
217       $obj->writable()
218           Inherited, see "Folder flags" in Mail::Box
219
220   The messages
221       Extends "The messages" in Mail::Box.
222
223       $obj->current( [$number|$message|$message_id] )
224           Inherited, see "The messages" in Mail::Box
225
226       $obj->find($message_id)
227           Inherited, see "The messages" in Mail::Box
228
229       $obj->findFirstLabeled( $label, [BOOLEAN, [$msgs]] )
230           Inherited, see "The messages" in Mail::Box
231
232       $obj->message( $index, [$message] )
233           Inherited, see "The messages" in Mail::Box
234
235       $obj->messageId( $message_id, [$message] )
236           Inherited, see "The messages" in Mail::Box
237
238       $obj->messageIds()
239           Inherited, see "The messages" in Mail::Box
240
241       $obj->messages( <'ALL'|$range|'ACTIVE'|'DELETED'|$label|
242       !$label|$filter> )
243           Inherited, see "The messages" in Mail::Box
244
245       $obj->nrMessages(%options)
246           Inherited, see "The messages" in Mail::Box
247
248       $obj->scanForMessages($message, $message_ids, $timespan, $window)
249           Inherited, see "The messages" in Mail::Box
250
251   Sub-folders
252       Extends "Sub-folders" in Mail::Box.
253
254       $obj->listSubFolders(%options)
255       Mail::Box::File->listSubFolders(%options)
256           Inherited, see "Sub-folders" in Mail::Box
257
258       $obj->nameOfSubFolder( $subname, [$parentname] )
259       Mail::Box::File->nameOfSubFolder( $subname, [$parentname] )
260           Inherited, see "Sub-folders" in Mail::Box
261
262       $obj->openRelatedFolder(%options)
263           Inherited, see "Sub-folders" in Mail::Box
264
265       $obj->openSubFolder($subname, %options)
266           Inherited, see "Sub-folders" in Mail::Box
267
268       $obj->topFolderWithMessages()
269       Mail::Box::File->topFolderWithMessages()
270           Inherited, see "Sub-folders" in Mail::Box
271
272   Internals
273       Extends "Internals" in Mail::Box.
274
275       $obj->coerce($message, %options)
276           Inherited, see "Internals" in Mail::Box
277
278       $obj->create($foldername, %options)
279       Mail::Box::File->create($foldername, %options)
280            -Option   --Defined in--Default
281             folderdir  Mail::Box   undef
282
283           folderdir => DIRECTORY
284       $obj->determineBodyType($message, $head)
285           Inherited, see "Internals" in Mail::Box
286
287       $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
292       Mail::Box::File->foundIn( [$foldername], %options )
293           Inherited, see "Internals" in Mail::Box
294
295       $obj->lineSeparator( [<STRING|'CR'|'LF'|'CRLF'>] )
296           Inherited, see "Internals" in Mail::Box
297
298       $obj->locker()
299           Inherited, see "Internals" in Mail::Box
300
301       $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
306           This data is used by readMessages() and updateMessages().  With
307           $type and $config, a new configuration is set.
308
309       $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
314       $obj->parser()
315           Create a parser for this mailbox.  The parser stays alive as long
316           as the folder is open.
317
318       $obj->read(%options)
319           Inherited, see "Internals" in Mail::Box
320
321       $obj->readMessages(%options)
322           Inherited, see "Internals" in Mail::Box
323
324       $obj->storeMessage($message)
325           Inherited, see "Internals" in Mail::Box
326
327       $obj->toBeThreaded($messages)
328           Inherited, see "Internals" in Mail::Box
329
330       $obj->toBeUnthreaded($messages)
331           Inherited, see "Internals" in Mail::Box
332
333       $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
338       $obj->write(%options)
339            -Option      --Defined in     --Default
340             force         Mail::Box        <false>
341             policy                         undef
342             save_deleted  Mail::Box        <false>
343
344           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
350             Valid values:
351
352             •   "REPLACE"
353
354                 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
358                 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
363             •   "INPLACE"
364
365                 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
370             •   "undef"
371
372                 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
376             "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
383             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
391           save_deleted => BOOLEAN
392       $obj->writeMessages(%options)
393           Inherited, see "Internals" in Mail::Box
394
395   Other methods
396       Extends "Other methods" in Mail::Box.
397
398       $obj->timespan2seconds($time)
399       Mail::Box::File->timespan2seconds($time)
400           Inherited, see "Other methods" in Mail::Box
401
402   Error handling
403       Extends "Error handling" in Mail::Box.
404
405       $obj->AUTOLOAD()
406           Inherited, see "Error handling" in Mail::Reporter
407
408       $obj->addReport($object)
409           Inherited, see "Error handling" in Mail::Reporter
410
411       $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
417       $obj->errors()
418           Inherited, see "Error handling" in Mail::Reporter
419
420       $obj->log( [$level, [$strings]] )
421       Mail::Box::File->log( [$level, [$strings]] )
422           Inherited, see "Error handling" in Mail::Reporter
423
424       $obj->logPriority($level)
425       Mail::Box::File->logPriority($level)
426           Inherited, see "Error handling" in Mail::Reporter
427
428       $obj->logSettings()
429           Inherited, see "Error handling" in Mail::Reporter
430
431       $obj->notImplemented()
432           Inherited, see "Error handling" in Mail::Reporter
433
434       $obj->report( [$level] )
435           Inherited, see "Error handling" in Mail::Reporter
436
437       $obj->reportAll( [$level] )
438           Inherited, see "Error handling" in Mail::Reporter
439
440       $obj->trace( [$level] )
441           Inherited, see "Error handling" in Mail::Reporter
442
443       $obj->warnings()
444           Inherited, see "Error handling" in Mail::Reporter
445
446   Cleanup
447       Extends "Cleanup" in Mail::Box.
448
449       $obj->DESTROY()
450           Inherited, see "Cleanup" in Mail::Box
451
452   DETAILS
453       File based folders
454
455       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
459       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

DETAILS

467       Extends "DETAILS" in Mail::Box.
468

DIAGNOSTICS

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
475       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
481       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
487       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
491       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
497       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
504       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
510       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
516       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
521       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
527       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
532       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
539           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
544       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
549       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
556       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
560       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
566       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
573       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
578       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

SEE ALSO

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

LICENSE

588       Copyrights 2001-2020 by [Mark Overmeer]. For other contributors see
589       ChangeLog.
590
591       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/
593
594
595
596perl v5.36.0                      2023-01-20                Mail::Box::File(3)
Impressum