Add header with declarations for the sqfs_xattr_writer_t

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

1 files changed, 147 insertions, 0 deletions

diff --git a/include/sqfs/xattr_writer.h b/include/sqfs/xattr_writer.h
new file mode 100644
index 0000000..5b18659
--- /dev/null
+++ b/include/sqfs/xattr_writer.h
@@ -0,0 +1,147 @@
+/* SPDX-License-Identifier: LGPL-3.0-or-later */
+/*
+ * xattr_writer.h - This file is part of libsquashfs
+ *
+ * Copyright (C) 2019 David Oberhollenzer <goliath@infraroot.at>
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Lesser General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+#ifndef SQFS_XATRR_WRITER_H
+#define SQFS_XATRR_WRITER_H
+
+#include "sqfs/predef.h"
+
+/**
+ * @file xattr_writer.h
+ *
+ * @brief Contains declarations for the @ref sqfs_xattr_writer_t.
+ */
+
+/**
+ * @struct sqfs_xattr_writer_t
+ *
+ * @brief Abstracts writing of extended attributes to a SquashFS filesystem.
+ *
+ * This data structure provides a simple, abstract interface to recording
+ * extended attributes that hads out 32 bit tokens required for inodes to
+ * refere to them.
+ *
+ * Use @ref sqfs_xattr_writer_begin to start a block of key-value pairs, then
+ * add the individual pairs with @ref sqfs_xattr_writer_add and finaly use
+ * @ref sqfs_xattr_writer_end which returns the required token.
+ *
+ * Finally, use @ref sqfs_xattr_writer_flush to have the extended attributes
+ * written to disk.
+ *
+ * The writer internally takes care of propper deduplication and packaging
+ * everything up in compressed meta data blocks in the multi-level hierarchy
+ * used by SquashFS. See @ref sqfs_xattr_reader_t for a brief overview on how
+ * SquashFS stores extended attributes.
+ */
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief Create an xattr writer instance.
+ *
+ * @memberof sqfs_xattr_writer_t
+ *
+ * @return A pointer to a new xattr writer, NULL on allocation failure.
+ */
+SQFS_API sqfs_xattr_writer_t *sqfs_xattr_writer_create(void);
+
+/**
+ * @brief Destroy an xattr writer instance and free all memory it used.
+ *
+ * @memberof sqfs_xattr_writer_t
+ *
+ * @param xwr A pointer to an xattr writer instance.
+ */
+SQFS_API void sqfs_xattr_writer_destroy(sqfs_xattr_writer_t *xwr);
+
+/**
+ * @brief Begin recording a block of key-value pairs.
+ *
+ * @memberof sqfs_xattr_writer_t
+ *
+ * Use @ref sqfs_xattr_writer_add to add the individual pairs. Call
+ * @ref sqfs_xattr_writer_end when you are done.
+ *
+ * @param xwr A pointer to an xattr writer instance.
+ *
+ * @return Zero on success, a negative @ref E_SQFS_ERROR value on failure.
+ */
+SQFS_API int sqfs_xattr_writer_begin(sqfs_xattr_writer_t *xwr);
+
+/**
+ * @brief Add a key-value pair to the current block.
+ *
+ * @memberof sqfs_xattr_writer_t
+ *
+ * @param xwr A pointer to an xattr writer instance.
+ * @param key The xattr key string.
+ * @param value The associated value to store.
+ * @param size The size of the value blob.
+ *
+ * @return Zero on success, a negative @ref E_SQFS_ERROR value on failure.
+ */
+SQFS_API int sqfs_xattr_writer_add(sqfs_xattr_writer_t *xwr, const char *key,
+				   const void *value, size_t size);
+
+/**
+ * @brief Finish a generating a key-value block.
+ *
+ * @memberof sqfs_xattr_writer_t
+ *
+ * This function internally takes care of deduplicating the current block
+ * and generates the coresponding 32 bit xattr token used by SquashFS inodes.
+ * The token it returns can be one it returned previously if the block turns
+ * out to be a duplicate of a previous block.
+ *
+ * @param xwr A pointer to an xattr writer instance.
+ * @param out Returns an ID that has to be set to the inode that the block of
+ *            key-value pairs belongs to.
+ *
+ * @return Zero on success, a negative @ref E_SQFS_ERROR value on failure.
+ */
+SQFS_API int sqfs_xattr_writer_end(sqfs_xattr_writer_t *xwr, sqfs_u32 *out);
+
+/**
+ * @brief Write all recorded key-value pairs to disk.
+ *
+ * @memberof sqfs_xattr_writer_t
+ *
+ * This function takes care of generating the extended attribute tables
+ * used by SquashFS. Call it after you are donew with all other meta data
+ * tables, since SquashFS requires it to be the very last thing in the
+ * file system.
+ *
+ * @param xwr A pointer to an xattr writer instance.
+ * @param file The output file to write the tables to.
+ * @param super The super block to update with the table locations and flags.
+ * @param cmp The compressor to user to compress the tables.
+ *
+ * @return Zero on success, a negative @ref E_SQFS_ERROR value on failure.
+ */
+SQFS_API int sqfs_xattr_writer_flush(sqfs_xattr_writer_t *xwr,
+				     sqfs_file_t *file, sqfs_super_t *super,
+				     sqfs_compressor_t *cmp);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* SQFS_XATRR_WRITER_H */