Debian 3.9.10debian/3.9.10debian

1 files changed, 110 insertions, 0 deletions

diff --git a/man/man3/mmv_stats_init.3 b/man/man3/mmv_stats_init.3
new file mode 100644
index 0000000..216ed02
--- /dev/null
+++ b/man/man3/mmv_stats_init.3
@@ -0,0 +1,110 @@
+'\"macro stdmacro
+.\"
+.\" Copyright (c) 2013 Red Hat.
+.\" 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_STATS_INIT 3 "" "Performance Co-Pilot"
+.SH NAME
+\f3mmv_stats_init\f1 - create and initialize Memory Mapped Value file
+.SH "C SYNOPSIS"
+.ft 3
+#include <pcp/pmapi.h>
+.br
+#include <pcp/mmv_stats.h>
+.sp
+.ad l
+.hy 0
+.in +8n
+.ti -8n
+void *mmv_stats_init(const char *\fIname\fP, int \fIcluster\fP, mmv_stats_flags_t\ \fIflags\fP, const\ mmv_metric_t\ *\fIstats\fP, int\ \fInstats\fP, mmv_indom_t\ *\fIindoms\fP, int\ \fInindoms\fP);
+.sp
+.in
+.hy
+.ad
+cc ... \-lpcp_mmv \-lpcp
+.ft 1
+.SH DESCRIPTION
+.P
+\f3mmv_stats_init\f1 creates and initializes the content of the 
+\f2MMV\f1(5) file, returning a handle that is used in subsequent
+MMV API calls.
+.P
+\f3mmv_stats_stop\f1 performs an orderly shutdown of the mapping
+handle returned by an earlier initialization call.
+.P
+The file is created in the $PCP_TMP_DIR/mmv directory, \f2name\f1
+argument is expected to be a basename of the file, not the full path.
+The metadata content of the file does not change after the file has
+been created. 
+.P
+The old file is removed unconditionally unless there was an error.
+.P
+\f2cluster\f1 is the preferred MMV PMDA cluster ID to be used for
+the metrics originating from this call to \f3mmv_stats_init\f1.
+The \f2flags\f1 provide additional control over the behaviour
+of the MMV PMDA - e.g. use of MMV_FLAG_PROCESS will ensure values
+are only exported when the instrumented application is running \-
+this is verified on each request for new values.
+.P
+\f2stats\f1 is the array of \f3mmv_metric_t\f1 elements of length
+\f2nstats\f1. Each element of the array describes one PCP metric.
+.P
+.nf
+        typedef struct {
+            char name[MMV_NAMEMAX];     /* Name of the metric */
+            __uint32_t item;            /* Item component of PMID */
+            mmv_metric_type_t type;     /* Type of the metric */
+            mmv_metric_sem_t semantics; /* Semantics of the metric */
+            pmUnits dimension;          /* Dimensions (TIME,SPACE,etc) */
+            __uint32_t indom;           /* Instance domain identifier */
+            char *shorttext;            /* Optional, one-line help */
+            char *helptext;             /* Optional, full help text */
+        } mmv_metric_t;
+.fi
+.P
+If \f3indom\f1 is not zero and not PM_INDOM_NULL, then the metric has
+multiple values and there must be a corresponding \f2indom\f1 entry
+in the \f2indom\f1 list (uniquely identified by \f3serial\f1 number).
+.P
+The \f2stats\f1 array cannot contain any elements which have no name -
+this is considered an error and no metrics will be exported in this case.
+.P
+\f2indoms\f1 is the array of \f3mmv_indom_t\f1 elements of length
+\f2nindoms\f1. Each element of the array describes one PCP instance
+domain.
+.P
+.nf
+        typedef struct {
+            __int32_t internal;
+            char external[MMV_NAMEMAX];
+        } mmv_instances_t;
+
+        typedef struct {
+            __uint32_t serial;          /* Unique serial number */
+            __uint32_t count;           /* Number of instances */
+            mmv_instances_t *instances; /* Internal/external IDs */
+            char *shorttext;            /* Short help text */
+            char *helptext;             /* Long help text */
+        } mmv_indom_t;
+.fi
+.P
+.SH RETURNS
+The function returns the address of the memory mapped region on success or
+NULL on failure.
+.SH SEE ALSO
+.BR mmv_inc_value (3),
+.BR mmv_lookup_value_desc (3)
+and
+.BR mmv (5).