core: Introduce pointer box firmware for RAII behavior

Signed-off-by: Ian Moffett <ian@mirocom.org>

include/common/ptrbox.h

@@ -0,0 +1,70 @@
+/*
+ * Copyright (c) 2026, Mirocom Laboratories
+ * Provided under the BSD-3 clause
+ *
+ * Abtract:
+ *      This file implements pointer boxes used to provide RAII-like
+ *      allocation behavior.
+ * Author:
+ *      Ian M. Moffett <ian@mirocom.org>
+ */
+
+#ifndef COMMON_PTRBOX_H
+#define COMMON_PTRBOX_H 1
+
+#include <stdint.h>
+#include <stddef.h>
+
+/*
+ * Represents a pointer box entry which stores
+ * a reference to allocated data and a next pointer.
+ *
+ * @data:  Allocated data reference
+ * @next:  Next entry
+ */
+struct ptrbox_entry {
+    void *data;
+    struct ptrbox_entry *next;
+};
+
+/*
+ * Represents a pointer box which holds a list of pointer
+ * box entries
+ *
+ * @head: Pointer box entry list head
+ * @entry_count: Number of entries
+ */
+struct ptrbox {
+    struct ptrbox_entry *head;
+    struct ptrbox_entry *tail;
+    size_t entry_count;
+};
+
+/*
+ * Initialize a pointer box
+ *
+ * @ptrbox: Pointer box to initialize
+ *
+ * Returns zero on success
+ */
+int ptrbox_init(struct ptrbox *ptrbox);
+
+/*
+ * Duplicate a string and store the reference in a pointer box
+ *
+ * @ptrbox: Pointerbox to store reference within
+ * @s:      String to duplicate
+ *
+ * Returns the duplicated string on success, otherwise a value
+ * of NULL on failure.
+ */
+char *ptrbox_strdup(struct ptrbox *ptrbox, const char *s);
+
+/*
+ * Destroy all elements within a pointer box
+ *
+ * @ptrbox: Pointer box to destroy
+ */
+void ptrbox_destroy(struct ptrbox *ptrbox);
+
+#endif  /* !COMMON_PTRBOX_H */