1/*
2 * Copyright (C) 2012 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17#ifndef _LIBSPARSE_SPARSE_H_
18#define _LIBSPARSE_SPARSE_H_
19
20#include <stdbool.h>
21#include <stdint.h>
22
23#ifdef	__cplusplus
24extern "C" {
25#endif
26
27struct sparse_file;
28
29/**
30 * sparse_file_new - create a new sparse file cookie
31 *
32 * @block_size - minimum size of a chunk
33 * @len - size of the expanded sparse file.
34 *
35 * Creates a new sparse_file cookie that can be used to associate data
36 * blocks.  Can later be written to a file with a variety of options.
37 * block_size specifies the minimum size of a chunk in the file.  The maximum
38 * size of the file is 2**32 * block_size (16TB for 4k block size).
39 *
40 * Returns the sparse file cookie, or NULL on error.
41 */
42struct sparse_file *sparse_file_new(unsigned int block_size, int64_t len);
43
44/**
45 * sparse_file_destroy - destroy a sparse file cookie
46 *
47 * @s - sparse file cookie
48 *
49 * Destroys a sparse file cookie.  After destroy, all memory passed in to
50 * sparse_file_add_data can be freed by the caller
51 */
52void sparse_file_destroy(struct sparse_file *s);
53
54/**
55 * sparse_file_add_data - associate a data chunk with a sparse file
56 *
57 * @s - sparse file cookie
58 * @data - pointer to data block
59 * @len - length of the data block
60 * @block - offset in blocks into the sparse file to place the data chunk
61 *
62 * Associates a data chunk with a sparse file cookie.  The region
63 * [block * block_size : block * block_size + len) must not already be used in
64 * the sparse file. If len is not a multiple of the block size the data
65 * will be padded with zeros.
66 *
67 * The data pointer must remain valid until the sparse file is closed or the
68 * data block is removed from the sparse file.
69 *
70 * Returns 0 on success, negative errno on error.
71 */
72int sparse_file_add_data(struct sparse_file *s,
73		void *data, unsigned int len, unsigned int block);
74
75/**
76 * sparse_file_add_fill - associate a fill chunk with a sparse file
77 *
78 * @s - sparse file cookie
79 * @fill_val - 32 bit fill data
80 * @len - length of the fill block
81 * @block - offset in blocks into the sparse file to place the fill chunk
82 *
83 * Associates a chunk filled with fill_val with a sparse file cookie.
84 * The region [block * block_size : block * block_size + len) must not already
85 * be used in the sparse file. If len is not a multiple of the block size the
86 * data will be padded with zeros.
87 *
88 * Returns 0 on success, negative errno on error.
89 */
90int sparse_file_add_fill(struct sparse_file *s,
91		uint32_t fill_val, unsigned int len, unsigned int block);
92
93/**
94 * sparse_file_add_file - associate a chunk of a file with a sparse file
95 *
96 * @s - sparse file cookie
97 * @filename - filename of the file to be copied
98 * @file_offset - offset into the copied file
99 * @len - length of the copied block
100 * @block - offset in blocks into the sparse file to place the file chunk
101 *
102 * Associates a chunk of an existing file with a sparse file cookie.
103 * The region [block * block_size : block * block_size + len) must not already
104 * be used in the sparse file. If len is not a multiple of the block size the
105 * data will be padded with zeros.
106 *
107 * Allows adding large amounts of data to a sparse file without needing to keep
108 * it all mapped.  File size is limited by available virtual address space,
109 * exceptionally large files may need to be added in multiple chunks.
110 *
111 * Returns 0 on success, negative errno on error.
112 */
113int sparse_file_add_file(struct sparse_file *s,
114		const char *filename, int64_t file_offset, unsigned int len,
115		unsigned int block);
116
117/**
118 * sparse_file_add_file - associate a chunk of a file with a sparse file
119 *
120 * @s - sparse file cookie
121 * @filename - filename of the file to be copied
122 * @file_offset - offset into the copied file
123 * @len - length of the copied block
124 * @block - offset in blocks into the sparse file to place the file chunk
125 *
126 * Associates a chunk of an existing fd with a sparse file cookie.
127 * The region [block * block_size : block * block_size + len) must not already
128 * be used in the sparse file. If len is not a multiple of the block size the
129 * data will be padded with zeros.
130 *
131 * Allows adding large amounts of data to a sparse file without needing to keep
132 * it all mapped.  File size is limited by available virtual address space,
133 * exceptionally large files may need to be added in multiple chunks.
134 *
135 * The fd must remain open until the sparse file is closed or the fd block is
136 * removed from the sparse file.
137 *
138 * Returns 0 on success, negative errno on error.
139 */
140int sparse_file_add_fd(struct sparse_file *s,
141		int fd, int64_t file_offset, unsigned int len, unsigned int block);
142
143/**
144 * sparse_file_write - write a sparse file to a file
145 *
146 * @s - sparse file cookie
147 * @fd - file descriptor to write to
148 * @gz - write a gzipped file
149 * @sparse - write in the Android sparse file format
150 * @crc - append a crc chunk
151 *
152 * Writes a sparse file to a file.  If gz is true, the data will be passed
153 * through zlib.  If sparse is true, the file will be written in the Android
154 * sparse file format.  If sparse is false, the file will be written by seeking
155 * over unused chunks, producing a smaller file if the filesystem supports
156 * sparse files.  If crc is true, the crc of the expanded data will be
157 * calculated and appended in a crc chunk.
158 *
159 * Returns 0 on success, negative errno on error.
160 */
161int sparse_file_write(struct sparse_file *s, int fd, bool gz, bool sparse,
162		bool crc);
163
164/**
165 * sparse_file_len - return the length of a sparse file if written to disk
166 *
167 * @s - sparse file cookie
168 * @sparse - write in the Android sparse file format
169 * @crc - append a crc chunk
170 *
171 * Returns the size a sparse file would be on disk if it were written in the
172 * specified format.  If sparse is true, this is the size of the data in the
173 * sparse format.  If sparse is false, this is the size of the normal
174 * non-sparse file.
175 */
176int64_t sparse_file_len(struct sparse_file *s, bool sparse, bool crc);
177
178/**
179 * sparse_file_block_size
180 *
181 * @s - sparse file cookie
182 */
183unsigned int sparse_file_block_size(struct sparse_file *s);
184
185/**
186 * sparse_file_callback - call a callback for blocks in sparse file
187 *
188 * @s - sparse file cookie
189 * @sparse - write in the Android sparse file format
190 * @crc - append a crc chunk
191 * @write - function to call for each block
192 * @priv - value that will be passed as the first argument to write
193 *
194 * Writes a sparse file by calling a callback function.  If sparse is true, the
195 * file will be written in the Android sparse file format.  If crc is true, the
196 * crc of the expanded data will be calculated and appended in a crc chunk.
197 * The callback 'write' will be called with data and length for each data,
198 * and with data==NULL to skip over a region (only used for non-sparse format).
199 * The callback should return negative on error, 0 on success.
200 *
201 * Returns 0 on success, negative errno on error.
202 */
203int sparse_file_callback(struct sparse_file *s, bool sparse, bool crc,
204		int (*write)(void *priv, const void *data, int len), void *priv);
205
206/**
207 * sparse_file_foreach_chunk - call a callback for data blocks in sparse file
208 *
209 * @s - sparse file cookie
210 * @sparse - write in the Android sparse file format
211 * @crc - append a crc chunk
212 * @write - function to call for each block
213 * @priv - value that will be passed as the first argument to write
214 *
215 * The function has the same behavior as 'sparse_file_callback', except it only
216 * iterates on blocks that contain data.
217 *
218 * Returns 0 on success, negative errno on error.
219 */
220int sparse_file_foreach_chunk(struct sparse_file *s, bool sparse, bool crc,
221	int (*write)(void *priv, const void *data, int len, unsigned int block,
222		     unsigned int nr_blocks),
223	void *priv);
224/**
225 * sparse_file_read - read a file into a sparse file cookie
226 *
227 * @s - sparse file cookie
228 * @fd - file descriptor to read from
229 * @sparse - read a file in the Android sparse file format
230 * @crc - verify the crc of a file in the Android sparse file format
231 *
232 * Reads a file into a sparse file cookie.  If sparse is true, the file is
233 * assumed to be in the Android sparse file format.  If sparse is false, the
234 * file will be sparsed by looking for block aligned chunks of all zeros or
235 * another 32 bit value.  If crc is true, the crc of the sparse file will be
236 * verified.
237 *
238 * Returns 0 on success, negative errno on error.
239 */
240int sparse_file_read(struct sparse_file *s, int fd, bool sparse, bool crc);
241
242/**
243 * sparse_file_import - import an existing sparse file
244 *
245 * @s - sparse file cookie
246 * @verbose - print verbose errors while reading the sparse file
247 * @crc - verify the crc of a file in the Android sparse file format
248 *
249 * Reads an existing sparse file into a sparse file cookie, recreating the same
250 * sparse cookie that was used to write it.  If verbose is true, prints verbose
251 * errors when the sparse file is formatted incorrectly.
252 *
253 * Returns a new sparse file cookie on success, NULL on error.
254 */
255struct sparse_file *sparse_file_import(int fd, bool verbose, bool crc);
256
257/**
258 * sparse_file_import_auto - import an existing sparse or normal file
259 *
260 * @fd - file descriptor to read from
261 * @crc - verify the crc of a file in the Android sparse file format
262 * @verbose - whether to use verbose logging
263 *
264 * Reads an existing sparse or normal file into a sparse file cookie.
265 * Attempts to determine if the file is sparse or not by looking for the sparse
266 * file magic number in the first 4 bytes.  If the file is not sparse, the file
267 * will be sparsed by looking for block aligned chunks of all zeros or another
268 * 32 bit value.  If crc is true, the crc of the sparse file will be verified.
269 *
270 * Returns a new sparse file cookie on success, NULL on error.
271 */
272struct sparse_file *sparse_file_import_auto(int fd, bool crc, bool verbose);
273
274/** sparse_file_resparse - rechunk an existing sparse file into smaller files
275 *
276 * @in_s - sparse file cookie of the existing sparse file
277 * @max_len - maximum file size
278 * @out_s - array of sparse file cookies
279 * @out_s_count - size of out_s array
280 *
281 * Splits chunks of an existing sparse file into smaller sparse files such that
282 * each sparse file is less than max_len.  Returns the number of sparse_files
283 * that would have been written to out_s if out_s were big enough.
284 */
285int sparse_file_resparse(struct sparse_file *in_s, unsigned int max_len,
286		struct sparse_file **out_s, int out_s_count);
287
288/**
289 * sparse_file_verbose - set a sparse file cookie to print verbose errors
290 *
291 * @s - sparse file cookie
292 *
293 * Print verbose sparse file errors whenever using the sparse file cookie.
294 */
295void sparse_file_verbose(struct sparse_file *s);
296
297/**
298 * sparse_print_verbose - function called to print verbose errors
299 *
300 * By default, verbose errors will print to standard error.
301 * sparse_print_verbose may be overridden to log verbose errors somewhere else.
302 *
303 */
304extern void (*sparse_print_verbose)(const char *fmt, ...);
305
306#ifdef	__cplusplus
307}
308#endif
309
310#endif
311