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
24 extern "C" {
25 #endif
26 
27 struct 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  */
42 struct 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  */
52 void 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  */
72 int 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  */
90 int 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  */
113 int 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  */
140 int 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  */
161 int 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  */
176 int64_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  */
183 unsigned 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  */
203 int 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  */
220 int 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  */
240 int 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  */
255 struct 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  */
272 struct 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  */
285 int 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  */
295 void 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  */
304 extern void (*sparse_print_verbose)(const char *fmt, ...);
305 
306 #ifdef	__cplusplus
307 }
308 #endif
309 
310 #endif
311