Fix: libsquashfs: add sqfs_free() function

On systems like Windows, the dynamic library and applications can
easily end up being linked against different runtime libraries, so
applications cannot be expected to be able to free() any malloc'd
pointer that the library returns.

This commit adds an sqfs_free function so the application can pass
pointers back to the library to call the correct free() implementation.

Signed-off-by: David Oberhollenzer <david.oberhollenzer@sigma-star.at>

1 files changed, 43 insertions, 0 deletions

diff --git a/include/sqfs/predef.h b/include/sqfs/predef.h
index 55ccc86..3254186 100644
--- a/include/sqfs/predef.h
+++ b/include/sqfs/predef.h
@@ -156,4 +156,47 @@ static SQFS_INLINE void *sqfs_copy(const void *obj)
 	return NULL;
 }
 
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief Free a block of memory created by the squashfs library
+ *
+ * Some objects in the squashfs library allocate temporary chunks of memory
+ * and return pointers to them, with the expectation that the user takes care
+ * of freeing them memory again.
+ *
+ * In the past this worked without hitches, because most sane operating systems
+ * have a single, global C library that everything is linked against. On
+ * systems like Windows that have a huge fragmentation of runtime libraries
+ * this fails, because the library and application can easily end up linked
+ * against different runtime libraries, making it impossible for the program
+ * to free the memory.
+ *
+ * To re-create the same situation on Linux, one would have to link a program
+ * and the squashfs library dynamically, while linking at least one of them
+ * statically against the C runtime, or intentionally linking against two
+ * different runtimes.
+ *
+ * This function mitigates the arising problem by exposing the free() function
+ * of the libraries runtime to the application, so it can propperly release
+ * memory again to the correct heap.
+ *
+ * To maintain API/ABI compatibillity, it is guaranteed that for all versions
+ * of libsquashfs with major version 1, this function does nothing other than
+ * call free() on the C runtime that the library was linked against. If just
+ * calling free() works on your system, it will continue to work, and older
+ * application will continue to work with newer versions of libsquashfs 1.x.
+ * Going forward, new applications using libsquashfs should use this function
+ * instead for better portabillity.
+ *
+ * @param ptr A pointer to a memory block returned by a libsquashfs function.
+ */
+SQFS_API void sqfs_free(void *ptr);
+
+#ifdef __cplusplus
+}
+#endif
+
 #endif /* SQFS_PREDEF_H */