---
name: "pmiSetImportProgram"
section: "3"
platform: "linux"
package: "pcp"
version: "7.2.2-2"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/pmiSetImportProgram"
---

# pmiSetImportProgram(3)

register an import tool with pmdapmimport

## NAME

**pmiSetImportProgram** - register an import tool with pmdapmimport

## C SYNOPSIS

**#include \<pcp/pmapi.h\>**\
 **#include \<pcp/import.h\>**

**int pmiSetImportProgram(const char \****tool***, const char \****version***, const char \****args***, const char \****archive***);**

**cc ... -lpcp\_import -lpcp**

## DESCRIPTION

As part of the Performance Co-Pilot Log Import API (see [**LOGIMPORT**(3)](/LOGIMPORT/3.md)), **pmiSetImportProgram** registers the running import tool with **pmdapmimport**(1) so that its status is visible through the **pmimport.\*** metric family.

The function writes a sidecar status file to **PCP\_IMPORTRUN\_DIR** (typically */run/pmimport*) named after *tool*. The file is a simple *key=value* text format containing a subset of the following fields:

- **pid=**

  The process ID of the import tool, written only when the **PMI\_PROCESS** flag was passed to [**pmiStart**(3)](/pmiStart/3.md). Long-running daemons should use this flag so that **pmdapmimport**(1) can detect and suppress stale entries left by an unclean exit. One-shot tools (e.g. those invoked periodically from a cron job) should omit the flag; their sidecar files persist between invocations and are always considered live.

- **version=**

  The *version* string supplied by the caller (skipped if NULL or empty).

- **args=**

  The *args* string supplied by the caller (skipped if NULL or empty). Typically a summary of the subsystems or data sources being imported, for display by [**pcp**(1)](/pcp/1.md).

- **archive=**

  The *archive* base path supplied by the caller (skipped if NULL or empty).

The sidecar file is removed automatically when [**pmiEnd**(3)](/pmiEnd/3.md) is called, so no explicit cleanup is required on a clean exit.

**pmiSetImportProgram** should be called once after [**pmiStart**(3)](/pmiStart/3.md) and before the first call to [**pmiWrite**(3)](/pmiWrite/3.md). Calling it again with updated arguments (e.g. after an archive rotation) is permitted and overwrites the existing sidecar file.

## DIAGNOSTICS

Returns zero on success. **PM\_ERR\_NOCONTEXT** is returned if there is no current import context. **PM\_ERR\_CONV** is returned if *tool* is NULL or empty. Any error opening or writing the sidecar file causes the corresponding negated [**errno**(3)](/errno/3.md) value to be returned.

## FILES

- *$PCP\_IMPORTRUN\_DIR/\<tool\>*

  Sidecar status file for the named import tool.

## SEE ALSO

[**LOGIMPORT**(3)](/LOGIMPORT/3.md), [**pcp**(1)](/pcp/1.md), **pmdapmimport**(1), [**pmiEnd**(3)](/pmiEnd/3.md), [**pmiErrStr**(3)](/pmiErrStr/3.md), [**pmiStart**(3)](/pmiStart/3.md), [**pmiWrite**(3)](/pmiWrite/3.md) and [**pmiWriteNow**(3)](/pmiWriteNow/3.md).