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
23struct sparse_file;
24
25/**
26 * sparse_file_new - create a new sparse file cookie
27 *
28 * @block_size - minimum size of a chunk
29 * @len - size of the expanded sparse file.
30 *
31 * Creates a new sparse_file cookie that can be used to associate data
32 * blocks.  Can later be written to a file with a variety of options.
33 * block_size specifies the minimum size of a chunk in the file.  The maximum
34 * size of the file is 2**32 * block_size (16TB for 4k block size).
35 *
36 * Returns the sparse file cookie, or NULL on error.
37 */
38struct sparse_file *sparse_file_new(unsigned int block_size, int64_t len);
39
40/**
41 * sparse_file_destroy - destroy a sparse file cookie
42 *
43 * @s - sparse file cookie
44 *
45 * Destroys a sparse file cookie.  After destroy, all memory passed in to
46 * sparse_file_add_data can be freed by the caller
47 */
48void sparse_file_destroy(struct sparse_file *s);
49
50/**
51 * sparse_file_add_data - associate a data chunk with a sparse file
52 *
53 * @s - sparse file cookie
54 * @data - pointer to data block
55 * @len - length of the data block
56 * @block - offset in blocks into the sparse file to place the data chunk
57 *
58 * Associates a data chunk with a sparse file cookie.  The region
59 * [block * block_size : block * block_size + len) must not already be used in
60 * the sparse file. If len is not a multiple of the block size the data
61 * will be padded with zeros.
62 *
63 * The data pointer must remain valid until the sparse file is closed or the
64 * data block is removed from the sparse file.
65 *
66 * Returns 0 on success, negative errno on error.
67 */
68int sparse_file_add_data(struct sparse_file *s,
69		void *data, unsigned int len, unsigned int block);
70
71/**
72 * sparse_file_add_fill - associate a fill chunk with a sparse file
73 *
74 * @s - sparse file cookie
75 * @fill_val - 32 bit fill data
76 * @len - length of the fill block
77 * @block - offset in blocks into the sparse file to place the fill chunk
78 *
79 * Associates a chunk filled with fill_val with a sparse file cookie.
80 * The region [block * block_size : block * block_size + len) must not already
81 * be used in the sparse file. If len is not a multiple of the block size the
82 * data will be padded with zeros.
83 *
84 * Returns 0 on success, negative errno on error.
85 */
86int sparse_file_add_fill(struct sparse_file *s,
87		uint32_t fill_val, unsigned int len, unsigned int block);
88
89/**
90 * sparse_file_add_file - associate a chunk of a file with a sparse file
91 *
92 * @s - sparse file cookie
93 * @filename - filename of the file to be copied
94 * @file_offset - offset into the copied file
95 * @len - length of the copied block
96 * @block - offset in blocks into the sparse file to place the file chunk
97 *
98 * Associates a chunk of an existing file with a sparse file cookie.
99 * The region [block * block_size : block * block_size + len) must not already
100 * be used in the sparse file. If len is not a multiple of the block size the
101 * data will be padded with zeros.
102 *
103 * Allows adding large amounts of data to a sparse file without needing to keep
104 * it all mapped.  File size is limited by available virtual address space,
105 * exceptionally large files may need to be added in multiple chunks.
106 *
107 * Returns 0 on success, negative errno on error.
108 */
109int sparse_file_add_file(struct sparse_file *s,
110		const char *filename, int64_t file_offset, unsigned int len,
111		unsigned int block);
112
113/**
114 * sparse_file_add_file - associate a chunk of a file with a sparse file
115 *
116 * @s - sparse file cookie
117 * @filename - filename of the file to be copied
118 * @file_offset - offset into the copied file
119 * @len - length of the copied block
120 * @block - offset in blocks into the sparse file to place the file chunk
121 *
122 * Associates a chunk of an existing fd with a sparse file cookie.
123 * The region [block * block_size : block * block_size + len) must not already
124 * be used in the sparse file. If len is not a multiple of the block size the
125 * data will be padded with zeros.
126 *
127 * Allows adding large amounts of data to a sparse file without needing to keep
128 * it all mapped.  File size is limited by available virtual address space,
129 * exceptionally large files may need to be added in multiple chunks.
130 *
131 * The fd must remain open until the sparse file is closed or the fd block is
132 * removed from the sparse file.
133 *
134 * Returns 0 on success, negative errno on error.
135 */
136int sparse_file_add_fd(struct sparse_file *s,
137		int fd, int64_t file_offset, unsigned int len, unsigned int block);
138
139/**
140 * sparse_file_write - write a sparse file to a file
141 *
142 * @s - sparse file cookie
143 * @fd - file descriptor to write to
144 * @gz - write a gzipped file
145 * @sparse - write in the Android sparse file format
146 * @crc - append a crc chunk
147 *
148 * Writes a sparse file to a file.  If gz is true, the data will be passed
149 * through zlib.  If sparse is true, the file will be written in the Android
150 * sparse file format.  If sparse is false, the file will be written by seeking
151 * over unused chunks, producing a smaller file if the filesystem supports
152 * sparse files.  If crc is true, the crc of the expanded data will be
153 * calculated and appended in a crc chunk.
154 *
155 * Returns 0 on success, negative errno on error.
156 */
157int sparse_file_write(struct sparse_file *s, int fd, bool gz, bool sparse,
158		bool crc);
159
160/**
161 * sparse_file_len - return the length of a sparse file if written to disk
162 *
163 * @s - sparse file cookie
164 * @sparse - write in the Android sparse file format
165 * @crc - append a crc chunk
166 *
167 * Returns the size a sparse file would be on disk if it were written in the
168 * specified format.  If sparse is true, this is the size of the data in the
169 * sparse format.  If sparse is false, this is the size of the normal
170 * non-sparse file.
171 */
172int64_t sparse_file_len(struct sparse_file *s, bool sparse, bool crc);
173
174/**
175 * sparse_file_callback - call a callback for blocks in sparse file
176 *
177 * @s - sparse file cookie
178 * @sparse - write in the Android sparse file format
179 * @crc - append a crc chunk
180 * @write - function to call for each block
181 * @priv - value that will be passed as the first argument to write
182 *
183 * Writes a sparse file by calling a callback function.  If sparse is true, the
184 * file will be written in the Android sparse file format.  If crc is true, the
185 * crc of the expanded data will be calculated and appended in a crc chunk.
186 * The callback 'write' will be called with data and length for each data,
187 * and with data==NULL to skip over a region (only used for non-sparse format).
188 * The callback should return negative on error, 0 on success.
189 *
190 * Returns 0 on success, negative errno on error.
191 */
192int sparse_file_callback(struct sparse_file *s, bool sparse, bool crc,
193		int (*write)(void *priv, const void *data, int len), void *priv);
194
195/**
196 * sparse_file_read - read a file into a sparse file cookie
197 *
198 * @s - sparse file cookie
199 * @fd - file descriptor to read from
200 * @sparse - read a file in the Android sparse file format
201 * @crc - verify the crc of a file in the Android sparse file format
202 *
203 * Reads a file into a sparse file cookie.  If sparse is true, the file is
204 * assumed to be in the Android sparse file format.  If sparse is false, the
205 * file will be sparsed by looking for block aligned chunks of all zeros or
206 * another 32 bit value.  If crc is true, the crc of the sparse file will be
207 * verified.
208 *
209 * Returns 0 on success, negative errno on error.
210 */
211int sparse_file_read(struct sparse_file *s, int fd, bool sparse, bool crc);
212
213/**
214 * sparse_file_import - import an existing sparse file
215 *
216 * @s - sparse file cookie
217 * @verbose - print verbose errors while reading the sparse file
218 * @crc - verify the crc of a file in the Android sparse file format
219 *
220 * Reads an existing sparse file into a sparse file cookie, recreating the same
221 * sparse cookie that was used to write it.  If verbose is true, prints verbose
222 * errors when the sparse file is formatted incorrectly.
223 *
224 * Returns a new sparse file cookie on success, NULL on error.
225 */
226struct sparse_file *sparse_file_import(int fd, bool verbose, bool crc);
227
228/**
229 * sparse_file_import_auto - import an existing sparse or normal file
230 *
231 * @fd - file descriptor to read from
232 * @crc - verify the crc of a file in the Android sparse file format
233 *
234 * Reads an existing sparse or normal file into a sparse file cookie.
235 * Attempts to determine if the file is sparse or not by looking for the sparse
236 * file magic number in the first 4 bytes.  If the file is not sparse, the file
237 * will be sparsed by looking for block aligned chunks of all zeros or another
238 * 32 bit value.  If crc is true, the crc of the sparse file will be verified.
239 *
240 * Returns a new sparse file cookie on success, NULL on error.
241 */
242struct sparse_file *sparse_file_import_auto(int fd, bool crc);
243
244/** sparse_file_resparse - rechunk an existing sparse file into smaller files
245 *
246 * @in_s - sparse file cookie of the existing sparse file
247 * @max_len - maximum file size
248 * @out_s - array of sparse file cookies
249 * @out_s_count - size of out_s array
250 *
251 * Splits chunks of an existing sparse file into smaller sparse files such that
252 * each sparse file is less than max_len.  Returns the number of sparse_files
253 * that would have been written to out_s if out_s were big enough.
254 */
255int sparse_file_resparse(struct sparse_file *in_s, unsigned int max_len,
256		struct sparse_file **out_s, int out_s_count);
257
258/**
259 * sparse_file_verbose - set a sparse file cookie to print verbose errors
260 *
261 * @s - sparse file cookie
262 *
263 * Print verbose sparse file errors whenever using the sparse file cookie.
264 */
265void sparse_file_verbose(struct sparse_file *s);
266
267/**
268 * sparse_print_verbose - function called to print verbose errors
269 *
270 * By default, verbose errors will print to standard error.
271 * sparse_print_verbose may be overridden to log verbose errors somewhere else.
272 *
273 */
274extern void (*sparse_print_verbose)(const char *fmt, ...);
275
276#endif
277