libsparse/include/sparse/sparse.h

   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_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 /**
 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
 237  * @verbose - whether to use verbose logging
 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  */
 247 struct sparse_file *sparse_file_import_auto(int fd, bool crc, bool verbose);
 248
 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
 263 /**
 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
 281 #ifdef  __cplusplus
 282 }
 283 #endif
 284
 285 #endif