# mmv_stats_init

## 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



           **Note: these functions are deprecated - see mmv_stats_registry(3).**
    
           **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_  argu‐
           ment  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  dif‐
           ference  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_metric2_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  ex‐
           ported 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).
    


* * *