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
26 overload: ""
27 See "OVERLOADED" in Mail::Box
28 overload: @{}
30 See "OVERLOADED" in Mail::Box
31 overload: cmp
33 See "OVERLOADED" in Mail::Box
34
36 Constructors
37 Mail::Box::Maildir->new(OPTIONS)
38 -Option --Defined in --Default
39 accept_new <false>
40 access Mail::Box 'r'
41 body_delayed_type Mail::Box Mail::Message::Body::Delayed
42 body_type Mail::Box Mail::Message::Body::Lines
43 coerce_options Mail::Box []
44 create Mail::Box <false>
45 directory Mail::Box::Dir <derived from folder name>
46 extract Mail::Box 10240
47 field_type Mail::Box undef
48 fix_headers Mail::Box <false>
49 folder Mail::Box $ENV{MAIL}
50 folderdir Mail::Box $ENV{HOME}/.maildir
51 head_delayed_type Mail::Box Mail::Message::Head::Delayed
52 head_type Mail::Box Mail::Message::Head::Complete
53 keep_dups Mail::Box <false>
54 lock_file Mail::Box <not used>
55 lock_timeout Mail::Box <not used>
56 lock_type Mail::Box 'NONE' (constant)
57 lock_wait Mail::Box <not used>
58 locker Mail::Box undef
59 log Mail::Reporter 'WARNINGS'
60 manager Mail::Box undef
61 message_type Mail::Box Mail::Box::Message
62 multipart_type Mail::Box Mail::Message::Body::Multipart
63 remove_when_empty Mail::Box <true>
64 save_on_exit Mail::Box <true>
65 trace Mail::Reporter 'WARNINGS'
66 trusted Mail::Box <depends on folder location>
67 accept_new => BOOLEAN
69 When the folder is open, some messages may be stored in the "new"
70 sub-directory. By default, these messages are immediately moved
71 to the "cur" directory when the folder is opened. Otherwise, you
72 have to call acceptMessages() or
73 Mail::Box::Maildir::Message::accept().
74 access => MODE
76 body_delayed_type => CLASS
77 body_type => CLASS|CODE
78 coerce_options => ARRAY
79 create => BOOLEAN
80 directory => DIRECTORY
81 extract => INTEGER | CODE | METHOD | 'LAZY'|'ALWAYS'
82 field_type => CLASS
83 fix_headers => BOOLEAN
84 folder => FOLDERNAME
85 folderdir => DIRECTORY
86 head_delayed_type => CLASS
87 head_type => CLASS
88 keep_dups => BOOLEAN
89 lock_file => FILENAME
90 lock_timeout => SECONDS
91 lock_type => CLASS|STRING|ARRAY
92 lock_wait => SECONDS
93 locker => OBJECT
94 log => LEVEL
95 manager => MANAGER
96 message_type => CLASS
97 multipart_type => CLASS
98 remove_when_empty => BOOLEAN
99 save_on_exit => BOOLEAN
100 trace => LEVEL
101 trusted => BOOLEAN
102 The folder
104 $obj->addMessage(MESSAGE, OPTIONS)
105 See "The folder" in Mail::Box
106 $obj->addMessages(MESSAGE [, MESSAGE, ...])
108 See "The folder" in Mail::Box
109 Mail::Box::Maildir->appendMessages(OPTIONS)
111 See "The folder" in Mail::Box
112 $obj->close(OPTIONS)
114 See "The folder" in Mail::Box
115 $obj->copyTo(FOLDER, OPTIONS)
117 See "The folder" in Mail::Box
118 $obj->delete(OPTIONS)
120 See "The folder" in Mail::Box
121 $obj->directory
123 See "The folder" in Mail::Box::Dir
124 $obj->folderdir([DIRECTORY])
126 See "The folder" in Mail::Box
127 $obj->name
129 See "The folder" in Mail::Box
130 $obj->organization
132 See "The folder" in Mail::Box
133 $obj->size
135 See "The folder" in Mail::Box
136 $obj->type
138 See "The folder" in Mail::Box
139 $obj->update(OPTIONS)
141 See "The folder" in Mail::Box
142 $obj->url
144 See "The folder" in Mail::Box
145 Folder flags
147 $obj->access
148 See "Folder flags" in Mail::Box
149 $obj->isModified
151 See "Folder flags" in Mail::Box
152 $obj->modified([BOOLEAN])
154 See "Folder flags" in Mail::Box
155 $obj->writable
157 See "Folder flags" in Mail::Box
158 The messages
160 $obj->current([NUMBER|MESSAGE|MESSAGE-ID])
161 See "The messages" in Mail::Box
162 $obj->find(MESSAGE-ID)
164 See "The messages" in Mail::Box
165 $obj->findFirstLabeled(LABEL, [BOOLEAN, [ARRAY-OF-MSGS]])
167 See "The messages" in Mail::Box
168 $obj->message(INDEX [,MESSAGE])
170 See "The messages" in Mail::Box
171 $obj->messageId(MESSAGE-ID [,MESSAGE])
173 See "The messages" in Mail::Box
174 $obj->messageIds
176 See "The messages" in Mail::Box
177 $obj->messages(['ALL',RANGE,'ACTIVE','DELETED',LABEL,!LABEL,FILTER])
179 See "The messages" in Mail::Box
180 $obj->nrMessages(OPTIONS)
182 See "The messages" in Mail::Box
183 $obj->scanForMessages(MESSAGE, MESSAGE-IDS, TIMESPAN, WINDOW)
185 See "The messages" in Mail::Box
186 Sub-folders
188 $obj->listSubFolders(OPTIONS)
189 Mail::Box::Maildir->listSubFolders(OPTIONS)
190 See "Sub-folders" in Mail::Box
192 $obj->nameOfSubFolder(SUBNAME, [PARENTNAME])
194 Mail::Box::Maildir->nameOfSubFolder(SUBNAME, [PARENTNAME])
195 See "Sub-folders" in Mail::Box
197 $obj->openRelatedFolder(OPTIONS)
199 See "Sub-folders" in Mail::Box
200 $obj->openSubFolder(SUBNAME, OPTIONS)
202 See "Sub-folders" in Mail::Box
203 $obj->topFolderWithMessages
205 Mail::Box::Maildir->topFolderWithMessages
206 See "Sub-folders" in Mail::Box
208 Internals
210 $obj->acceptMessages
211 Accept all messages which are waiting in the "new" directory to be
212 moved to the "cur" directory. This will not rescan the directory
213 for newly arrived messages, because that's a task for update().
214 Mail::Box::Maildir->appendMessage(OPTIONS)
216 $obj->coerce(MESSAGE, OPTIONS)
217 $obj->create(FOLDERNAME, OPTIONS)
218 Mail::Box::Maildir->create(FOLDERNAME, OPTIONS)
219 -Option --Defined in--Default
221 folderdir Mail::Box undef
222 folderdir => DIRECTORY
224 $obj->createDirs(FOLDERDIR)
225 Mail::Box::Maildir->createDirs(FOLDERDIR)
226 The FOLDERDIR contains the absolute path of the location where the
228 messages are kept. Maildir folders contain a "tmp", "new", and
229 "cur" sub-directory within that folder directory as well. This
230 method will ensure that all directories exist. Returns false on
231 failure.
232 $obj->determineBodyType(MESSAGE, HEAD)
234 See "Internals" in Mail::Box
235 $obj->folderIsEmpty(FOLDERDIR)
237 Mail::Box::Maildir->folderIsEmpty(FOLDERDIR)
238 Checks whether the folder whose directory is specified as absolute
240 FOLDERDIR is empty or not. A folder is empty when the "tmp",
241 "new", and "cur" subdirectories are empty and some files which are
242 left there by application programs. The maildir spec explicitly
243 states: ".qmail", "bulletintime", "bulletinlock" and "seriallock".
244 If any other files are found, the directory is considered not-
245 empty.
246 $obj->folderToDirectory(FOLDERNAME, FOLDERDIR)
248 See "Internals" in Mail::Box::Dir
249 Mail::Box::Maildir->foundIn([FOLDERNAME], OPTIONS)
251 See "Internals" in Mail::Box
252 $obj->lineSeparator([STRING|'CR'|'LF'|'CRLF'])
254 See "Internals" in Mail::Box
255 $obj->locker
257 See "Internals" in Mail::Box
258 $obj->read(OPTIONS)
260 See "Internals" in Mail::Box
261 $obj->readMessageFilenames(DIRECTORY)
263 See "Internals" in Mail::Box::Dir
264 $obj->readMessages(OPTIONS)
266 See "Internals" in Mail::Box
267 $obj->storeMessage(MESSAGE)
269 See "Internals" in Mail::Box
270 $obj->toBeThreaded(MESSAGES)
272 See "Internals" in Mail::Box
273 $obj->toBeUnthreaded(MESSAGES)
275 See "Internals" in Mail::Box
276 $obj->updateMessages(OPTIONS)
278 See "Internals" in Mail::Box
279 $obj->write(OPTIONS)
281 See "Internals" in Mail::Box
282 $obj->writeMessages(OPTIONS)
284 See "Internals" in Mail::Box
285 Other methods
287 $obj->timespan2seconds(TIME)
288 Mail::Box::Maildir->timespan2seconds(TIME)
289 See "Other methods" in Mail::Box
291 Error handling
293 $obj->AUTOLOAD
294 See "Error handling" in Mail::Reporter
295 $obj->addReport(OBJECT)
297 See "Error handling" in Mail::Reporter
298 $obj->defaultTrace([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL, CALLBACK])
300 Mail::Box::Maildir->defaultTrace([LEVEL]|[LOGLEVEL,
301 TRACELEVEL]|[LEVEL, CALLBACK])
302 See "Error handling" in Mail::Reporter
304 $obj->errors
306 See "Error handling" in Mail::Reporter
307 $obj->log([LEVEL [,STRINGS]])
309 Mail::Box::Maildir->log([LEVEL [,STRINGS]])
310 See "Error handling" in Mail::Reporter
312 $obj->logPriority(LEVEL)
314 Mail::Box::Maildir->logPriority(LEVEL)
315 See "Error handling" in Mail::Reporter
317 $obj->logSettings
319 See "Error handling" in Mail::Reporter
320 $obj->notImplemented
322 See "Error handling" in Mail::Reporter
323 $obj->report([LEVEL])
325 See "Error handling" in Mail::Reporter
326 $obj->reportAll([LEVEL])
328 See "Error handling" in Mail::Reporter
329 $obj->trace([LEVEL])
331 See "Error handling" in Mail::Reporter
332 $obj->warnings
334 See "Error handling" in Mail::Reporter
335 Cleanup
337 $obj->DESTROY
338 See "Cleanup" in Mail::Box
339 $obj->inGlobalDestruction
341 See "Cleanup" in Mail::Reporter
342
344 Different kinds of folders
345 Available folder types
346 Folder class implementation
347 How MAILDIR folders work
348 Maildir-type folders use a directory to store the messages of one
349 folder. Each message is stored in a separate file. This seems useful,
350 because changes in a folder change only a few of these small files, in
351 contrast with file-based folders where changes in a folder cause
352 rewrites of huge folder-files.
353 However, Maildir based folders perform very bad if you need header
355 information of all messages. For instance, if you want to have full
356 knowledge about all message-threads (see Mail::Box::Thread::Manager) in
357 the folder, it requires to read all header lines in all message files.
358 And usually, reading your messages as threads is desired. Maildir
359 maintains a tiny amount of info visible in the filename, which may make
360 it perform just a little bit faster than MH.
361 The explanation is complicated, but for normal use you should bother
363 yourself with all details.
364
366 Error: Cannot append Maildir message in $new to folder $self.
367 The message (or messages) could not be stored in the right
368 directories for the Maildir folder.
369 Error: Cannot create Maildir directory $dir: $!
371 A Maildir folder is represented by a directory, with some sub-
372 directories. The top folder directory could not be created for the
373 reason indicated.
374 Error: Cannot create Maildir folder $name.
376 One or more of the directories required to administer a Maildir
377 folder could not be created.
378 Error: Cannot create Maildir message file $new.
380 A message is converted from some other message format into a
381 Maildir format by writing it to a file with a name which contains
382 the status flags of the message. Apparently, creating this file
383 failed.
384 Error: Cannot create Maildir subdir $dir: $!
386 Each Maildir folder has three sub-directories for administration:
387 "new", "tmp", and "cur". The mentioned directory could not be
388 created for the indicated reason.
389 Warning: Changes not written to read-only folder $self.
391 You have opened the folder read-only --which is the default set by
392 new(access)--, made modifications, and now want to close it. Set
393 close(force) if you want to overrule the access mode, or close the
394 folder with close(write) set to "NEVER".
395 Error: Copying failed for one message.
397 For some reason, for instance disc full, removed by external
398 process, or read-protection, it is impossible to copy one of the
399 messages. Copying will proceed for the other messages.
400 Error: Destination folder $name is not writable.
402 The folder where the messages are copied to is not opened with
403 write access (see new(access)). This has no relation with write
404 permission to the folder which is controled by your operating
405 system.
406 Warning: Different messages with id $msgid
408 The message id is discovered more than once within the same folder,
409 but the content of the message seems to be different. This should
410 not be possible: each message must be unique.
411 Error: Folder $name is opened read-only
413 You can not write to this folder unless you have opened the folder
414 to write or append with new(access), or the "force" option is set
415 true.
416 Error: Folder $name not deleted: not writable.
418 The folder must be opened with write access via new(access),
419 otherwise removing it will be refused. So, you may have write-
420 access according to the operating system, but that will not
421 automatically mean that this "delete" method permits you to. The
422 reverse remark is valid as well.
423 Error: Invalid timespan '$timespan' specified.
425 The string does not follow the strict rules of the time span syntax
426 which is permitted as parameter.
427 Warning: Message-id '$msgid' does not contain a domain.
429 According to the RFCs, message-ids need to contain a unique random
430 part, then an "@", and then a domain name. This is made to avoid
431 the creation of two messages with the same id. The warning emerges
432 when the "@" is missing from the string.
433 Error: Package $package does not implement $method.
435 Fatal error: the specific package (or one of its superclasses) does
436 not implement this method where it should. This message means that
437 some other related classes do implement this method however the
438 class at hand does not. Probably you should investigate this and
439 probably inform the author of the package.
440 Error: Unable to create subfolder $name of $folder.
442 The copy includes the subfolders, but for some reason it was not
443 possible to copy one of these. Copying will proceed for all other
444 sub-folders.
445 Error: Writing folder $name failed
447 For some reason (you probably got more error messages about this
448 problem) it is impossible to write the folder, although you should
449 because there were changes made.
450
452 This module is part of Mail-Box distribution version 2.097, built on
453 January 26, 2011. Website: http://perl.overmeer.net/mailbox/
454
456 Copyrights 2001-2011 by Mark Overmeer. For other contributors see
457 ChangeLog.
458 This program is free software; you can redistribute it and/or modify it
460 under the same terms as Perl itself. See
461 http://www.perl.com/perl/misc/Artistic.html
462perl v5.12.3 2011-01-26 Mail::Box::Maildir(3)