'\"macro stdmacro
.\"
.\" Copyright (c) 2022 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 PMAREWRITEMETA 3 "PCP" "Performance Co-Pilot"
.SH NAME
\f3pmaRewriteMeta\f1 \- try to change the version of an archive metadata record
.SH "C SYNOPSIS"
.ft 3
#include <pcp/pmapi.h>
.br
#include <pcp/libpcp.h>
.br
#include <pcp/archive.h>
.sp
int pmaRewriteMeta(__pmLogCtl *\fIinlcp\fP, __pmLogCtl *\fIoutlcp\fP, __int32_t *\fIrbuf\fP);
.sp
cc ... \-lpcp_archive \-lpcp
.ft 1
.SH CAVEAT
This documentation is intended for internal Performance Co-Pilot
(PCP) developer use.
.PP
These interfaces are not part of the PCP APIs that are guaranteed to
remain fixed across releases, and they may not work, or may provide
different semantics at some point in the future.
.SH DESCRIPTION
.de CR
.ie t \f(CR\\$1\fR\\$2
.el \fI\\$1\fR\\$2
..
A physical metadata record from the input archive identified by
.I inlcp
is passed in via
.I rbuf
and this is reformatted if
required to produce the equivalent metadata record for the output
archive identified by
.IR outlcp .
.PP
Combined with the input and output archive versions,
the type of the metadata record (as extracted from
.IR rbuf )
is used to decide if;
for some record types and version changes no rewriting is required.
.PP
.B pmaRewriteMeta
is intended to be used in cases where the archive version of
.I inlcp
and
.I outlcp
are different.
The only sane choice of archive versions
today is
.B PM_LOG_VERS02
for
.I inlcp
and
.B PM_LOG_VERS03
for
.IR outlcp ,
which would be requesting a rewrite from archive version 2 format
to archive version 3 format
(as only versions 2 and 3 are currently supported).
.PP
If rewriting takes place the old
.I rbuf
will have been free'd and a new
.I rbuf
allocated with
.BR malloc (3).
It is the caller's responsibility to make sure
this potential free-and-allocate will be safe, e.g. no dangling references
into the contents of
.IR rbuf ,
or pass in a copy of
the record if it is precious.
.SH DIAGNOSTICS AND RETURN VALUES
In several places, fatal errors will trigger an error message and
force the application to exit.
.PP
If there is no defined translation for the versions of
.I inlcp
and
.I outlcp
then
.B pmaRewriteMeta
returns
.B PM_ERR_APPVERSION
(a slight perversion of this error code).
.PP
If no rewrite is performed, the return value is 0, otherwise a return value
of 1 indicates a rewrite has taken place and
.I rbuf
has been reallocated.
.SH SEE ALSO
.BR free (3),
.BR malloc (3),
.BR PMAPI (3),
and
.BR pmaRewriteData (3).