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 struct 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 */ 38 struct 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 */ 48 void 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 */ 68 int 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 */ 86 int 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 */ 109 int 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 */ 136 int 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 */ 157 int 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 */ 172 int64_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 */ 192 int 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 */ 211 int 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 */ 226 struct 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 */ 242 struct 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 */ 255 int 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 */ 265 void 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 */ 274 extern void (*sparse_print_verbose)(const char *fmt, ...); 275 276 #endif 277
