|
HTML rendering created 2026-09-09 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|
|
NAME | C SYNOPSIS | Perl SYNOPSIS | Python SYNOPSIS | DESCRIPTION | DIAGNOSTICS | SEE ALSO | COLOPHON |
|
|
|
PMISTART(3) Library Functions Manual PMISTART(3)
pmiStart - establish a new LOGIMPORT context
#include <pcp/pmapi.h>
#include <pcp/import.h>
int pmiStart(const char *archive, int flags);
cc ... -lpcp_import -lpcp
use PCP::LogImport;
pmiStart($archive, $flags);
from pcp import pmi
log = pmi.pmiLogImport(archive, flags)
As part of the Performance Co-Pilot Log Import API (see
LOGIMPORT(3)), pmiStart creates a new context. Each context main‐
tains the following state and metadata:
• The base name (archive) for the physical files that constitute
the output PCP archive.
• The source hostname for the data that will be written to the
PCP archive. Defaults to the hostname of the localhost, but
can be set using pmiSetHostname(3).
• The source timezone for the PCP archive. Defaults to the time‐
zone of the localhost, but can be set using pmiSetTimezone(3).
• The output archive version number for the PCP archive. De‐
faults to the traditional version 2 format, but can be set us‐
ing pmiSetVersion(3).
• Metrics and instance domains, as defined by pmiAddMetric(3).
• Instances for each instance domain, as defined by
pmiAddInstance(3).
• Handles as defined by pmiGetHandle(3). Each handle is a met‐
ric-instance pair, and each metric-instance pair may have an
associated value in each record written to the output PCP
archive.
• An optional set of data values for one or more metric-instance
pairs (ready for the next record to be written to the output
PCP archive) as defined by calls to pmiPutValue(3) or
pmiPutValueHandle(3).
The flags argument is a bitwise-OR of zero or more of the follow‐
ing constants:
PMI_INHERIT
The new context will inherit any and all metadata (metrics,
instance domains, instances and handles) from the current
context. The basename for the output PCP archive, the
source hostname, the source timezone and any data values
from the current context are not inherited. If this is the
first call to pmiStart the metadata will be empty indepen‐
dent of whether PMI_INHERIT is set.
PMI_APPEND
Open an existing PCP archive for appending rather than cre‐
ating a new one. The archive label (hostname, timezone,
version, start timestamp) is read from the existing
archive.meta file and used to initialise the new context.
The temporal index is read to seed the last-written time‐
stamp; all subsequent pmiWrite(3) calls must use timestamps
strictly later than this value. The archive.meta and
archive.index files are opened in read/write mode and posi‐
tioned at end-of-file; the highest-numbered data volume is
opened in append mode. Metrics and instance domains must
still be registered via pmiAddMetric(3) and
pmiAddInstance(3) before calling pmiPutValue(3) — if the
metric descriptor is already present in the archive the du‐
plicate entry in archive .meta is harmless and will be ig‐
nored by readers. If the archive files do not yet exist,
PMI_APPEND behaves identically to creating a new archive
(no flags).
PMI_APPEND and PMI_INHERIT may be used together. The inherited
metric and instance-domain definitions are carried into the new
context, and when the archive is opened on the first pmiWrite(3)
call, each inherited descriptor is checked against what is already
on disk: compatible descriptors are silently skipped (no duplicate
written); incompatible ones are rejected with an appropriate error
(e.g. PM_ERR_LOGCHANGETYPE). When the previous context was writ‐
ing to the same archive, every inherited descriptor already exists
on disk so the combination is effectively a no-op beyond conve‐
nience.
If flags is zero, or neither PMI_INHERIT nor PMI_APPEND is set,
the new context is created with no metadata and a new archive will
be created from scratch.
Since no physical files for the output PCP archive will be created
until the first call to pmiWrite(3) or pmiPutResult(3), archive
could be NULL to create a convenience context that is populated
with metadata to be inherited by subsequent contexts.
The return value is a context identifier that could be used in a
subsequent call to pmUseContext(3) and the new context becomes the
current context which persists for all subsequent calls up to ei‐
ther another pmiStart call or a call to pmiUseContext(3) or a call
to pmiEnd(3).
When creating a new archive (neither PMI_APPEND nor any other flag
that implies file creation), it is an error if the physical files
archive.0 and/or archive.index and/or archive.meta already exist,
but this is not discovered until the first attempt is made to out‐
put some data by calling pmiWrite(3) or pmiPutResult(3), so pmiS‐
tart always returns a positive context identifier.
When PMI_APPEND is set and the archive files do not exist, pmiS‐
tart silently falls back to creating a new archive, making it safe
to use PMI_APPEND unconditionally on the first invocation of a da‐
ta collector.
LOGIMPORT(3), PMAPI(3), pmiAddInstance(3), pmiAddMetric(3),
pmiEnd(3), pmiErrStr(3), pmiGetHandle(3), pmiPutLabel(3),
pmiPutResult(3), pmiPutText(3), pmiPutValue(3),
pmiPutValueHandle(3), pmiSetHostname(3), pmiSetTimezone(3),
pmiSetVersion(3), pmiUseContext(3) and pmiWrite(3).
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
2026-08-04. (At that time, the date of the most recent commit
that was found in the repository was 2026-08-04.) 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 PMISTART(3)
Pages that refer to this page: logimport(3), pmiend(3), pmisethostname(3), pmisetimportprogram(3), pmisettimezone(3), pmisetversion(3), pmisetvolumesize(3), pmiusecontext(3)
|
HTML rendering created 2026-09-09 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|