Colin Cross | 28fa5bc | 2012-05-20 13:28:05 -0700 | [diff] [blame] | 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 | |
Colin Cross | 099824c | 2014-04-18 13:54:12 -0700 | [diff] [blame] | 23 | #ifdef __cplusplus |
| 24 | extern "C" { |
| 25 | #endif |
| 26 | |
Colin Cross | 28fa5bc | 2012-05-20 13:28:05 -0700 | [diff] [blame] | 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 | /** |
Colin Cross | 9e1f17e | 2012-04-25 18:31:39 -0700 | [diff] [blame] | 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 | /** |
Colin Cross | 28fa5bc | 2012-05-20 13:28:05 -0700 | [diff] [blame] | 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 | |
Colin Cross | a21930b | 2012-04-26 14:24:35 -0700 | [diff] [blame] | 164 | /** |
Colin Cross | 317a09e | 2012-05-24 17:15:43 -0700 | [diff] [blame] | 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 | /** |
Colin Cross | 1e17b31 | 2012-05-21 16:35:45 -0700 | [diff] [blame] | 179 | * sparse_file_callback - call a callback for blocks in sparse file |
| 180 | * |
| 181 | * @s - sparse file cookie |
| 182 | * @sparse - write in the Android sparse file format |
| 183 | * @crc - append a crc chunk |
| 184 | * @write - function to call for each block |
| 185 | * @priv - value that will be passed as the first argument to write |
| 186 | * |
| 187 | * Writes a sparse file by calling a callback function. If sparse is true, the |
| 188 | * file will be written in the Android sparse file format. If crc is true, the |
| 189 | * crc of the expanded data will be calculated and appended in a crc chunk. |
| 190 | * The callback 'write' will be called with data and length for each data, |
| 191 | * and with data==NULL to skip over a region (only used for non-sparse format). |
| 192 | * The callback should return negative on error, 0 on success. |
| 193 | * |
| 194 | * Returns 0 on success, negative errno on error. |
| 195 | */ |
| 196 | int sparse_file_callback(struct sparse_file *s, bool sparse, bool crc, |
| 197 | int (*write)(void *priv, const void *data, int len), void *priv); |
| 198 | |
| 199 | /** |
Colin Cross | 0c4c47f | 2012-04-25 19:02:58 -0700 | [diff] [blame] | 200 | * sparse_file_read - read a file into a sparse file cookie |
| 201 | * |
| 202 | * @s - sparse file cookie |
| 203 | * @fd - file descriptor to read from |
| 204 | * @sparse - read a file in the Android sparse file format |
| 205 | * @crc - verify the crc of a file in the Android sparse file format |
| 206 | * |
| 207 | * Reads a file into a sparse file cookie. If sparse is true, the file is |
| 208 | * assumed to be in the Android sparse file format. If sparse is false, the |
| 209 | * file will be sparsed by looking for block aligned chunks of all zeros or |
| 210 | * another 32 bit value. If crc is true, the crc of the sparse file will be |
| 211 | * verified. |
| 212 | * |
| 213 | * Returns 0 on success, negative errno on error. |
| 214 | */ |
| 215 | int sparse_file_read(struct sparse_file *s, int fd, bool sparse, bool crc); |
| 216 | |
| 217 | /** |
| 218 | * sparse_file_import - import an existing sparse file |
| 219 | * |
| 220 | * @s - sparse file cookie |
| 221 | * @verbose - print verbose errors while reading the sparse file |
| 222 | * @crc - verify the crc of a file in the Android sparse file format |
| 223 | * |
| 224 | * Reads an existing sparse file into a sparse file cookie, recreating the same |
| 225 | * sparse cookie that was used to write it. If verbose is true, prints verbose |
| 226 | * errors when the sparse file is formatted incorrectly. |
| 227 | * |
| 228 | * Returns a new sparse file cookie on success, NULL on error. |
| 229 | */ |
| 230 | struct sparse_file *sparse_file_import(int fd, bool verbose, bool crc); |
| 231 | |
| 232 | /** |
| 233 | * sparse_file_import_auto - import an existing sparse or normal file |
| 234 | * |
| 235 | * @fd - file descriptor to read from |
| 236 | * @crc - verify the crc of a file in the Android sparse file format |
Mohamad Ayyash | 80cc1f6 | 2015-03-31 12:09:29 -0700 | [diff] [blame] | 237 | * @verbose - whether to use verbose logging |
Colin Cross | 0c4c47f | 2012-04-25 19:02:58 -0700 | [diff] [blame] | 238 | * |
| 239 | * Reads an existing sparse or normal file into a sparse file cookie. |
| 240 | * Attempts to determine if the file is sparse or not by looking for the sparse |
| 241 | * file magic number in the first 4 bytes. If the file is not sparse, the file |
| 242 | * will be sparsed by looking for block aligned chunks of all zeros or another |
| 243 | * 32 bit value. If crc is true, the crc of the sparse file will be verified. |
| 244 | * |
| 245 | * Returns a new sparse file cookie on success, NULL on error. |
| 246 | */ |
Mohamad Ayyash | 80cc1f6 | 2015-03-31 12:09:29 -0700 | [diff] [blame] | 247 | struct sparse_file *sparse_file_import_auto(int fd, bool crc, bool verbose); |
Colin Cross | 0c4c47f | 2012-04-25 19:02:58 -0700 | [diff] [blame] | 248 | |
Colin Cross | bdc6d39 | 2012-05-02 15:18:22 -0700 | [diff] [blame] | 249 | /** sparse_file_resparse - rechunk an existing sparse file into smaller files |
| 250 | * |
| 251 | * @in_s - sparse file cookie of the existing sparse file |
| 252 | * @max_len - maximum file size |
| 253 | * @out_s - array of sparse file cookies |
| 254 | * @out_s_count - size of out_s array |
| 255 | * |
| 256 | * Splits chunks of an existing sparse file into smaller sparse files such that |
| 257 | * each sparse file is less than max_len. Returns the number of sparse_files |
| 258 | * that would have been written to out_s if out_s were big enough. |
| 259 | */ |
| 260 | int sparse_file_resparse(struct sparse_file *in_s, unsigned int max_len, |
| 261 | struct sparse_file **out_s, int out_s_count); |
| 262 | |
Colin Cross | 0c4c47f | 2012-04-25 19:02:58 -0700 | [diff] [blame] | 263 | /** |
Colin Cross | a21930b | 2012-04-26 14:24:35 -0700 | [diff] [blame] | 264 | * sparse_file_verbose - set a sparse file cookie to print verbose errors |
| 265 | * |
| 266 | * @s - sparse file cookie |
| 267 | * |
| 268 | * Print verbose sparse file errors whenever using the sparse file cookie. |
| 269 | */ |
| 270 | void sparse_file_verbose(struct sparse_file *s); |
| 271 | |
| 272 | /** |
| 273 | * sparse_print_verbose - function called to print verbose errors |
| 274 | * |
| 275 | * By default, verbose errors will print to standard error. |
| 276 | * sparse_print_verbose may be overridden to log verbose errors somewhere else. |
| 277 | * |
| 278 | */ |
| 279 | extern void (*sparse_print_verbose)(const char *fmt, ...); |
| 280 | |
Colin Cross | 099824c | 2014-04-18 13:54:12 -0700 | [diff] [blame] | 281 | #ifdef __cplusplus |
| 282 | } |
| 283 | #endif |
| 284 | |
Colin Cross | 28fa5bc | 2012-05-20 13:28:05 -0700 | [diff] [blame] | 285 | #endif |