'\"macro stdmacro
.\"
.\" Copyright (c) 2000 Silicon Graphics, Inc.  All Rights Reserved.
.\"
.\" This program is free software; you can redistribute it and/or modify it
.\" under the terms of the GNU General Public License as published by the
.\" Free Software Foundation; either version 2 of the License, or (at your
.\" option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful, but
.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
.\" or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
.\" for more details.
.\"
.\"
.TH PMNAMEINDOM 3 "PCP" "Performance Co-Pilot"
.SH NAME
\f3pmNameInDom\f1 \- translate an instance identifier into an instance name
.SH "C SYNOPSIS"
.ft 3
#include <pcp/pmapi.h>
.sp
.nf
int pmNameInDom(pmInDom \fIindom\fP, int \fIinst\fP, char **\fIname\fP);
.fi
.sp
cc ... \-lpcp
.ft 1
.SH DESCRIPTION
.de CR
.ie t \f(CR\\$1\f1\\$2
.el \fI\\$1\f1\\$2
..
For the instance domain
.IR indom ,
in the current
Performance Metrics Application Programming Interface (PMAPI)
context,
locate the instance with the internal instance identifier given
by
.IR inst ,
and return the full external instance identification via
.IR name .
.PP
The value for the instance domain
.I indom
is typically extracted from a
.CR pmDesc
structure, following a call to
.BR pmLookupDesc (3)
for a particular performance metric.
.PP
The space for the value of
.I name
will have been allocated in
.B pmNameInDom
with
.BR malloc (3),
and it is the responsibility of the caller to
.BR free (3)
the space when it is no longer required.
.PP
.B pmNameInDom
returns zero on success.
.SH DIAGNOSTICS
.IP \f3PM_ERR_INDOM\f1
.I indom
is not a valid instance domain identifier
.IP \f3PM_ERR_INST\f1
The instance identifier
.I inst
is not known for the instance domain
.I indom
in the current PMAPI context
.SH SEE ALSO
.BR PMAPI (3),
.BR pmGetConfig (3),
.BR pmGetInDom (3),
.BR pmLookupInDom (3),
.BR pmNameInDomArchive (3),
.BR pcp.conf (5)
and
.BR pcp.env (5).