---

pmsetmode(3) — Linux manual page

PMSETMODE(3) Library Functions Manual PMSETMODE(3)

NAME top

 pmSetMode - set collection time and mode parameters for the
 current PMAPI context

C SYNOPSIS top

 #include <pcp/pmapi.h>
 int pmSetMode(int mode, const struct timespec *when,
 const struct timespec *delta);
 cc ... -lpcp

DESCRIPTION top

 pmSetMode are used to define the collection time and/or mode for
 accessing performance metrics and metadata in the current Perfor‐
 mance Metrics Application Programming Interface (PMAPI) context.
 This mode affects the semantics of subsequent calls to the follow‐
 ing PMAPI routines: pmFetch(3), pmFetchArchive(3),
 pmLookupDesc(3), pmGetInDom(3), pmLookupInDom(3),
 pmLookupLabels(3) and pmNameInDom(3).
 Intended mainly for retrospective analysis of performance metrics
 from a PCP archive, the options described below allow an applica‐
 tion to implement seeking to an arbitrary time within the archive,
 playback, fast forward, reverse, etc. by alternating calls to pm‐
 SetMode and pmFetch(3).
 If mode is PM_MODE_LIVE then all information is returned from the
 active pool of performance metrics as of the time that the PMAPI
 call is made, and the other two parameters to pmSetMode (when and
 delta) are ignored. PM_MODE_LIVE is the default mode when a new
 PMAPI context is created with type PM_CONTEXT_HOST (i.e. fetching
 metrics from pmcd(1)) or PM_CONTEXT_LOCAL, and this mode is rarely
 used in calls to pmSetMode
 The other values of mode are used with PCP archives where the as‐
 sociated PMAPI context must be of type PM_CONTEXT_ARCHIVE (when it
 was created with pmNewContext(3)) and the when parameter defines
 the current time within the archive. All requests for metric val‐
 ues and metadata (metric descriptions and instance identifiers
 from the instance domains) will be processed to reflect the state
 in the archive as of the current time.
 When selecting a value for when, the time at the start of the
 archive can be established from the ll_start field in the struc‐
 ture returned from a call to pmGetArchiveLabel(3) or the start
 field in the structure returned from a call to
 pmGetArchiveLabel(3), and the time at the end of the archive can
 be established by calling pmGetArchiveEnd(3)
 As a special case, if when is NULL then the mode and delta argu‐
 ments are used as described below, but the current time in the
 archive is not altered.

TIME-DRIVEN ARCHIVE MODE top

 If mode is PM_MODE_INTERP then as metric values are retrieved from
 the archive with pmFetch(3) the current time is returned as the
 timestamp in the pmResult structure and the current time moves on;
 if delta is positive, the current time moves forwards, else the
 current time moves backwards. The adjustment to the current time
 is applied even if the pmFetch(3) fails to return values for any
 metrics or returns an error, e.g. PM_ERR_EOL because the current
 time is outside the range defined by the records in the archive.
 When metric values are being requested via pmFetch(3) the current
 time may not exactly match the times at which values have been
 recorded in the archive, so the returned metric values are comput‐
 ed from the observed metric values in the archive (usually at
 times close to the current time).
 For metrics with semantics of PM_SEM_COUNTER, the computed value
 is based on linear interpolation between the last observation be‐
 fore the current time and the first observation after the current
 time.
 For metrics with semantics of PM_SEM_INSTANT or PM_SEM_DISCRETE,
 the computed value is based on values in the neighbourhood of the
 current time.
 The algorithms used in these computations depend on the semantics
 of the metrics and the time series of observed values in the
 archive; a fuller explanation may be found in the white paper Ex‐
 plaining Value Interpolation with PCP Archives found at
 https://pcp.io/papers/archive-interpolation.pdf .

