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
