MAT_VARCREATESTRUCT2(3)

💖 MAT_VARCREATESTRUCT2 💖

okay bestie, this is a page from the Library Functions Manual (section 3, the library-call girlies 🫶), and it's literally all about Mat_VarCreateStruct2 — the little function that builds you a struct variable so you can yeet it into a MAT file. no cap, it's iconic.

---

✨ NAME ✨

Mat_VarCreateStruct2 — Creates a structure variable. that's it, that's the whole job 💅

---

🌸 SYNOPSIS 🌸

#include <matio.h>

matvar_t *
Mat_VarCreateStruct(const char *name, int rank, const size_t *dims,
    const char *const *fields);

yes bestie the header says Mat_VarCreateStruct2 and the prototype says Mat_VarCreateStruct — that's just how the library rolls, we don't question it, we simply vibe 🦋

---

👑 DESCRIPTION 👑

The Mat_VarCreateStruct2() function creates a structure variable named name that can be written to a MAT file. like, it's giving "make me a lil struct, i'll take it from here." main character energy fr fr.

---

💀 RETURN VALUES 💀

• if the structure variable was successfully created, a pointer to the variable is returned. slay 🎀
• otherwise NULL is returned. not slay 😭

and listen — the structure variable pointer should be free'd when no longer needed using Mat_VarFree(). do not forget, bestie, that's a memory leak and we do not do those in this house 🙈

The names of the fields are copied in the function, and thus should be released after calling the function if necessary. The names of the fields has to be a NULL-terminated array. that last bit is important — if you don't terminate your array with NULL, the function just keeps going and going and going 💀

---

🌈 EXAMPLES 🌈

This example program opens a MAT file named by the first argument to the program, and writes a structure named a to the file. let's gooo ✨

#include "matio.h"

int
main(int argc, char **argv)
{
    mat_t    *matfp;
    matvar_t *matvar;
    matvar_t *field;
    const char *fields[3] = {"field1", "field2", NULL};
    double       data1 = 1, data2 = 2;
    size_t       dims[2] = {1, 1};

    matfp = Mat_Open(argv[1], MAT_ACC_RDWR);
    if ( NULL == matfp ) {
        fprintf(stderr, "Error opening MAT file %s0, argv[1]);
        return EXIT_FAILURE;
    }

    dims[0] = 1; dims[1] = 1;
    matvar = Mat_VarCreateStruct2("a", 2, dims, fields);
    if ( NULL == matvar ) {
        Mat_Close(matfp);
        return EXIT_FAILURE;
    }

    field = Mat_VarCreate(NULL, MAT_C_DOUBLE, MAT_T_DOUBLE, 2, dims, &data1,
                MAT_F_DONT_COPY_DATA);
    Mat_VarSetStructFieldByName(matvar, "field1", 0, field);

    field = Mat_VarCreate(NULL, MAT_C_DOUBLE, MAT_T_DOUBLE, 2, dims, &data2,
                MAT_F_DONT_COPY_DATA);
    Mat_VarSetStructFieldByName(matvar, "field2", 0, field);

    Mat_VarWrite(matfp, matvar, MAT_COMPRESSION_NONE);
    Mat_VarFree(matvar);

    Mat_Close(matfp);
    return EXIT_SUCCESS;
}

okay real talk, notice the flow: open the file with Mat_Open using MAT_ACC_RDWR, bail out with EXIT_FAILURE if it's NULL, then Mat_VarCreateStruct2("a", 2, dims, fields) to make the struct, fill each field with Mat_VarCreate + Mat_VarSetStructFieldByName, write it with Mat_VarWrite and MAT_COMPRESSION_NONE, free it with Mat_VarFree, close with Mat_Close, and return EXIT_SUCCESS. it's literally a whole routine and it ate 💅

also yes, bestie, the format string in that fprintf line is exactly as it appears above — I copied it character for character because that's the rule and I don't make the rules, I just follow them like the good student I am 🧚

---

💜 SEE ALSO 💜

• Mat_VarCreate(3)
• Mat_VarSetStructFieldByName(3)

---

and that's the whole page!! this one came from the Debian build of the manual, dated January 5, 2026, so if you see a timestamp floating around that's why 🍓 stay hydrated, free your matvar_t pointers, and go write some MAT files bestie 💖✨👑