'\"macro stdmacro
.\"
.\" Copyright (c) 2014 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 PMLOGMV 1 "PCP" "Performance Co-Pilot"
.SH NAME
\f3pmlogmv\f1 \- move (rename) Performance Co-Pilot archive files
.SH SYNOPSIS
\f3pmlogmv\f1
[\f3\-cfNV?\f1]
\f2oldname\f1
\f2newname\f1
.SH DESCRIPTION
A Performance Co-Pilot (PCP) archive consists of multiple files as
created by
.BR pmlogger (1).
.B pmlogmv
allows all the files of a single PCP archive
to be moved or renamed as a group in a single operation.
.PP
The
.I oldname
argument identifies the target archive, and may be either the basename
that is common to all files in that archive or one of the archive's
files.
The new archive's basename is
.IR newname .
.PP
Because PCP archives are important records of system activity, special
care is taken to ensure the integrity of an archive's files.
For recoverable problems encountered during the execution of
.BR pmlogmv ,
all the files associated with
.I oldname
will be preserved, and no new files with the
.I newname
prefix will be created.
``Recoverable problems'' include signals that can be caught (such as SIGHUP,
SIGINT, SIGQUIT and SIGTERM), permissions issues, new files already existing,
file system full events, etc.
.PP
The implementation of
.B pmlogmv
tries to use
hard links in the file system and so follows the semantic
restrictions of
.IR ln (2)
which for most systems means the directories containing both
the
.I oldname
and the
.I newname
PCP archive files need to be within the
.B same
file system.
When this is not possible,
.B pmlogmv
falls back to using
.BR cp (1)
to copy
.I oldname
to
.IR newname .
.SH OPTIONS
The available command line options are:
.TP 5
\fB\-c\fR, \fB\-\-checksum\fR
Paranoid checking mode when
.BR cp (1)
is needed and each file's checksum is computed for the
original file and the copied file, and the checksums must match before
the copy is considered acceptable.
The checksum command is chosen by trying the following in turn until
one is found to be executable:
.BR md5sum (1),
.BR sha256sum (1),
.BR sha1sum(1)
and
.BR sum (1).
If no executable checksum command is found, a warning is issued and the
checksum check is skipped.
.TP 5
\fB\-f\fR, \fB\-\-force\fR
Normally
.B pmlogmv
takes a conservative view in respect of
.I newname
and will not proceed if
.I newname
contains any characters that are likely to cause a problem for
.BR sh (1).
This includes ``glob'' characters like ``?'', ``*'' and ``['', shell
syntax meta characters like ``('', ``|'', ``;'' and ``&'', shell
I/O redirection characters like ``<'' and ``>'', the dollar sign,
a space, etc.
.RS
.PP
The
.B \-f
flag forces
.B pmlogmv
to proceed, even if
.I newname
contains any of these ``unsafe'' characters.
.RE
.TP
\fB\-N\fR, \fB\-\-showme\fR
Perform a dry-run, checking and reporting what changes would
be made without making any changes.
.TP
\fB\-V\fR, \fB\-\-verbose\fR
Enable verbose mode.
.TP
\fB\-?\fR, \fB\-\-help\fR
Display usage message and exit.
.SH DIAGNOSTICS
All error and warning messages are intended to be easily understood and
errors produce a non-zero exit status.
.SH SEE ALSO
.BR cp (1),
.BR ln (1),
.BR md5sum (1),
.BR PCPIntro (1),
.BR pmlogger (1),
.BR sha1sum (1),
.BR sha256sum (1)
and
.BR LOGARCHIVE (5).