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 <stddef.h> 22 #include <stdint.h> 23 24 #ifdef __cplusplus 25 extern "C" { 26 #endif 27 28 struct sparse_file; 29 30 // The callbacks in sparse_file_callback() and sparse_file_foreach_chunk() take 31 // size_t as the length type (was `int` in past). This allows clients to keep 32 // their codes compatibile with both versions as needed. 33 #define SPARSE_CALLBACK_USES_SIZE_T 34 35 /** 36 * sparse_file_new - create a new sparse file cookie 37 * 38 * @block_size - minimum size of a chunk 39 * @len - size of the expanded sparse file. 40 * 41 * Creates a new sparse_file cookie that can be used to associate data 42 * blocks. Can later be written to a file with a variety of options. 43 * block_size specifies the minimum size of a chunk in the file. The maximum 44 * size of the file is 2**32 * block_size (16TB for 4k block size). 45 * 46 * Returns the sparse file cookie, or NULL on error. 47 */ 48 struct sparse_file *sparse_file_new(unsigned int block_size, int64_t len); 49 50 /** 51 * sparse_file_destroy - destroy a sparse file cookie 52 * 53 * @s - sparse file cookie 54 * 55 * Destroys a sparse file cookie. After destroy, all memory passed in to 56 * sparse_file_add_data can be freed by the caller 57 */ 58 void sparse_file_destroy(struct sparse_file *s); 59 60 /** 61 * sparse_file_add_data - associate a data chunk with a sparse file 62 * 63 * @s - sparse file cookie 64 * @data - pointer to data block 65 * @len - length of the data block 66 * @block - offset in blocks into the sparse file to place the data chunk 67 * 68 * Associates a data chunk with a sparse file cookie. The region 69 * [block * block_size : block * block_size + len) must not already be used in 70 * the sparse file. If len is not a multiple of the block size the data 71 * will be padded with zeros. 72 * 73 * The data pointer must remain valid until the sparse file is closed or the 74 * data block is removed from the sparse file. 75 * 76 * Returns 0 on success, negative errno on error. 77 */ 78 int sparse_file_add_data(struct sparse_file* s, void* data, uint64_t len, unsigned int block); 79 80 /** 81 * sparse_file_add_fill - associate a fill chunk with a sparse file 82 * 83 * @s - sparse file cookie 84 * @fill_val - 32 bit fill data 85 * @len - length of the fill block 86 * @block - offset in blocks into the sparse file to place the fill chunk 87 * 88 * Associates a chunk filled with fill_val with a sparse file cookie. 89 * The region [block * block_size : block * block_size + len) must not already 90 * be used in the sparse file. If len is not a multiple of the block size the 91 * data will be padded with zeros. 92 * 93 * Returns 0 on success, negative errno on error. 94 */ 95 int sparse_file_add_fill(struct sparse_file* s, uint32_t fill_val, uint64_t len, 96 unsigned int block); 97 98 /** 99 * sparse_file_add_file - associate a chunk of a file with a sparse file 100 * 101 * @s - sparse file cookie 102 * @filename - filename of the file to be copied 103 * @file_offset - offset into the copied file 104 * @len - length of the copied block 105 * @block - offset in blocks into the sparse file to place the file chunk 106 * 107 * Associates a chunk of an existing file with a sparse file cookie. 108 * The region [block * block_size : block * block_size + len) must not already 109 * be used in the sparse file. If len is not a multiple of the block size the 110 * data will be padded with zeros. 111 * 112 * Allows adding large amounts of data to a sparse file without needing to keep 113 * it all mapped. File size is limited by available virtual address space, 114 * exceptionally large files may need to be added in multiple chunks. 115 * 116 * Returns 0 on success, negative errno on error. 117 */ 118 int sparse_file_add_file(struct sparse_file* s, const char* filename, int64_t file_offset, 119 uint64_t len, unsigned int block); 120 121 /** 122 * sparse_file_add_file - associate a chunk of a file with a sparse file 123 * 124 * @s - sparse file cookie 125 * @filename - filename of the file to be copied 126 * @file_offset - offset into the copied file 127 * @len - length of the copied block 128 * @block - offset in blocks into the sparse file to place the file chunk 129 * 130 * Associates a chunk of an existing fd with a sparse file cookie. 131 * The region [block * block_size : block * block_size + len) must not already 132 * be used in the sparse file. If len is not a multiple of the block size the 133 * data will be padded with zeros. 134 * 135 * Allows adding large amounts of data to a sparse file without needing to keep 136 * it all mapped. File size is limited by available virtual address space, 137 * exceptionally large files may need to be added in multiple chunks. 138 * 139 * The fd must remain open until the sparse file is closed or the fd block is 140 * removed from the sparse file. 141 * 142 * Returns 0 on success, negative errno on error. 143 */ 144 int sparse_file_add_fd(struct sparse_file* s, int fd, int64_t file_offset, uint64_t len, 145 unsigned int block); 146 147 /** 148 * sparse_file_write - write a sparse file to a file 149 * 150 * @s - sparse file cookie 151 * @fd - file descriptor to write to 152 * @gz - write a gzipped file 153 * @sparse - write in the Android sparse file format 154 * @crc - append a crc chunk 155 * 156 * Writes a sparse file to a file. If gz is true, the data will be passed 157 * through zlib. If sparse is true, the file will be written in the Android 158 * sparse file format. If sparse is false, the file will be written by seeking 159 * over unused chunks, producing a smaller file if the filesystem supports 160 * sparse files. If crc is true, the crc of the expanded data will be 161 * calculated and appended in a crc chunk. 162 * 163 * Returns 0 on success, negative errno on error. 164 */ 165 int sparse_file_write(struct sparse_file *s, int fd, bool gz, bool sparse, 166 bool crc); 167 168 /** 169 * sparse_file_len - return the length of a sparse file if written to disk 170 * 171 * @s - sparse file cookie 172 * @sparse - write in the Android sparse file format 173 * @crc - append a crc chunk 174 * 175 * Returns the size a sparse file would be on disk if it were written in the 176 * specified format. If sparse is true, this is the size of the data in the 177 * sparse format. If sparse is false, this is the size of the normal 178 * non-sparse file. 179 */ 180 int64_t sparse_file_len(struct sparse_file *s, bool sparse, bool crc); 181 182 /** 183 * sparse_file_block_size 184 * 185 * @s - sparse file cookie 186 */ 187 unsigned int sparse_file_block_size(struct sparse_file *s); 188 189 /** 190 * sparse_file_callback - call a callback for blocks in sparse file 191 * 192 * @s - sparse file cookie 193 * @sparse - write in the Android sparse file format 194 * @crc - append a crc chunk 195 * @write - function to call for each block 196 * @priv - value that will be passed as the first argument to write 197 * 198 * Writes a sparse file by calling a callback function. If sparse is true, the 199 * file will be written in the Android sparse file format. If crc is true, the 200 * crc of the expanded data will be calculated and appended in a crc chunk. 201 * The callback 'write' will be called with data and length for each data, 202 * and with data==NULL to skip over a region (only used for non-sparse format). 203 * The callback should return negative on error, 0 on success. 204 * 205 * Returns 0 on success, negative errno on error. 206 */ 207 int sparse_file_callback(struct sparse_file *s, bool sparse, bool crc, 208 int (*write)(void *priv, const void *data, size_t len), void *priv); 209 210 /** 211 * sparse_file_foreach_chunk - call a callback for data blocks in sparse file 212 * 213 * @s - sparse file cookie 214 * @sparse - write in the Android sparse file format 215 * @crc - append a crc chunk 216 * @write - function to call for each block 217 * @priv - value that will be passed as the first argument to write 218 * 219 * The function has the same behavior as 'sparse_file_callback', except it only 220 * iterates on blocks that contain data. 221 * 222 * Returns 0 on success, negative errno on error. 223 */ 224 int sparse_file_foreach_chunk(struct sparse_file *s, bool sparse, bool crc, 225 int (*write)(void *priv, const void *data, size_t len, unsigned int block, 226 unsigned int nr_blocks), 227 void *priv); 228 229 /** 230 * enum sparse_read_mode - The method to use when reading in files 231 * @SPARSE_READ_MODE_NORMAL: The input is a regular file. Constant chunks of 232 * data (including holes) will be be converted to 233 * fill chunks. 234 * @SPARSE_READ_MODE_SPARSE: The input is an Android sparse file. 235 * @SPARSE_READ_MODE_HOLE: The input is a regular file. Holes will be converted 236 * to "don't care" chunks. Other constant chunks will 237 * be converted to fill chunks. 238 */ 239 enum sparse_read_mode { 240 SPARSE_READ_MODE_NORMAL = false, 241 SPARSE_READ_MODE_SPARSE = true, 242 SPARSE_READ_MODE_HOLE, 243 }; 244 245 /** 246 * sparse_file_read - read a file into a sparse file cookie 247 * 248 * @s - sparse file cookie 249 * @fd - file descriptor to read from 250 * @mode - mode to use when reading the input file 251 * @crc - verify the crc of a file in the Android sparse file format 252 * 253 * Reads a file into a sparse file cookie. If @mode is 254 * %SPARSE_READ_MODE_SPARSE, the file is assumed to be in the Android sparse 255 * file format. If @mode is %SPARSE_READ_MODE_NORMAL, the file will be sparsed 256 * by looking for block aligned chunks of all zeros or another 32 bit value. If 257 * @mode is %SPARSE_READ_MODE_HOLE, the file will be sparsed like 258 * %SPARSE_READ_MODE_NORMAL, but holes in the file will be converted to "don't 259 * care" chunks. If crc is true, the crc of the sparse file will be verified. 260 * 261 * Returns 0 on success, negative errno on error. 262 */ 263 int sparse_file_read(struct sparse_file *s, int fd, enum sparse_read_mode mode, bool crc); 264 265 /** 266 * sparse_file_import - import an existing sparse file 267 * 268 * @fd - file descriptor to read from 269 * @verbose - print verbose errors while reading the sparse file 270 * @crc - verify the crc of a file in the Android sparse file format 271 * 272 * Reads an existing sparse file into a sparse file cookie, recreating the same 273 * sparse cookie that was used to write it. If verbose is true, prints verbose 274 * errors when the sparse file is formatted incorrectly. 275 * 276 * Returns a new sparse file cookie on success, NULL on error. 277 */ 278 struct sparse_file *sparse_file_import(int fd, bool verbose, bool crc); 279 280 /** 281 * sparse_file_import_buf - import an existing sparse file from a buffer 282 * 283 * @buf - buffer to read from 284 * @len - length of buffer 285 * @verbose - print verbose errors while reading the sparse file 286 * @crc - verify the crc of a file in the Android sparse file format 287 * 288 * Reads existing sparse file data into a sparse file cookie, recreating the same 289 * sparse cookie that was used to write it. If verbose is true, prints verbose 290 * errors when the sparse file is formatted incorrectly. 291 * 292 * Returns a new sparse file cookie on success, NULL on error. 293 */ 294 struct sparse_file* sparse_file_import_buf(char* buf, size_t len, bool verbose, bool crc); 295 296 /** 297 * sparse_file_import_auto - import an existing sparse or normal file 298 * 299 * @fd - file descriptor to read from 300 * @crc - verify the crc of a file in the Android sparse file format 301 * @verbose - whether to use verbose logging 302 * 303 * Reads an existing sparse or normal file into a sparse file cookie. 304 * Attempts to determine if the file is sparse or not by looking for the sparse 305 * file magic number in the first 4 bytes. If the file is not sparse, the file 306 * will be sparsed by looking for block aligned chunks of all zeros or another 307 * 32 bit value. If crc is true, the crc of the sparse file will be verified. 308 * 309 * Returns a new sparse file cookie on success, NULL on error. 310 */ 311 struct sparse_file *sparse_file_import_auto(int fd, bool crc, bool verbose); 312 313 /** sparse_file_resparse - rechunk an existing sparse file into smaller files 314 * 315 * @in_s - sparse file cookie of the existing sparse file 316 * @max_len - maximum file size 317 * @out_s - array of sparse file cookies 318 * @out_s_count - size of out_s array 319 * 320 * Splits chunks of an existing sparse file into smaller sparse files such that 321 * each sparse file is less than max_len. Returns the number of sparse_files 322 * that would have been written to out_s if out_s were big enough. 323 */ 324 int sparse_file_resparse(struct sparse_file *in_s, unsigned int max_len, 325 struct sparse_file **out_s, int out_s_count); 326 327 /** 328 * sparse_file_verbose - set a sparse file cookie to print verbose errors 329 * 330 * @s - sparse file cookie 331 * 332 * Print verbose sparse file errors whenever using the sparse file cookie. 333 */ 334 void sparse_file_verbose(struct sparse_file *s); 335 336 /** 337 * sparse_print_verbose - function called to print verbose errors 338 * 339 * By default, verbose errors will print to standard error. 340 * sparse_print_verbose may be overridden to log verbose errors somewhere else. 341 * 342 */ 343 extern void (*sparse_print_verbose)(const char *fmt, ...); 344 345 #ifdef __cplusplus 346 } 347 #endif 348 349 #endif 350