MMV_STATS_INIT(3)

💖 MMV_STATS_INIT 💖

okay bestie, welcome to the Library Functions Manual entry for mmv_stats_init and mmv_stats2_init — yes those are the whole names, no cap. sit down, hydrate, we're building a Memory Mapped Value file together and it's gonna be iconic ✨

---

🌸 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

link it like that and you're slaying, fr fr 💅

---

🦋 DESCRIPTION 🦋

⚠️ heads up bestie — these functions are deprecated, okay? go look at mmv_stats_registry(3) instead. i'm not gatekeeping, i'm literally telling you where the cool kids hang out now.

so mmv_stats_init creates and initializes the content of the MMV(5) file, and it hands you back a handle that you'll use in all the later MMV API calls. like a little friendship bracelet for your metrics 🫶

mmv_stats2_init is the exact same energy as mmv_stats_init, except it gives you an option for longer metric and instance names. glow up.

and mmv_stats_stop — which you're probably wondering about since it's not up in the synopsis — does an orderly shutdown of the mapping handle that an earlier initialization call gave you. closing the loop, very demure, very mindful.

the file gets created in the $PCP_TMP_DIR/mmv directory. and listen: the name argument is expected to be a basename of the file, not the full path. don't be out here passing whole paths, it's not that kind of party. also the metadata content of the file does not change after the file has been created. it's set, it's done, periodt.

the old file is removed unconditionally unless there was an error. unconditional. no negotiating. 💀

---

the args, one by one 👑

cluster is the preferred MMV PMDA cluster ID to be used for the metrics originating from this call to mmv_stats_init.

flags gives you additional control over how the MMV PMDA behaves — for example, using MMV_FLAG_PROCESS will ensure values are only exported when the instrumented application is running, and this gets verified on each request for new values. every single time. it's checking. 👀

---

stats — the metrics array 🍓

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 — the metrics array, but longer 🌈

stats2 is the array of mmv_metric2_t elements of length nstats2. each element describes one PCP metric, and the only difference from stats is that the restriction on name length got lifted (it used to be 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). no matching entry, no vibe. 🧚

🚨 important: the stats and stats2 arrays cannot contain any elements which have no name. that's considered an error, and in that case no metrics will be exported at all. zero. nada. so name your metrics bestie, i'm begging 😭

---

indoms — the instance domains 💜

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 — the instance domains, but longer ⭐

indoms2 is the array of mmv_indom2_t elements of length nindoms2. each element describes one PCP instance domain, and the only difference from indoms is that the restriction on external instance name lengths got lifted (it used to be 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 ✨

on success, these functions return the address of the memory mapped region. slay. 🎉

on failure, they return NULL and errno is set to a value suitable for decoding with strerror(3). so if you get NULL, go read your errno, it's literally trying to tell you something. communication queen. 🙈

---

👑 SEE ALSO 👑

• mmv_stats_registry(3)
• mmv_lookup_value_desc(3)
• mmv_inc_value(3)
• strerror(3)
• mmv(5)

---

and that's the whole page, bestie!! this came to you from Performance Co-Pilot, on the MMV_STATS_INIT(3) manual page — go forth and map those values, you absolute main character 💖✨🦋🌸💅