1Mail::Box::Maildir(3) User Contributed Perl DocumentationMail::Box::Maildir(3)
2
6 Mail::Box::Maildir - handle Maildir folders
7
9 Mail::Box::Maildir
10 is a Mail::Box::Dir
11 is a Mail::Box
12 is a Mail::Reporter
13
15 use Mail::Box::Maildir;
16 my $folder = new Mail::Box::Maildir folder => $ENV{MAIL}, ...;
17
19 This documentation describes how Maildir mailboxes work, and what you
20 can do with the Maildir folder object "Mail::Box::Maildir".
21 Maildir is not supported for Windows, because it create filenames which
23 are not accepted by the Windows system.
24 Extends "DESCRIPTION" in Mail::Box::Dir.
26
28 Extends "OVERLOADED" in Mail::Box::Dir.
29 overload: ""
31 Inherited, see "OVERLOADED" in Mail::Box
32 overload: @{}
34 Inherited, see "OVERLOADED" in Mail::Box
35 overload: cmp
37 Inherited, see "OVERLOADED" in Mail::Box
38
40 Extends "METHODS" in Mail::Box::Dir.
41 Constructors
43 Extends "Constructors" in Mail::Box::Dir.
44 Mail::Box::Maildir->new(%options)
46 -Option --Defined in --Default
47 accept_new <false>
48 access Mail::Box 'r'
49 body_delayed_type Mail::Box Mail::Message::Body::Delayed
50 body_type Mail::Box Mail::Message::Body::Lines
51 coerce_options Mail::Box []
52 create Mail::Box <false>
53 directory Mail::Box::Dir <derived from folder name>
54 extract Mail::Box 10240
55 field_type Mail::Box undef
56 fix_headers Mail::Box <false>
57 folder Mail::Box $ENV{MAIL}
58 folderdir Mail::Box $ENV{HOME}/.maildir
59 head_delayed_type Mail::Box Mail::Message::Head::Delayed
60 head_type Mail::Box Mail::Message::Head::Complete
61 keep_dups Mail::Box <false>
62 lock_file Mail::Box <not used>
63 lock_timeout Mail::Box <not used>
64 lock_type Mail::Box 'NONE' (constant)
65 lock_wait Mail::Box <not used>
66 locker Mail::Box undef
67 log Mail::Reporter 'WARNINGS'
68 manager Mail::Box undef
69 message_type Mail::Box <folder-class>::Message
70 multipart_type Mail::Box Mail::Message::Body::Multipart
71 remove_when_empty Mail::Box <true>
72 save_on_exit Mail::Box <true>
73 trace Mail::Reporter 'WARNINGS'
74 trusted Mail::Box <depends on folder location>
75 accept_new => BOOLEAN
77 When the folder is open, some messages may be stored in the "new"
78 sub-directory. By default, these messages are immediately moved
79 to the "cur" directory when the folder is opened. Otherwise, you
80 have to call acceptMessages() or
81 Mail::Box::Maildir::Message::accept().
82 access => MODE
84 body_delayed_type => CLASS
85 body_type => CLASS|CODE
86 coerce_options => ARRAY
87 create => BOOLEAN
88 directory => DIRECTORY
89 extract => INTEGER | CODE | METHOD | 'LAZY'|'ALWAYS'
90 field_type => CLASS
91 fix_headers => BOOLEAN
92 folder => FOLDERNAME
93 folderdir => DIRECTORY
94 head_delayed_type => CLASS
95 head_type => CLASS
96 keep_dups => BOOLEAN
97 lock_file => FILENAME
98 lock_timeout => SECONDS
99 lock_type => CLASS|STRING|ARRAY
100 lock_wait => SECONDS
101 locker => OBJECT
102 log => LEVEL
103 manager => MANAGER
104 message_type => CLASS
105 multipart_type => CLASS
106 remove_when_empty => BOOLEAN
107 save_on_exit => BOOLEAN
108 trace => LEVEL
109 trusted => BOOLEAN
110 The folder
112 Extends "The folder" in Mail::Box::Dir.
113 $obj->addMessage($message, %options)
115 Inherited, see "The folder" in Mail::Box
116 $obj->addMessages(@messages)
118 Inherited, see "The folder" in Mail::Box
119 Mail::Box::Maildir->appendMessages(%options)
121 Inherited, see "The folder" in Mail::Box
122 $obj->close(%options)
124 Inherited, see "The folder" in Mail::Box
125 $obj->copyTo($folder, %options)
127 Inherited, see "The folder" in Mail::Box
128 $obj->delete(%options)
130 Inherited, see "The folder" in Mail::Box
131 $obj->directory()
133 Inherited, see "The folder" in Mail::Box::Dir
134 $obj->folderdir( [$directory] )
136 Inherited, see "The folder" in Mail::Box
137 $obj->name()
139 Inherited, see "The folder" in Mail::Box
140 $obj->organization()
142 Inherited, see "The folder" in Mail::Box
143 $obj->size()
145 Inherited, see "The folder" in Mail::Box
146 $obj->type()
148 Inherited, see "The folder" in Mail::Box
149 $obj->update(%options)
151 Inherited, see "The folder" in Mail::Box
152 $obj->url()
154 Inherited, see "The folder" in Mail::Box
155 Folder flags
157 Extends "Folder flags" in Mail::Box::Dir.
158 $obj->access()
160 Inherited, see "Folder flags" in Mail::Box
161 $obj->isModified()
163 Inherited, see "Folder flags" in Mail::Box
164 $obj->modified( [BOOLEAN] )
166 Inherited, see "Folder flags" in Mail::Box
167 $obj->writable()
169 Inherited, see "Folder flags" in Mail::Box
170 The messages
172 Extends "The messages" in Mail::Box::Dir.
173 $obj->current( [$number|$message|$message_id] )
175 Inherited, see "The messages" in Mail::Box
176 $obj->find($message_id)
178 Inherited, see "The messages" in Mail::Box
179 $obj->findFirstLabeled( $label, [BOOLEAN, [$msgs]] )
181 Inherited, see "The messages" in Mail::Box
182 $obj->message( $index, [$message] )
184 Inherited, see "The messages" in Mail::Box
185 $obj->messageId( $message_id, [$message] )
187 Inherited, see "The messages" in Mail::Box
188 $obj->messageIds()
190 Inherited, see "The messages" in Mail::Box
191 $obj->messages( <'ALL'|$range|'ACTIVE'|'DELETED'|$label|
193 !$label|$filter> )
194 Inherited, see "The messages" in Mail::Box
195 $obj->nrMessages(%options)
197 Inherited, see "The messages" in Mail::Box
198 $obj->scanForMessages($message, $message_ids, $timespan, $window)
200 Inherited, see "The messages" in Mail::Box
201 Sub-folders
203 Extends "Sub-folders" in Mail::Box::Dir.
204 $obj->listSubFolders(%options)
206 Mail::Box::Maildir->listSubFolders(%options)
207 Inherited, see "Sub-folders" in Mail::Box
208 $obj->nameOfSubFolder( $subname, [$parentname] )
210 Mail::Box::Maildir->nameOfSubFolder( $subname, [$parentname] )
211 Inherited, see "Sub-folders" in Mail::Box
212 $obj->openRelatedFolder(%options)
214 Inherited, see "Sub-folders" in Mail::Box
215 $obj->openSubFolder($subname, %options)
217 Inherited, see "Sub-folders" in Mail::Box
218 $obj->topFolderWithMessages()
220 Mail::Box::Maildir->topFolderWithMessages()
221 Inherited, see "Sub-folders" in Mail::Box
222 Internals
224 Extends "Internals" in Mail::Box::Dir.
225 $obj->acceptMessages()
227 Accept all messages which are waiting in the "new" directory to be
228 moved to the "cur" directory. This will not rescan the directory
229 for newly arrived messages, because that's a task for update().
230 Mail::Box::Maildir->appendMessage(%options)
232 $obj->coerce($message, %options)
233 $obj->create($foldername, %options)
234 Mail::Box::Maildir->create($foldername, %options)
235 -Option --Defined in--Default
236 folderdir Mail::Box undef
237 folderdir => DIRECTORY
239 $obj->createDirs($folderdir)
240 Mail::Box::Maildir->createDirs($folderdir)
241 The $folderdir contains the absolute path of the location where the
242 messages are kept. Maildir folders contain a "tmp", "new", and
243 "cur" sub-directory within that folder directory as well. This
244 method will ensure that all directories exist. Returns false on
245 failure.
246 $obj->determineBodyType($message, $head)
248 Inherited, see "Internals" in Mail::Box
249 $obj->folderIsEmpty($folderdir)
251 Mail::Box::Maildir->folderIsEmpty($folderdir)
252 Checks whether the folder whose directory is specified as absolute
253 $folderdir is empty or not. A folder is empty when the "tmp",
254 "new", and "cur" subdirectories are empty and some files which are
255 left there by application programs. The maildir spec explicitly
256 states: ".qmail", "bulletintime", "bulletinlock" and "seriallock".
257 If any other files are found, the directory is considered not-
258 empty.
259 $obj->folderToDirectory($foldername, $folderdir)
261 Inherited, see "Internals" in Mail::Box::Dir
262 Mail::Box::Maildir->foundIn( [$foldername], %options )
264 Inherited, see "Internals" in Mail::Box
265 $obj->lineSeparator( [<STRING|'CR'|'LF'|'CRLF'>] )
267 Inherited, see "Internals" in Mail::Box
268 $obj->locker()
270 Inherited, see "Internals" in Mail::Box
271 $obj->read(%options)
273 Inherited, see "Internals" in Mail::Box
274 $obj->readMessageFilenames($directory)
276 Inherited, see "Internals" in Mail::Box::Dir
277 $obj->readMessages(%options)
279 Inherited, see "Internals" in Mail::Box
280 $obj->storeMessage($message)
282 Inherited, see "Internals" in Mail::Box
283 $obj->toBeThreaded($messages)
285 Inherited, see "Internals" in Mail::Box
286 $obj->toBeUnthreaded($messages)
288 Inherited, see "Internals" in Mail::Box
289 $obj->updateMessages(%options)
291 Inherited, see "Internals" in Mail::Box
292 $obj->write(%options)
294 Inherited, see "Internals" in Mail::Box
295 $obj->writeMessages(%options)
297 Inherited, see "Internals" in Mail::Box
298 Other methods
300 Extends "Other methods" in Mail::Box::Dir.
301 $obj->timespan2seconds($time)
303 Mail::Box::Maildir->timespan2seconds($time)
304 Inherited, see "Other methods" in Mail::Box
305 Error handling
307 Extends "Error handling" in Mail::Box::Dir.
308 $obj->AUTOLOAD()
310 Inherited, see "Error handling" in Mail::Reporter
311 $obj->addReport($object)
313 Inherited, see "Error handling" in Mail::Reporter
314 $obj->defaultTrace( [$level]|[$loglevel, $tracelevel]|[$level,
316 $callback] )
317 Mail::Box::Maildir->defaultTrace( [$level]|[$loglevel,
318 $tracelevel]|[$level, $callback] )
319 Inherited, see "Error handling" in Mail::Reporter
320 $obj->errors()
322 Inherited, see "Error handling" in Mail::Reporter
323 $obj->log( [$level, [$strings]] )
325 Mail::Box::Maildir->log( [$level, [$strings]] )
326 Inherited, see "Error handling" in Mail::Reporter
327 $obj->logPriority($level)
329 Mail::Box::Maildir->logPriority($level)
330 Inherited, see "Error handling" in Mail::Reporter
331 $obj->logSettings()
333 Inherited, see "Error handling" in Mail::Reporter
334 $obj->notImplemented()
336 Inherited, see "Error handling" in Mail::Reporter
337 $obj->report( [$level] )
339 Inherited, see "Error handling" in Mail::Reporter
340 $obj->reportAll( [$level] )
342 Inherited, see "Error handling" in Mail::Reporter
343 $obj->trace( [$level] )
345 Inherited, see "Error handling" in Mail::Reporter
346 $obj->warnings()
348 Inherited, see "Error handling" in Mail::Reporter
349 Cleanup
351 Extends "Cleanup" in Mail::Box::Dir.
352 $obj->DESTROY()
354 Inherited, see "Cleanup" in Mail::Box
355
357 The explanation is complicated, but for normal use you should bother
358 yourself with all details.
359 Extends "DETAILS" in Mail::Box::Dir.
361 Different kinds of folders
363 Extends "Different kinds of folders" in Mail::Box::Dir.
364 Available folder types
366 Extends "Available folder types" in Mail::Box::Dir.
367 Folder class implementation
369 Extends "Folder class implementation" in Mail::Box::Dir.
370 How MAILDIR folders work
372 Maildir-type folders use a directory to store the messages of one
373 folder. Each message is stored in a separate file. This seems useful,
374 because changes in a folder change only a few of these small files, in
375 contrast with file-based folders where changes in a folder cause
376 rewrites of huge folder-files.
377 However, Maildir based folders perform very bad if you need header
379 information of all messages. For instance, if you want to have full
380 knowledge about all message-threads (see Mail::Box::Thread::Manager) in
381 the folder, it requires to read all header lines in all message files.
382 And usually, reading your messages as threads is desired. Maildir
383 maintains a tiny amount of info visible in the filename, which may make
384 it perform just a little bit faster than MH.
385
387 Error: Cannot append Maildir message in $new to folder $self.
388 The message (or messages) could not be stored in the right
389 directories for the Maildir folder.
390 Error: Cannot create Maildir directory $dir: $!
392 A Maildir folder is represented by a directory, with some sub-
393 directories. The top folder directory could not be created for the
394 reason indicated.
395 Error: Cannot create Maildir folder $name.
397 One or more of the directories required to administer a Maildir
398 folder could not be created.
399 Error: Cannot create Maildir message file $new.
401 A message is converted from some other message format into a
402 Maildir format by writing it to a file with a name which contains
403 the status flags of the message. Apparently, creating this file
404 failed.
405 Error: Cannot create Maildir subdir $dir: $!
407 Each Maildir folder has three sub-directories for administration:
408 "new", "tmp", and "cur". The mentioned directory could not be
409 created for the indicated reason.
410 Warning: Changes not written to read-only folder $self.
412 You have opened the folder read-only --which is the default set by
413 new(access)--, made modifications, and now want to close it. Set
414 close(force) if you want to overrule the access mode, or close the
415 folder with close(write) set to "NEVER".
416 Error: Copying failed for one message.
418 For some reason, for instance disc full, removed by external
419 process, or read-protection, it is impossible to copy one of the
420 messages. Copying will proceed for the other messages.
421 Error: Destination folder $name is not writable.
423 The folder where the messages are copied to is not opened with
424 write access (see new(access)). This has no relation with write
425 permission to the folder which is controlled by your operating
426 system.
427 Warning: Different messages with id $msgid
429 The message id is discovered more than once within the same folder,
430 but the content of the message seems to be different. This should
431 not be possible: each message must be unique.
432 Error: Folder $name is opened read-only
434 You can not write to this folder unless you have opened the folder
435 to write or append with new(access), or the "force" option is set
436 true.
437 Error: Folder $name not deleted: not writable.
439 The folder must be opened with write access via new(access),
440 otherwise removing it will be refused. So, you may have write-
441 access according to the operating system, but that will not
442 automatically mean that this "delete" method permits you to. The
443 reverse remark is valid as well.
444 Error: Invalid timespan '$timespan' specified.
446 The string does not follow the strict rules of the time span syntax
447 which is permitted as parameter.
448 Warning: Message-id '$msgid' does not contain a domain.
450 According to the RFCs, message-ids need to contain a unique random
451 part, then an "@", and then a domain name. This is made to avoid
452 the creation of two messages with the same id. The warning emerges
453 when the "@" is missing from the string.
454 Error: Package $package does not implement $method.
456 Fatal error: the specific package (or one of its superclasses) does
457 not implement this method where it should. This message means that
458 some other related classes do implement this method however the
459 class at hand does not. Probably you should investigate this and
460 probably inform the author of the package.
461 Error: Unable to create subfolder $name of $folder.
463 The copy includes the subfolders, but for some reason it was not
464 possible to copy one of these. Copying will proceed for all other
465 sub-folders.
466 Error: Writing folder $name failed
468 For some reason (you probably got more error messages about this
469 problem) it is impossible to write the folder, although you should
470 because there were changes made.
471
473 This module is part of Mail-Box distribution version 3.008, built on
474 October 04, 2019. Website: http://perl.overmeer.net/CPAN/
475
477 Copyrights 2001-2019 by [Mark Overmeer]. For other contributors see
478 ChangeLog.
479 This program is free software; you can redistribute it and/or modify it
481 under the same terms as Perl itself. See http://dev.perl.org/licenses/
482perl v5.30.1 2020-01-30 Mail::Box::Maildir(3)