pmarewritemeta(3) — Linux manual page

NAME | C SYNOPSIS | CAVEAT | DESCRIPTION | DIAGNOSTICS AND RETURN VALUES | SEE ALSO | COLOPHON

PMAREWRITEMETA(3)        Library Functions Manual       PMAREWRITEMETA(3)

NAME         top

       pmaRewriteMeta - try to change the version of an archive metadata
       record

C SYNOPSIS         top

       #include <pcp/pmapi.h>
       #include <pcp/libpcp.h>
       #include <pcp/archive.h>

       int pmaRewriteMeta(__pmLogCtl *inlcp, __pmLogCtl *outlcp,
                          __int32_t *rbuf);

       cc ... -lpcp_archive -lpcp

CAVEAT         top

       This  documentation  is intended for internal Performance Co-Pilot
       (PCP) developer use.

       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.

DESCRIPTION         top

       A physical metadata record from the input  archive  identified  by
       inlcp is passed in via rbuf and this is reformatted if required to
       produce  the  equivalent  metadata  record  for the output archive
       identified by outlcp.

       Combined with the input and output archive versions, the  type  of
       the metadata record (as extracted from rbuf) is used to decide if;
       for  some  record  types  and  version changes no rewriting is re‐
       quired.

       pmaRewriteMeta is intended to be used in cases where  the  archive
       version  of  inlcp and outlcp are different.  The only sane choice
       of  archive  versions  today  is  PM_LOG_VERS02  for   inlcp   and
       PM_LOG_VERS03 for outlcp, which would be requesting a rewrite from
       archive version 2 format to archive version 3 format (as only ver‐
       sions 2 and 3 are currently supported).

       If  rewriting takes place the old rbuf will have been free'd and a
       new rbuf allocated with malloc(3).  It is the  caller's  responsi‐
       bility to make sure this potential free-and-allocate will be safe,
       e.g.  no dangling references into the contents of rbuf, or pass in
       a copy of the record if it is precious.

DIAGNOSTICS AND RETURN VALUES         top

       In several places, fatal errors will trigger an error message  and
       force the application to exit.

       If  there  is no defined translation for the versions of inlcp and
       outlcp then pmaRewriteMeta  returns  PM_ERR_APPVERSION  (a  slight
       perversion of this error code).

       If no rewrite is performed, the return value is 0, otherwise a re‐
       turn  value  of 1 indicates a rewrite has taken place and rbuf has
       been reallocated.

SEE ALSO         top

       free(3), malloc(3), PMAPI(3), and pmaRewriteData(3).

COLOPHON         top

       This page is part of the PCP (Performance Co-Pilot) project.   In‐
       formation  about the project can be found at ⟨http://www.pcp.io/⟩.
       If you have a  bug  report  for  this  manual  page,  send  it  to
       pcp@groups.io.  This page was obtained from the project's upstream
       Git  repository ⟨https://github.com/performancecopilot/pcp.git⟩ on
       2025-08-11.  (At that time, the date of  the  most  recent  commit
       that was found in the repository was 2025-08-11.)  If you discover
       any  rendering  problems  in this HTML version of the page, or you
       believe there is a better or more up-to-date source for the  page,
       or you have corrections or improvements to the information in this
       COLOPHON  (which  is not part of the original manual page), send a
       mail to man-pages@man7.org

Performance Co-Pilot               PCP                  PMAREWRITEMETA(3)

Pages that refer to this page: pmarewritedata(3)