# mmv_stats_registry

## NAME



           **mmv_stats_registry** , **mmv_stats_start** , **mmv_stats_stop** - Initialize
           the Memory Mapped Value file
    


## C SYNOPSIS



           **#include <pcp/pmapi.h>**
           **#include <pcp/mmv_stats.h>**
    
           **mmv_registry_t *mmv_stats_registry(const char ***_file_**, int** _cluster_**,**
                                              **mmv_stats_flags_t** _flags_**);**
           **void *mmv_stats_start(mmv_registry_t ***_registry_**);**
           **void mmv_stats_stop(const char ***_fname_**, void ***_addr_**);**
    
           **cc ... -lpcp_mmv -lpcp**
    


## DESCRIPTION



           **mmv_stats_registry** initializes  an  opaque structure that defines
           various aspects of a memory mapped file.  This file  is  used  for
           lightweight interprocess communication between an instrumented ap‐
           plication and _pmdammv_(1).
    
           The  **mmv_stats_registry** interface is used to allocate a registry,
           and allows the _name_ of the _MMV_(5) file, the _cluster_ identifier and
           the _flags_ (if any) to be set.  It returns a handle that is used in
           subsequent MMV API calls when adding  metrics,  indoms,  instances
           and labels to the registry - before actually creating the file.
    
           **mmv_stats_start** is the call that creates the _MMV_(5) file with the
           handle that returns **mmv_stats_registry**.   It  returns  the  mapped
           memory   handle   used  in  subsequent  MMV  API  calls,  such  as
           mmv_inc_value(3).
    
           **mmv_stats_stop** performs an orderly shutdown of the mapping  handle
           returned by an earlier initialization call and also frees the reg‐
           istry structure.
    
           The  combination  of **mmv_stats_registry** and **mmv_stats_start** do the
           same as the deprecated calls **mmv_stats2_init**.  However,  now,  one
           should  first  call **mmv_stats_registry** and then the API calls that
           add instances, indoms, metrics and labels.  In this way, there  is
           no need to know in advance which version of the MMV(1|2|3) mapping
           will be used as it is calculated automatically.
    
           The  file  is  created in the _$PCP_TMP_DIR/mmv_ directory, the _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  the  originates the call **mmv_stats_start**.  The _flags_ pro‐
           vide 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.
    
           The next sections explain how to add  metrics,  indoms,  instances
           and labels.
    


## ADD METRICS



           **int mmv_stats_add_metric(mmv_registry_t *registry,**
                                    **const char ***_name_**, int** _item_**,**
                                    **mmv_metric_type_t** _type_**,**
                                    **mmv_metric_sem_t** _sem_**, pmUnits** _units_**,**
                                    **int** _serial_**, const char ***_shorthelp_**,**
                                    **const char ***_longhelp_**);**
    
           When  adding  a  metric,  internally it is being handled using the
           next struct.  _sem_ match in the struct is semantics. _units_ match in
           the struct is dimension. _serial_ match in the struct is indom.
    
                   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;
    


## ADD INDOMS



           **int mmv_stats_add_indom(mmv_registry_t ***_registry_**, int** _serial_**,**
                                   **const char ***_shorthelp_**,**
                                   **const char ***_longhelp_**);**
    
           When adding an indom, internally it is  being  handled  using  the
           next struct.
    
                   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;
    


## ADD INSTANCES



           **int mmv_stats_add_instance(mmv_registry_t ***_registry_**, int** _serial_**,**
                                      **int** _instid_**, const char ***_instname_**);**
    
           When  adding an instance, internally it is being handled using the
           next struct.  _instid_ match in the struct is internal  while  _inst‐_
           _name_ is external.
    
                   typedef struct {
                       __int32_t internal;
                       char *external;
                   } mmv_instances2_t;
    
           It  is  worth  mentioning that if the indom of the instance is not
           found it returns an error.
    


## ADD LABELS



           **int mmv_stats_add_registry_label(mmv_registry_t ***_registry_**,**
                                            **const char ***_name_**,**
                                            **const char ***_value_**,**
                                            **mmv_value_type_t** _type_**,**
                                            **int** _optional_**);**
    
           **int mmv_stats_add_indom_label(mmv_registry_t ***_registry_**,**
                                         **int** _serial_**, const char ***_name_**,**
                                         **const char ***_value_**,**
                                         **mmv_value_type_t** _type_**,**
                                         **int** _optional_**);**
    
           **int mmv_stats_add_metric_label(mmv_registry_t ***_registry_**, int** _item_**,**
                                          **const char ***_name_**,**
                                          **const char ***_value_**,**
                                          **mmv_value_type_t** _type_**,**
                                          **int** _optional_**);**
    
           **int mmv_stats_add_instance_label(mmv_registry_t ***_registry_**,**
                                            **int** _serial_**, int** _instid_**,**
                                            **const char ***_name_**,**
                                            **const char ***_value_**,**
                                            **mmv_value_type_t** _type_**,**
                                            **int** _optional_**);**
    
           _registry_ is the handle obtained from **mmv_stats_registry**. _name_  and
           _value_ are the strings that will form the label.
    
           _type_  specifies  the  value  type  that  can  be: MMV_STRING_TYPE,
           MMV_NUMBER_TYPE, MMV_BOOLEAN_TYPE,  MMV_NULL_TYPE,  MMV_ARRAY_TYPE
           and MMV_MAP_TYPE.
    
           At  the  moment  there is a simple check of the correctness of the
           value.  After adding a label, it is called a function to verify if
           it is correct.
    
           Additionally, if _optional_ is set, it  is  added  the  flag  PM_LA‐
           BEL_OPTIONAL.
    
           _serial_ is the serial of the indom when adding an indom or instance
           label.   _item_ is the metric identifier when adding a metric label.
           Finally, when adding a registry label it is not necessary to  give
           the cluster id because it will be taken from the internal registry
           struct already created.
    
           **mmv_stats_add_registry_label** adds a PM_LABEL_CLUSTER.
    
           **mmv_stats_add_indom_label** adds a PM_LABEL_INDOM.
    
           **mmv_stats_add_metric_label** adds a PM_LABEL_ITEM.
    
           **mmv_stats_add_instance_label** adds a PM_LABEL_INSTANCES.
    


## RETURN VALUES



            When adding metrics, indoms, instances and labels, if correct re‐
           turns 0
            and  if  not it returns an errno code. The other functions return
           the address
            of the memory mapped region on success. On failure, NULL  is  re‐
           turned and
            _errno_ is set to a value suitable for decoding with strerror(3).
    


* * *