Mail::Box::Maildir(3pm)

1Mail::Box::Maildir(3) User Contributed Perl DocumentationMail::Box::Maildir(3)
2
3
4

NAME

6       Mail::Box::Maildir - handle Maildir folders
7

INHERITANCE

9        Mail::Box::Maildir
10          is a Mail::Box::Dir
11          is a Mail::Box
12          is a Mail::Reporter
13

SYNOPSIS

15        use Mail::Box::Maildir;
16        my $folder = new Mail::Box::Maildir folder => $ENV{MAIL}, ...;
17

DESCRIPTION

19       This documentation describes how Maildir mailboxes work, and what you
20       can do with the Maildir folder object "Mail::Box::Maildir".
21
22       Maildir is not supported for Windows, because it create filenames which
23       are not accepted by the Windows system.
24

OVERLOADED

26       overload: ""
27
28           See "OVERLOADED" in Mail::Box
29
30       overload: @{}
31
32           See "OVERLOADED" in Mail::Box
33
34       overload: cmp
35
36           See "OVERLOADED" in Mail::Box
37

METHODS

39       Constructors
40
41       Mail::Box::Maildir->new(OPTIONS)
42
43        Option           --Defined in     --Default
44        accept_new                          <false>
45        access             Mail::Box        'r'
46        body_delayed_type  Mail::Box        Mail::Message::Body::Delayed
47        body_type          Mail::Box        Mail::Message::Body::Lines
48        coerce_options     Mail::Box        []
49        create             Mail::Box        <false>
50        directory          Mail::Box::Dir   <derived from folder name>
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}/.maildir
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_file          Mail::Box        <not used>
60        lock_timeout       Mail::Box        <not used>
61        lock_type          Mail::Box        'NONE' (constant)
62        lock_wait          Mail::Box        <not used>
63        locker             Mail::Box        undef
64        log                Mail::Reporter   'WARNINGS'
65        manager            Mail::Box        undef
66        message_type       Mail::Box        Mail::Box::Message
67        multipart_type     Mail::Box        Mail::Message::Body::Multipart
68        remove_when_empty  Mail::Box        <true>
69        save_on_exit       Mail::Box        <true>
70        trace              Mail::Reporter   'WARNINGS'
71        trusted            Mail::Box        <depends on folder location>
72
73           . accept_new BOOLEAN
74
75               When the folder is open, some messages may be stored in the
76               "new" sub-directory.  By default, these messages are immedi‐
77               ately moved to the "cur" directory when the folder is opened.
78               Otherwise, you have to call acceptMessages() or
79               Mail::Box::Maildir::Message::accept().
80
81           . access MODE
82
83           . body_delayed_type CLASS
84
85           . body_type CLASS⎪CODE
86
87           . coerce_options ARRAY
88
89           . create BOOLEAN
90
91           . directory DIRECTORY
92
93           . extract INTEGER ⎪ CODE ⎪ METHOD ⎪ 'LAZY'⎪'ALWAYS'
94
95           . field_type CLASS
96
97           . fix_headers BOOLEAN
98
99           . folder FOLDERNAME
100
101           . folderdir DIRECTORY
102
103           . head_delayed_type CLASS
104
105           . head_type CLASS
106
107           . keep_dups BOOLEAN
108
109           . lock_file FILENAME
110
111           . lock_timeout SECONDS
112
113           . lock_type CLASS⎪STRING⎪ARRAY
114
115           . lock_wait SECONDS
116
117           . locker OBJECT
118
119           . log LEVEL
120
121           . manager MANAGER
122
123           . message_type CLASS
124
125           . multipart_type CLASS
126
127           . remove_when_empty BOOLEAN
128
129           . save_on_exit BOOLEAN
130
131           . trace LEVEL
132
133           . trusted BOOLEAN
134
135       The folder
136
137       $obj->addMessage(MESSAGE, OPTIONS)
138
139           See "The folder" in Mail::Box
140
141       $obj->addMessages(MESSAGE [, MESSAGE, ...])
142
143           See "The folder" in Mail::Box
144
145       Mail::Box::Maildir->appendMessages(OPTIONS)
146
147           See "The folder" in Mail::Box
148
149       $obj->close(OPTIONS)
150
151           See "The folder" in Mail::Box
152
153       $obj->copyTo(FOLDER, OPTIONS)
154
155           See "The folder" in Mail::Box
156
157       $obj->delete(OPTIONS)
158
159           See "The folder" in Mail::Box
160
161       $obj->directory
162
163           See "The folder" in Mail::Box::Dir
164
165       $obj->folderdir([DIRECTORY])
166
167           See "The folder" in Mail::Box
168
169       $obj->name
170
171           See "The folder" in Mail::Box
172
173       $obj->organization
174
175           See "The folder" in Mail::Box
176
177       $obj->size
178
179           See "The folder" in Mail::Box
180
181       $obj->type
182
183           See "The folder" in Mail::Box
184
185       $obj->update(OPTIONS)
186
187           See "The folder" in Mail::Box
188
189       $obj->url
190
191           See "The folder" in Mail::Box
192
193       Folder flags
194
195       $obj->access
196
197           See "Folder flags" in Mail::Box
198
199       $obj->isModified
200
201           See "Folder flags" in Mail::Box
202
203       $obj->modified([BOOLEAN])
204
205           See "Folder flags" in Mail::Box
206
207       $obj->writable
208
209           See "Folder flags" in Mail::Box
210
211       The messages
212
213       $obj->current([NUMBER⎪MESSAGE⎪MESSAGE-ID])
214
215           See "The messages" in Mail::Box
216
217       $obj->find(MESSAGE-ID)
218
219           See "The messages" in Mail::Box
220
221       $obj->findFirstLabeled(LABEL, [BOOLEAN, [ARRAY-OF-MSGS]])
222
223           See "The messages" in Mail::Box
224
225       $obj->message(INDEX [,MESSAGE])
226
227           See "The messages" in Mail::Box
228
229       $obj->messageId(MESSAGE-ID [,MESSAGE])
230
231           See "The messages" in Mail::Box
232
233       $obj->messageIds
234
235           See "The messages" in Mail::Box
236
237       $obj->messages(['ALL',RANGE,'ACTIVE','DELETED',LABEL,!LABEL,FILTER])
238
239           See "The messages" in Mail::Box
240
241       $obj->nrMessages(OPTIONS)
242
243           See "The messages" in Mail::Box
244
245       $obj->scanForMessages(MESSAGE, MESSAGE-IDS, TIMESPAN, WINDOW)
246
247           See "The messages" in Mail::Box
248
249       Sub-folders
250
251       $obj->listSubFolders(OPTIONS)
252
253       Mail::Box::Maildir->listSubFolders(OPTIONS)
254
255           See "Sub-folders" in Mail::Box
256
257       $obj->nameOfSubFolder(SUBNAME, [PARENTNAME])
258
259       Mail::Box::Maildir->nameOfSubFolder(SUBNAME, [PARENTNAME])
260
261           See "Sub-folders" in Mail::Box
262
263       $obj->openRelatedFolder(OPTIONS)
264
265           See "Sub-folders" in Mail::Box
266
267       $obj->openSubFolder(SUBNAME, OPTIONS)
268
269           See "Sub-folders" in Mail::Box
270
271       $obj->topFolderWithMessages
272
273       Mail::Box::Maildir->topFolderWithMessages
274
275           See "Sub-folders" in Mail::Box
276
277       Internals
278
279       $obj->acceptMessages
280
281           Accept all messages which are waiting in the "new" directory to be
282           moved to the "cur" directory.  This will not rescan the directory
283           for newly arrived messages, because that's a task for update().
284
285       Mail::Box::Maildir->appendMessage(OPTIONS)
286
287       $obj->coerce(MESSAGE, OPTIONS)
288
289       $obj->create(FOLDERNAME, OPTIONS)
290
291       Mail::Box::Maildir->create(FOLDERNAME, OPTIONS)
292
293        Option   --Defined in--Default
294        folderdir  Mail::Box   undef
295
296           . folderdir DIRECTORY
297
298       $obj->createDirs(FOLDERDIR)
299
300       Mail::Box::Maildir->createDirs(FOLDERDIR)
301
302           The FOLDERDIR contains the absolute path of the location where the
303           messages are kept.  Maildir folders contain a "tmp", "new", and
304           "cur" sub-directory within that folder directory as well.  This
305           method will ensure that all directories exist.  Returns false on
306           failure.
307
308       $obj->determineBodyType(MESSAGE, HEAD)
309
310           See "Internals" in Mail::Box
311
312       $obj->folderIsEmpty(FOLDERDIR)
313
314       Mail::Box::Maildir->folderIsEmpty(FOLDERDIR)
315
316           Checks whether the folder whose directory is specified as absolute
317           FOLDERDIR is empty or not.  A folder is empty when the "tmp",
318           "new", and "cur" subdirectories are empty and some files which are
319           left there by application programs.  The maildir spec explicitly
320           states: ".qmail", "bulletintime", "bulletinlock" and "seriallock".
321           If any other files are found, the directory is considered
322           not-empty.
323
324       $obj->folderToDirectory(FOLDERNAME, FOLDERDIR)
325
326           See "Internals" in Mail::Box::Dir
327
328       Mail::Box::Maildir->foundIn([FOLDERNAME], OPTIONS)
329
330           See "Internals" in Mail::Box
331
332       $obj->lineSeparator([STRING⎪'CR'⎪'LF'⎪'CRLF'])
333
334           See "Internals" in Mail::Box
335
336       $obj->locker
337
338           See "Internals" in Mail::Box
339
340       $obj->read(OPTIONS)
341
342           See "Internals" in Mail::Box
343
344       $obj->readMessageFilenames(DIRECTORY)
345
346           See "Internals" in Mail::Box::Dir
347
348       $obj->readMessages(OPTIONS)
349
350           See "Internals" in Mail::Box
351
352       $obj->storeMessage(MESSAGE)
353
354           See "Internals" in Mail::Box
355
356       $obj->toBeThreaded(MESSAGES)
357
358           See "Internals" in Mail::Box
359
360       $obj->toBeUnthreaded(MESSAGES)
361
362           See "Internals" in Mail::Box
363
364       $obj->updateMessages(OPTIONS)
365
366           See "Internals" in Mail::Box
367
368       $obj->write(OPTIONS)
369
370           See "Internals" in Mail::Box
371
372       $obj->writeMessages(OPTIONS)
373
374           See "Internals" in Mail::Box
375
376       Other methods
377
378       $obj->timespan2seconds(TIME)
379
380       Mail::Box::Maildir->timespan2seconds(TIME)
381
382           See "Other methods" in Mail::Box
383
384       Error handling
385
386       $obj->AUTOLOAD
387
388           See "Error handling" in Mail::Reporter
389
390       $obj->addReport(OBJECT)
391
392           See "Error handling" in Mail::Reporter
393
394       $obj->defaultTrace([LEVEL]⎪[LOGLEVEL, TRACELEVEL]⎪[LEVEL, CALLBACK])
395
396       Mail::Box::Maildir->defaultTrace([LEVEL]⎪[LOGLEVEL, TRACELEVEL]⎪[LEVEL,
397       CALLBACK])
398
399           See "Error handling" in Mail::Reporter
400
401       $obj->errors
402
403           See "Error handling" in Mail::Reporter
404
405       $obj->log([LEVEL [,STRINGS]])
406
407       Mail::Box::Maildir->log([LEVEL [,STRINGS]])
408
409           See "Error handling" in Mail::Reporter
410
411       $obj->logPriority(LEVEL)
412
413       Mail::Box::Maildir->logPriority(LEVEL)
414
415           See "Error handling" in Mail::Reporter
416
417       $obj->logSettings
418
419           See "Error handling" in Mail::Reporter
420
421       $obj->notImplemented
422
423           See "Error handling" in Mail::Reporter
424
425       $obj->report([LEVEL])
426
427           See "Error handling" in Mail::Reporter
428
429       $obj->reportAll([LEVEL])
430
431           See "Error handling" in Mail::Reporter
432
433       $obj->trace([LEVEL])
434
435           See "Error handling" in Mail::Reporter
436
437       $obj->warnings
438
439           See "Error handling" in Mail::Reporter
440
441       Cleanup
442
443       $obj->DESTROY
444
445           See "Cleanup" in Mail::Box
446
447       $obj->inGlobalDestruction
448
449           See "Cleanup" in Mail::Reporter
450

