NAME

       mmv_stats_init, mmv_stats2_init - create and initialize Memory Mapped Value file

C SYNOPSIS

       #include <pcp/pmapi.h>
       #include <pcp/mmv_stats.h>

       void *mmv_stats_init(const char *name, int cluster, mmv_stats_flags_t flags,
               const mmv_metric_t *stats, int nstats, mmv_indom_t *indoms, int nindoms);
       void *mmv_stats2_init(const char *name, int cluster, mmv_stats_flags_t flags,
               const mmv_metric2_t *stats2, int nstats2, mmv_indom2_t *indoms2, int nindoms2);

       cc ... -lpcp_mmv -lpcp

DESCRIPTION

       mmv_stats_init  creates and initializes the content of the MMV(5) file, returning a handle
       that is used in subsequent MMV API calls.

       mmv_stats2_init is equivalent to mmv_stats_init except that  it  provides  an  option  for
       longer metric and instance names.

       mmv_stats_stop  performs  an orderly shutdown of the mapping handle returned by an earlier
       initialization call.

       The file is created in the $PCP_TMP_DIR/mmv directory, name 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.

       The old file is removed unconditionally unless there was an error.

       cluster is the preferred MMV PMDA cluster ID to be used for the metrics  originating  from
       this  call  to mmv_stats_init.  The flags 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.

       stats  is  the  array of mmv_metric_t elements of length nstats. Each element of the array
       describes one PCP metric.

               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;

       stats2 is the array of mmv_metric2_t elements of length nstats2. Each element of the array
       describes  one  PCP metric, the only difference to stats is the lifting of the restriction
       on name length (previously MMV_NAMEMAX, which is 64 bytes).

               typedef struct {
                   char *name;                 /* 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;

       If indom is not zero and not PM_INDOM_NULL, then the metric has multiple values and  there
       must  be  a  corresponding  indom  entry  in the indom list (uniquely identified by serial
       number).

       The stats and stats2 arrays cannot contain any elements which  have  no  name  -  this  is
       considered an error and no metrics will be exported in this case.

       indoms  is  the array of mmv_indom_t elements of length nindoms. Each element of the array
       describes one PCP instance domain.

               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;

       indoms2 is the array of mmv_indom2_t elements of length  nindoms2.  Each  element  of  the
       array  describes one PCP instance domain, and the only difference to indoms is the lifting
       of the restriction on external instance name lengths (previously MMV_NAMEMAX, which is  64
       bytes).

               typedef struct {
                   __int32_t internal;
                   char *external;
               } mmv_instances2_t;

               typedef struct {
                   __uint32_t serial;           /* Unique serial number */
                   __uint32_t count;            /* Number of instances */
                   mmv_instances2_t *instances; /* Internal/external IDs */
                   char *shorttext;             /* Short help text */
                   char *helptext;              /* Long help text */
               } mmv_indom2_t;

RETURN VALUES

       These  functions  return  the address of the memory mapped region on success.  On failure,
       NULL is returned and errno is set to a value suitable for decoding with strerror(3).

SEE ALSO

       mmv_inc_value(3), mmv_lookup_value_desc(3), strerror(3) and mmv(5).