'\"macro stdmacro
.\"
.\" Copyright (c) 2024 Ken McDonell.  All Rights Reserved.
.\"
.\" This program is free software; you can redistribute it and/or modify it
.\" under the terms of the GNU General Public License as published by the
.\" Free Software Foundation; either version 2 of the License, or (at your
.\" option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful, but
.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
.\" or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
.\" for more details.
.\"
.TH PMLOGCOMPRESS 1 "PCP" "Performance Co-Pilot"
.SH NAME
\f3pmlogcompress\f1 \- compress and decompress PCP archive files
.SH SYNOPSIS
\fBpmlogcompress\fR
[\fB\-dNVz?\fR]
[\fB\-A\fR \fIarg\fR]
[\fB\-c\fR \fIproglist\fR]
[\fB\-f\fR \fIprog\fR]
[\fB\-l\fR \fIlimit\fR]
[\fB\-o\fR \fItype\fR]
[\fB\-t\fR \fIdir\fR]
[\fB\-Z\fR \fImin\fR]
\fIarchive\fR]...
.SH DESCRIPTION
.B pmlogcompress
supports the compression and decompression of the files that
make up a
Performance Co-Pilot (PCP)
archive; refer to
.BR LOGARCHIVE (5)
for an explanation of the various files that are components
of a PCP archive.
.PP
The
.I archive
arguments may be either the name of a single file in a PCP archive
or the basename of a PCP archive, as in the style generated by
.BR pmlogbasename (1).
In the former case,
.B pmlogcompress
will compress or decompress just that file, but in the latter
case
.B pmlogcompress
will attempt to compress or decompress
.B all
the files that are part of the associated PCP archive.
.PP
In keeping with other compression tools, the default mode for
.B pmlogcompress
is to compress, i.e. the
.B \-z
option, to decompress the
.BR \-d
option is required.
.SH OPTIONS
The available command line options are:
.TP 5
\fB\-A\fR \fIarg\fR, \fB\-\-arg\fR=\fIarg\fR
.I arg
is used as an argument to the compression
program; most likely useful with the
.B \-f
option so that the choice of compression program
is deterministic.
.RS 5
.PP
The processing of
.I arg
is not sophisticated, so embedded shell variables, escape characters, shell ``glob'' characters
and white space should be avoided.
.PP
Multiple
.B \-A
options are allowed and
.B all
the
.I arg
arguments will be used.
.RE
.TP
\fB\-c\fR \fIproglist\fR, \fB\-\-command\fR=\fIproglist\fR
Depending on other command line options, and the availability of installed
compression programs, the choice if program when compressing may vary.
The
.B \-c
option allows a
.B list
of compression programs to be provided, either with multiple
.B \-c
options and/or by separating program names in
.I proglist
by a colon, in the style of the shell's
.B $PATH
notation.
.RS 5
.PP
The default value for
.I proglist
is
.BR zstd:xz:bzip2:gzip .
.RE
.TP
\fB\-f\fR \fIprog\fR, \fB\-\-use\fR=\fIprog\fR
If only one program is to be considered for compression then this
may be specified using the
.B \-f
option.
The effect is the same as if only one
.B \-c
option was used, and
.I proglist
contained exactly one program name, namely
.IR prog .
.TP
\fB\-d\fR, \fB\-\-decompress\fR
Choose decompression mode.
The suffix of each file associated with
.I archive
determines the decompression tool to be used.
.TP
\fB\-l\fR \fIlimit\fR, \fB\-\-lower-limit\fR=\fIlimit\fR
When compressing, do not consider files smaller than
.I limit
(bytes).
.TP
\fB\-N\fR, \fB\-\-show-me\fR
Do nothing, but show what commands would have been executed.
.TP
\fB\-o\fR \fItype\fR, \fB\-\-optimize\fR=\fItype\fR
When compressing the
.B \-o
option will try to pick the compression program from
.I proglist
(see the
.B \-c
option above)
that does the ``best'' job, where
.I type
may be
.B size
to choose the compression program that produces the smallest
output file, or
.B cpu
to choose the compression program that uses the least CPU
time.
.RS 5
.PP
If
.I archive
is an archive basename then
the largest of the
files that are part of the associated PCP archive
is selected for the test, else
.I archive
will be used for the test.
.PP
Use of this option means each of the selected
.I archive
files will be compressed multiple times, so it is likely
that
.B \-o
would be used in experiments with
.B \-N
(and possibly \fB\-V\fP)
to determine the best compression tool for the local
environment and PCP archives.
.RE
.TP
\fB\-t\fR \fIdir\fR, \fB\-\-dir\fR=\fIdir\fR
When decompressing any compressed files will (by default) be
replaced by their decompressed equivalent.
The
.B \-t
option changes this behavior to create a duplicate, uncompressed
.I archive
in the
.I dir
directory.
.RS 5
.PP
If
.I archive
is a single file, then only that file is decompressed into
.IR dir ,
but if
.I archive
is an archive basename then
.B all
of the files of
.I archive
will be copied, and possibly decompressed, into
.IR dir .
.PP
.I dir
must exist before
.B pmlogcompress
is run.
.RE
.TP
\fB\-V\fR, \fB\-\-verbose\fR
Increase verbosity.
.TP
\fB\-z\fR, \fB\-\-compress\fR
Choose compression mode (the default).
.TP
\fB\-Z\fR \fImin\fR, \fB\-\-min-zstd-size\fR=\fImin\fR
.BR xz (1)
produces smaller compressed files for small input files,
but at some point the input file becomes large enough that
.BR zstd (1)
produces smaller compressed files and
.B zstd
is typically much faster.
.RS 5
.PP
When both
.B xz
and
.B xstd
are in consideration
(see the
.I \-c
option above), then the
.B \-Z
option allows the user to tune where the
.B xz
to
.B zstd
cut-over happens; input files smaller than
.I min
(in bytes)
will be compressed with
.B xz
else
.B zstd
will be used.
.PP
The default value for
.I min
is 52428800
(50MiB).
.RE
.TP
\fB\-?\fR, \fB\-\-help\fR
Display usage message and exit.
.SH SEE ALSO
.BR PCPIntro (1),
.BR bzip2 (1),
.BR gzip (1),
.BR pmlogbasename (1),
.BR pmlogger (1),
.BR pmlogger_check (1),
.BR pmlogger_daily (1),
.BR xz (1),
.BR zstd (1)
and
.BR LOGARCHIVE (5).

.SH TODO
back reference to pmlogger_daily and friends where all the compression is done at the moment

.\" control lines for scripts/man-spell
.\" +ok+ xstd zstd