.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "MAIL-EXPIRE 1"
.TH MAIL-EXPIRE 1 "2023-06-15" "mail-expire 0.9.2+nmu1" "User Commands"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
mail\-expire \- program to extract outdated messages from mbox files
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.IP "\fBmail-expire\fR \fIAGE-IN-DAYS\fR \fI\s-1FILES...\s0\fR" 4
.IX Item "mail-expire AGE-IN-DAYS FILES..."
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBmail-expire\fR is a small utility which only purpose is to help on keeping the
size of multiple mail folders as small as needed (by removing outdated
messages).
.PP
\&\fIMaildir\fR and \fIMailbox\fR formats are supported for input, both types are mentioned
interchangeably in this manual page. Output goes to \fIMailbox\fR files.
.PP
The old messages are compressed with gzip or xz and stored in the file with
the name following the pattern \fI\s-1MBOXNAME.MONTH_YEAR\s0\fR.gz (or similar). The
reference time for the output filename is calculated from the current time
minus number of days specified in the first parameter.
.PP
If a file of the same name is found, the default storage strategy is appending
a new compressed region to the existing file (unless \fB\-u\fR option is used).
This allows, for example, to run the expiration in a cron job each weekend,
while collecting all mails from (roughly) each month into dedicated buckets.
The drawback of this appending mode is a slightly reduced compression ratio,
the advantage is reduced disk usage all the time.
Also, such archives can later be recompressed separately to archive the highest
compression ratio (like: \*(L"mv x.xz x.old.xz && xzcat x.old.xz | xz \-9 > x.xz &&
rm xz.old.xz\*(R").
.SS "\s-1SPACE REQUIREMENTS\s0"
.IX Subsection "SPACE REQUIREMENTS"
For \fIMbox\fR input, additional disk space to store the amount of fresh messages plus a portion of the size of expired messages (depending on the output compression).
.PP
For \fIMaildir\fR input, only additional space for a portion of the size of expired messages (depending on the output compression) is required.
.SH "OPTIONS"
.IX Header "OPTIONS"
\&\fBmail-expire\fR recognizes the following options:
.IP "\fB\-u\fR" 4
.IX Item "-u"
If an existing archive file with the expected filename is found, another filename is to be chosen. This happens by appending a suffix like (\s-1NUMBER\s0) to the basename.
.Sp
This is a legacy option, not compatible with any custom output command.
.IP "\fB\-t \s-1DIR\s0\fR" 4
.IX Item "-t DIR"
Specifies a different target directory for storing expired mailbox files. Default is the current directory.
.IP "\fB\-T \s-1FILEBASE\s0\fR" 4
.IX Item "-T FILEBASE"
Explicit output target file name for all inputs (i.e. merging all expired mails into the same target mbox).
This mostly disables automated name generation (base name and date suffix),
only the compression suffix (\-c option and related) is appended.
.IP "\fB\-\-sfx\-fmt \s-1FORMAT\s0\fR" 4
.IX Item "--sfx-fmt FORMAT"
Format string, see \fIstrftime\fR or \fIdate\fR manpage.
.IP "\fB\-\-dry\-run\fR, \fB\-n\fR" 4
.IX Item "--dry-run, -n"
Only examine input files and directories, no mail data is moved around.
.IP "\fB\-\-delete\fR, \fB\-d\fR" 4
.IX Item "--delete, -d"
Drop the old messages. No backup will be made, be careful with this option.
.IP "\fB\-\-keep\fR, \fB\-k\fR" 4
.IX Item "--keep, -k"
Copy the expired messages to output files and keep them in the input file.
.IP "\fB\-\-purge=VALUE\fR, \fB\-p \s-1VALUE\s0\fR" 4
.IX Item "--purge=VALUE, -p VALUE"
Specify how to remove \fIinput\fR files or folders after becoming empty. 0: never
remove, 1 (default): remove empty files but keep folders (also related
folders), 2: remove empty Mbox file and Maildir, 3: like 2 but also remove the
input file if it was empty.
.IP "\fB\-v \s-1LEVEL\s0\fR" 4
.IX Item "-v LEVEL"
Verbosity level, where 0 produces no output except for errors, 1 some progress messages, 2 and more verbose progress messages.
.IP "\fB\-c output-shell-command\fR" 4
.IX Item "-c output-shell-command"
A shell script fragment which is run in order to archive the data.
Default or current value can be displayed with \-v2 option.
.Sp
This command is very delicate, it might destroy the target file.
It might also be suspicious to shell injection attacks, quotes are important.
.IP "\fB\-X\fR" 4
.IX Item "-X"
Shortcut for \-c and \-s options, compressing with \s-1XZ\s0 compressor (multiple
threads) and .xz file suffix.
.IP "\fB\-Z\fR" 4
.IX Item "-Z"
Shortcut for \-c and \-s options, compressing with Zstandard compressor (zstd or zstdmt
where available) and .zstd file suffix.
.IP "\fB\-U\fR" 4
.IX Item "-U"
Shortcut for \-c and \-s options, to not compress the output and not have an
additional suffix.
.IP "\fB\-l\fR" 4
.IX Item "-l"
Lockless operation, input Mailboxes are assumed to be not touched by other
tools while \fImail-expire\fR runs. By default, it attempts to mimic the behavior
of \fIprocmail\fR to prevent it from file modifications. This option has no effect
on \fIMaildir\fR type input. To be used with care, runtime conflicts with
\&\fIprocmail\fR or other tools \fB\s-1MIGHT CAUSE DATA LOSS\s0\fR.
.SH "AUTHOR"
.IX Header "AUTHOR"
This manual page was written by Eduard Bloch. Permission is granted to use,
copy, distribute and/or modify this document under the terms of the
\&\fI\s-1MIT\s0\fR license.