DETAILS

452       The explanation is complicated, but for normal use you should bother
453       yourself with all details.
454
455       How MAILDIR folders work
456
457       Maildir-type folders use a directory to store the messages of one
458       folder.  Each message is stored in a separate file.  This seems useful,
459       because changes in a folder change only a few of these small files, in
460       contrast with file-based folders where changes in a folder cause
461       rewrites of huge folder-files.
462
463       However, Maildir based folders perform very bad if you need header
464       information of all messages.  For instance, if you want to have full
465       knowledge about all message-threads (see Mail::Box::Thread::Manager) in
466       the folder, it requires to read all header lines in all message files.
467       And usually, reading your messages as threads is desired.  Maildir
468       maintains a tiny amount of info visible in the filename, which may make
469       it perform just a little bit faster than MH.
470

DIAGNOSTICS

472       Error: Cannot append Maildir message in $new to folder $self.
473
474       The message (or messages) could not be stored in the right directories
475       for the Maildir folder.
476
477       Error: Cannot create Maildir directory $dir: $!
478
479       A Maildir folder is represented by a directory, with some sub-directo‐
480       ries.  The top folder directory could not be created for the reason
481       indicated.
482
483       Error: Cannot create Maildir folder $name.
484
485       One or more of the directories required to administer a Maildir folder
486       could not be created.
487
488       Error: Cannot create Maildir message file $new.
489
490       A message is converted from some other message format into a Maildir
491       format by writing it to a file with a name which contains the status
492       flags of the message.  Apparently, creating this file failed.
493
494       Error: Cannot create Maildir subdir $dir: $!
495
496       Each Maildir folder has three sub-directories for administration:
497       "new", "tmp", and "cur".  The mentioned directory could not be created
498       for the indicated reason.
499
500       Warning: Changes not written to read-only folder $self.
501
502       You have opened the folder read-only --which is the default set by
503       new(access)--, made modifications, and now want to close it.  Set
504       close(force) if you want to overrule the access mode, or close the
505       folder with close(write) set to "NEVER".
506
507       Error: Copying failed for one message.
508
509       For some reason, for instance disc full, removed by external process,
510       or read-protection, it is impossible to copy one of the messages.
511       Copying will proceed for the other messages.
512
513       Error: Destination folder $name is not writable.
514
515       The folder where the messages are copied to is not opened with write
516       access (see new(access)).  This has no relation with write permission
517       to the folder which is controled by your operating system.
518
519       Warning: Different messages with id $msgid
520
521       The message id is discovered more than once within the same folder, but
522       the content of the message seems to be different.  This should not be
523       possible: each message must be unique.
524
525       Error: Folder $name is opened read-only
526
527       You can not write to this folder unless you have opened the folder to
528       write or append with new(access), or the "force" option is set true.
529
530       Error: Folder $name not deleted: not writable.
531
532       The folder must be opened with write access via new(access), otherwise
533       removing it will be refused.  So, you may have write-access according
534       to the operating system, but that will not automatically mean that this
535       "delete" method permits you to.  The reverse remark is valid as well.
536
537       Error: Invalid timespan '$timespan' specified.
538
539       The string does not follow the strict rules of the time span syntax
540       which is permitted as parameter.
541
542       Warning: Message-id '$msgid' does not contain a domain.
543
544       According to the RFCs, message-ids need to contain a unique random
545       part, then an "@", and then a domain name.  This is made to avoid the
546       creation of two messages with the same id.  The warning emerges when
547       the "@" is missing from the string.
548
549       Error: Package $package does not implement $method.
550
551       Fatal error: the specific package (or one of its superclasses) does not
552       implement this method where it should. This message means that some
553       other related classes do implement this method however the class at
554       hand does not.  Probably you should investigate this and probably
555       inform the author of the package.
556
557       Error: Unable to create subfolder $name of $folder.
558
559       The copy includes the subfolders, but for some reason it was not possi‐
560       ble to copy one of these.  Copying will proceed for all other sub-fold‐
561       ers.
562
563       Error: Writing folder $name failed
564
565       For some reason (you probably got more error messages about this prob‐
566       lem) it is impossible to write the folder, although you should because
567       there were changes made.
568

LICENSE

574       Copyrights 2001-2007 by Mark Overmeer.For other contributors see
575       ChangeLog.
576
577       This program is free software; you can redistribute it and/or modify it
578       under the same terms as Perl itself.  See
579       http://www.perl.com/perl/misc/Artistic.html
580
581
582
583perl v5.8.8                       2007-03-25             Mail::Box::Maildir(3)