1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
|
'\"macro stdmacro
.\"
.\" Copyright (c) 2000-2004 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 PMDAINSTANCE 3 "PCP" "Performance Co-Pilot"
.SH NAME
\f3pmdaInstance\f1 \- return instance descriptions for a PMDA
.SH "C SYNOPSIS"
.ft 3
#include <pcp/pmapi.h>
.br
#include <pcp/impl.h>
.br
#include <pcp/pmda.h>
.sp
.ad l
.hy 0
.in +8n
.ti -8n
int pmdaInstance(pmInDom \fIindom\fP, int \fIinst\fP, char *\fIname\fP, __pmInResult\ **\fIresult\fP, pmdaExt\ *\fIpmda\fP);
.sp
.in
.hy
.ad
cc ... \-lpcp_pmda \-lpcp
.ft 1
.SH DESCRIPTION
.B pmdaInstance
uses the standard
.BR PMDA (3)
data structures to return information concerning the instance domain
.IR indom .
.PP
The
.I result
structure is constructed by
.B pmdaInstance
and will contain one or more instance names and/or identifiers as specified by
the
.I inst
and
.I name
arguments.
.PP
If
.I inst
has the value
.B PM_IN_NULL
and
.I name
is a null string,
.I result
will contain all the instances names and identifiers in the instance domain.
.PP
If
.I inst
is
.B PM_IN_NULL
but
.I name
is the name of an instance in the instance domain
.IR indom ,
then
.I result
will contain the instance identifier for instance
.IR name .
Note that if
.I name
contains no spaces, partial matching up to the first space in the
instance name is performed, i.e.
.RB `` 1 ''
will match instance name
.RB `` 1
.BR minute ''.
If
.I name
contains an embedded space, then no partial matching is performed and
.I name
should match one of the instance names exactly.
.PP
If
.I name
is a null string but
.I inst
is an instance identifier in the instance domain
.IR indom ,
then
.I result
will contain the name for instance
.IR inst .
The
.I result
structure is allocated with
.BR malloc (3)
and should be released by the caller with
.BR free (3).
.SH DIAGNOSTICS
If any errors occur during the execution of
.BR pmdaInstance ,
the
.I result
structure is deallocated. If the instance domain
.I indom
is not supported by the PMDA,
.B pmdaInstance
will return
.BR PM_ERR_INDOM .
.PP
If the
.I inst
or
.I name
does not correspond to any instances in the
.I indom
domain,
.B pmdaInstance
will return
.BR PM_ERR_INST .
.SH CAVEAT
The PMDA must be using
.B PMDA_INTERFACE_2
or later, as specified in the call to
.BR pmdaDSO (3)
or
.BR pmdaDaemon (3).
.PP
Because of optional partial matching up to the first space in the instance
name, the
.B PMDA
developer should ensure that if instance names are allowed to have
spaces, the names are unique up to the first space.
.SH SEE ALSO
.BR malloc (3),
.BR PMAPI (3),
.BR PMDA (3)
and
.BR pmGetInDom (3).
|
