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

# pmiAddInstance(3)

add an element to an instance domain in a LOGIMPORT context

## NAME

**pmiAddInstance** - add an element to an instance domain in a LOGIMPORT context

## C SYNOPSIS

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

**int pmiAddInstance(pmInDom** *indom***,** **const char \****instance***,** **int** *inst***);**

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

## Perl SYNOPSIS

**use PCP::LogImport;**

**pmiAddInstance($***indom***, $***instance***, $***inst***);**

## Python SYNOPSIS

**from pcp import pmi**

**log.pmiAddInstance(***indom***,** *instance***,** *instid***)**

## DESCRIPTION

As part of the Performance Co-Pilot Log Import API (see [**LOGIMPORT**(3)](/LOGIMPORT/3.md)), **pmiAddInstance** adds a new element to the instance domain identified by *indom*.

*indom* would normally be constructed using the **pmInDom\_build** macro, e.g. pmInDom\_build(PMI\_DOMAIN,0) for the first instance domain in the Performance Metrics Domain PMI\_DOMAIN (which is the default for all meta data created by the LOGIMPORT library).

The new instance must have both an external name (*instance*) and an internal instance identifier (*inst*) that is unique across all instances in the *indom* instance domain. There is a special \`\`uniqueness rule'' for *instance* that is imposed by [**pmLookupInDom**(3)](/pmLookupInDom/3.md), namely that the external instance name must be unique in the leading non-space characters, e.g. the instance names \`\`foo'' and \`\`foo bar'' are considered the same by this rule and not allowed in the same instance domain, but \`\`foo'' and \`\`foobar'' would be allowed.

Once defined, the external instance name can be used in calls to [**pmiGetHandle**(3)](/pmiGetHandle/3.md) and/or [**pmiPutValue**(3)](/pmiPutValue/3.md) with the name of a metric defined over the same instance domain.

## DIAGNOSTICS

**pmiAddInstance** returns zero on success else a negative value that can be turned into an error message by calling [**pmiErrStr**(3)](/pmiErrStr/3.md).

## SEE ALSO

[**LOGIMPORT**(3)](/LOGIMPORT/3.md), [**pmiAddMetric**(3)](/pmiAddMetric/3.md), [**pmiErrStr**(3)](/pmiErrStr/3.md), [**pmiGetHandle**(3)](/pmiGetHandle/3.md), [**pmiPutValue**(3)](/pmiPutValue/3.md), [**pmiPutText**(3)](/pmiPutText/3.md), [**pmiPutLabel**(3)](/pmiPutLabel/3.md) and [**pmLookupInDom**(3)](/pmLookupInDom/3.md).