Debian 3.9.10debian/3.9.10debian

1 files changed, 148 insertions, 0 deletions

diff --git a/man/man3/pmdainstance.3 b/man/man3/pmdainstance.3
new file mode 100644
index 0000000..8b7fd97
--- /dev/null
+++ b/man/man3/pmdainstance.3
@@ -0,0 +1,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).