RECORD-DRIVEN ARCHIVE MODES top

 If mode is PM_MODE_FORW or PM_MODE_BACK then when metric values
 are being requested via pmFetch(3) the archive will be scanned in
 a forwards (PM_MODE_FORW) or backwards (PM_MODE_BACK) direction in
 time, until an archive record is encountered with values for at
 least one of the requested metrics. This archive record is used
 to provide as many of the requested metrics as possible and these
 are returned with the timestamp if the record in the archive,
 which becomes the new current time.
 Note that any metrics requested via pmFetch(3) that do not have a
 value in the archive record at the new current time will return no
 values, and so this mode is most useful for archives where all of
 the metrics of interest have been logged regularly at the same
 time in the archive. Otherwise, each pmFetch(3) will contain only
 the subset of the requested metrics and any associated instances
 found in the qualifying archive record.
 The delta parameter is ignored, because the current time is driven
 by the timestamp in the matching archive record. So there is no
 concept of stepping through the archive in regular time with this
 mode, although if the requested metrics appear at regular inter‐
 vals in the archive the current time may advance by regular inter‐
 vals, but this is serendipitous.
 If no qualifying metrics can be found in the requested direction
 of searching before the end or start of the archive is encoun‐
 tered, then pmFetch(3) returns the special error indicator,
 PM_ERR_EOL.

RECOMMENDATIONS top

 When processing PCP archives, PM_MODE_INTERP is preferred because:
 • This maximizes the information that will be returned in each
 pmFetch(3)
 • This returns values at regular intervals of the current time,
 independent of the logging frequency for requested metrics in
 the archive.
 • This works with any PCP archive, as opposed to the record-driven
 modes which may work acceptably for archives with regular log‐
 ging of all requested metrics, but may fail to report complete
 or useful results for other archives.
 • This mode provides the closest semantic match to PM_MODE_LIVE
 and leads to the least user surprise when moving between real-
 time monitoring and retrospective analysis.

EXAMPLES top

 To replay interpolated metrics from an archive at 10 second inter‐
 vals, the following code fragment could be used:
 struct timeval mytime;
 int mydelta = 10 * 1000; /* msec */
 pmLogLabel label;
 pmResult result;
 pmNewContext(PM_CONTEXT_ARCHIVE, "myarchive");
 pmGetArchiveLabel(&label);
 mytime = label.ll_start;
 pmSetMode(PM_MODE_INTERP, &mytime, mydelta)
 while (pmFetch(numpmid, pmidlist, &result) != PM_ERR_EOL) {
 /*
 * process interpolated metric values as of
 * result->timestamp
 */
 . . .
 pmFreeResult(result);
 }
 The following code fragment may be used to dump values for select‐
 ed metrics in an archive in reverse temporal sequence.
 struct timespec mytime;
 pmResult result;
 pmNewContext(PM_CONTEXT_ARCHIVE, "myarchive");
 pmGetArchiveEnd(&mytime);
 pmSetMode(PM_MODE_BACK, &mytime, NULL);
 while (pmFetch(npmid, pmidlist, &result) != PM_ERR_EOL) {
 /*
 * process logged metric values as of result->timestamp
 */
 . . .
 pmFreeResult(result);
 }

COMPATIBILITY top

 Prior to PCP 7.0 the when argument was a struct timeval and the
 delta argument was an int (in units of milliseconds). To support
 PMAPI transition, the old interface and semantics can be used if
 applications are recompiled with -DPMAPI_VERSION=2.
 For a time in PCP 6.x there was a routine with the same semantics
 as the current pmSetMode called pmSetModeHighRes although this is
 now deprecated and compile-time support for pmSetModeHighRes will
 be removed in a future release.

DIAGNOSTICS top

 PM_ERR_MODE
 The mode parameter is invalid

SEE ALSO top

 pmcd(1), PMAPI(3), pmFetch(3), pmFetchArchive(3),
 pmGetArchiveEnd(3), pmGetArchiveLabel(3), pmGetInDom(3),
 pmLookupDesc(3), pmLookupInDom(3), pmLookupLabels(3),
 pmNameInDom(3) and pmNewContext(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 PMSETMODE(3)

---

Pages that refer to this page: pcpintro(1), pcpintro(3), pmapi(3), pmfetch(3), pmfetcharchive(3), pmfetchgroup(3), pmgetarchiveend(3), pmnewcontext(3), pmstore(3), pmtime(3), QmcGroup(3)

---

---

---