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

# pmiGetHandle(3)

define a handle for a metric-instance pair

## NAME

**pmiGetHandle** - define a handle for a metric-instance pair

## C SYNOPSIS

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

**int pmiGetHandle(const char \****name***, const char \****instance***);**

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

## Perl SYNOPSIS

**use PCP::LogImport;**

**$***handle* **= pmiGetHandle($***name***, $***instance***);**

## Python SYNOPSIS

**from pcp import pmi**

*handle* **= log.pmiGetHandle(***name***,** *instance***)**

## DESCRIPTION

As part of the Performance Co-Pilot Log Import API (see [**LOGIMPORT**(3)](/LOGIMPORT/3.md)), **pmiGetHandle** creates a handle for a given metric and instance.  The handle is returned as the value from the **pmiGetHandle** call and can be used in subsequent calls to [**pmiPutValueHandle**(3)](/pmiPutValueHandle/3.md).

The metric's *name* should match one defined earlier in a call to [**pmiAddMetric**(3)](/pmiAddMetric/3.md).

For singular metrics (those defined with an instance domain of **PM\_INDOM\_NULL**), the *instance* should be NULL or an empty string, otherwise *instance* should match the name of an instance defined earlier in a call to [**pmiAddInstance**(3)](/pmiAddInstance/3.md) for the metric's instance domain.

When combined with [**pmiPutValueHandle**(3)](/pmiPutValueHandle/3.md), the use of handles provide a performance improvement over the alternative lookup for a metric name and an instance name for each data value that is required for [**pmiPutValue**(3)](/pmiPutValue/3.md).

## DIAGNOSTICS

On failure **pmiGetHandle** returns 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), [**pmiAddInstance**(3)](/pmiAddInstance/3.md), [**pmiAddMetric**(3)](/pmiAddMetric/3.md), [**pmiErrStr**(3)](/pmiErrStr/3.md) and [**pmiPutValueHandle**(3)](/pmiPutValueHandle/3.md).