1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
|
/* 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
*
* @implements sqfs_object_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
*
* @param flags Currently must be zero or the function fails.
*
* @return A pointer to a new xattr writer, NULL on allocation failure.
*/
SQFS_API sqfs_xattr_writer_t *sqfs_xattr_writer_create(sqfs_u32 flags);
/**
* @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.
* @param flags Currently must be zero, or the function will fail.
*
* @return Zero on success, a negative @ref SQFS_ERROR value on failure.
*/
SQFS_API int sqfs_xattr_writer_begin(sqfs_xattr_writer_t *xwr, sqfs_u32 flags);
/**
* @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 SQFS_ERROR value on failure.
*/
SQFS_API int sqfs_xattr_writer_add_kv(sqfs_xattr_writer_t *xwr,
const char *key,
const void *value, size_t size);
/**
* @brief Add a key-value struct to the current block.
*
* @memberof sqfs_xattr_writer_t
*
* To add a key string and value blob, use @ref sqfs_xattr_writer_add_kv
*
* @param xwr A pointer to an xattr writer instance.
* @param ent A pointer to a combined key-value pair.
*
* @return Zero on success, a negative @ref SQFS_ERROR value on failure.
*/
SQFS_API int sqfs_xattr_writer_add(sqfs_xattr_writer_t *xwr,
const sqfs_xattr_t *ent);
/**
* @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 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 SQFS_ERROR value on failure.
*/
SQFS_API int sqfs_xattr_writer_flush(const 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 */
|
