'\"! tbl | nroff \-man
'\"macro stdmacro
.\"
.\" Copyright (c) 2009 Max Matveev
.\" Copyright (c) 2009 Aconex.  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 MMV 5 "" "Performance Co-Pilot"
.SH NAME
\f3mmv\f1 \- Memory Mapped Values for Performance Co-Pilot
.SH SYNOPSIS
.I $PCP_TMP_DIR/mmv/<file>
.SH DESCRIPTION
The files in \f2$PCP_TMP_DIR/mmv\f1 are generated by 
\f2mmv_stats_init\f1() function from \f3libpcp_mmv\f1 library. There could
be multiple files in this directory, each file representing a single source
of the performance metrics. The metrics are harvested by the \f2mmv\f1 PMDA
which exports them to the rest of the Performance Co-Pilot infrastructure.
.SH FILE FORMAT
Each file starts with the following header:
.TS
box,center;
c | c | c
n | n | l.
Offset	Length	Name
_
0	4	tag == "MMV\\0"
_
4	4	Version
_
8	8	Generation 1
_
16	8	Generation 2
_
24	4	Number of TOC entries
_
28	4	Flags
_
32	4	Process identifier (PID)
_
36	4	Cluster identifier
.TE
.PP
.PP
The generation numbers are timestamps at the time of file
creation, and must match for the file to be considered by
the MMV PMDA.
.PP
The flags can specify ways in which the client would like
the MMV PMDA to behave - e.g. the MMV_FLAG_PROCESS flag
specifies that only if the process identified by PID is
currently running should those values be exported.
.PP
Finally, if set, the cluster identifier is a hint to the MMV
PMDA as to what cluster should be used with this application
when forming the individual metric identifiers.
A performance metric identifier (see \f2PMDA\f1(3)) consists of
the PMDA domain number, the cluster number, and the individual
item numbers described in the Metrics section.
.PP
The header is followed by at least 2 TOC sections:
one section for metrics and another for values.
The TOC section has the following format:
.TS
box,center;
c | c | c
n | n | l.
Offset	Length	Value
_
0	4	Section Type (see \f2mmv_stats.h\f1)
_
4	4	Number of entries in the section
_
8	8	Section's offset from the start of the file
.TE
.PP
.PP
The section types are:
.IP
1:
Indoms (instance domain definitions)
.IP
2:
Instances
.IP
3:
Metrics (metric definitions)
.IP
4:
Values
.IP
5:
String
.PP
The only mandatory sections are Metrics and Values.
Indoms and Instances sections only appear if there are metrics with
multiple instances.
String sections only appear if there are metrics with string values,
or when Metrics or Indoms are defined with help text.
.PP
The entries in the Indoms section have the following format:
.TS
box,center;
c | c | c
n | n | l.
Offset	Length	Value
_
0	4	Unique serial number for this domain
_
4	4	Number of entries in the domain
_
8	8	Offset to first instance
_
16	8	Short help text offset
_
24	8	Long help text offset
.TE
.PP
.PP
The entries in the Instances section have the following format:
.TS
box,center;
c | c | c
n | n | l.
Offset	Length	Value
_
0	8	Offset into the indom section
_
8	4	Unused padding (zero filled)
_
12	4	Internal instance identifier
_
16	64	External instance identifier
.TE
.PP
.PP
The entries in the Metrics section have the following format:
.TS
box,center;
c | c | c
n | n | l.
Offset	Length	Value
_
0	64	Metric Name
_
64	4	Metric Item (see \f2PMDA\f1(3))
_
68	4	Metric Type (see \f2mmv_stats.h\f1)
_
72	4	Semantics (see \f2PMAPI\f1(3))
_
76	4	Dimensions (see \f2PMAPI\f1(3))
_
80	4	Instance Domain ID
_
84	4	Unused padding (zero filled)
_
88	8	Short help text offset
_
96	8	Long help text offset
.TE
.PP
.PP
The entries in the Values section have the following format:
.TS
box,center;
c | c | c
n | n | l.
Offset	Length	Value
_
0	8	\f3pmAtomValue\f1 (see \f2PMAPI\f1(3))
_
8	8	Extra space for STRING and ELAPSED
_
16	8	Offset into the Metrics section
_
24	8	Offset into the Instances section
.TE
.PP
.PP
Each entry in the strings section is a 256 byte character array,
containing a single NULL-terminated character string.
So each string has a maximum length of 256 bytes, which includes
the terminating NULL.
.PP
.SH SEE ALSO
.BR PCPIntro (1),
.BR PMAPI (3),
.BR mmv_stats_init (3),
.BR pcp.conf (5)
and
.BR pcp.env (5).