sparse.h revision 28fa5bc347390480fe190294c6c385b6a9f0d68b
128fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross/* 228fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * Copyright (C) 2012 The Android Open Source Project 328fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * 428fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * Licensed under the Apache License, Version 2.0 (the "License"); 528fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * you may not use this file except in compliance with the License. 628fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * You may obtain a copy of the License at 728fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * 828fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * http://www.apache.org/licenses/LICENSE-2.0 928fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * 1028fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * Unless required by applicable law or agreed to in writing, software 1128fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * distributed under the License is distributed on an "AS IS" BASIS, 1228fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 1328fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * See the License for the specific language governing permissions and 1428fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * limitations under the License. 1528fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross */ 1628fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross 1728fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross#ifndef _LIBSPARSE_SPARSE_H_ 1828fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross#define _LIBSPARSE_SPARSE_H_ 1928fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross 2028fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross#include <stdbool.h> 2128fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross#include <stdint.h> 2228fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross 2328fa5bc347390480fe190294c6c385b6a9f0d68bColin Crossstruct sparse_file; 2428fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross 2528fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross/** 2628fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * sparse_file_new - create a new sparse file cookie 2728fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * 2828fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * @block_size - minimum size of a chunk 2928fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * @len - size of the expanded sparse file. 3028fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * 3128fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * Creates a new sparse_file cookie that can be used to associate data 3228fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * blocks. Can later be written to a file with a variety of options. 3328fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * block_size specifies the minimum size of a chunk in the file. The maximum 3428fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * size of the file is 2**32 * block_size (16TB for 4k block size). 3528fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * 3628fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * Returns the sparse file cookie, or NULL on error. 3728fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross */ 3828fa5bc347390480fe190294c6c385b6a9f0d68bColin Crossstruct sparse_file *sparse_file_new(unsigned int block_size, int64_t len); 3928fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross 4028fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross/** 4128fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * sparse_file_destroy - destroy a sparse file cookie 4228fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * 4328fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * @s - sparse file cookie 4428fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * 4528fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * Destroys a sparse file cookie. After destroy, all memory passed in to 4628fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * sparse_file_add_data can be freed by the caller 4728fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross */ 4828fa5bc347390480fe190294c6c385b6a9f0d68bColin Crossvoid sparse_file_destroy(struct sparse_file *s); 4928fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross 5028fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross/** 5128fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * sparse_file_add_data - associate a data chunk with a sparse file 5228fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * 5328fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * @s - sparse file cookie 5428fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * @data - pointer to data block 5528fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * @len - length of the data block 5628fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * @block - offset in blocks into the sparse file to place the data chunk 5728fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * 5828fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * Associates a data chunk with a sparse file cookie. The region 5928fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * [block * block_size : block * block_size + len) must not already be used in 6028fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * the sparse file. If len is not a multiple of the block size the data 6128fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * will be padded with zeros. 6228fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * 6328fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * The data pointer must remain valid until the sparse file is closed or the 6428fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * data block is removed from the sparse file. 6528fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * 6628fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * Returns 0 on success, negative errno on error. 6728fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross */ 6828fa5bc347390480fe190294c6c385b6a9f0d68bColin Crossint sparse_file_add_data(struct sparse_file *s, 6928fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross void *data, unsigned int len, unsigned int block); 7028fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross 7128fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross/** 7228fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * sparse_file_add_fill - associate a fill chunk with a sparse file 7328fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * 7428fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * @s - sparse file cookie 7528fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * @fill_val - 32 bit fill data 7628fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * @len - length of the fill block 7728fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * @block - offset in blocks into the sparse file to place the fill chunk 7828fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * 7928fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * Associates a chunk filled with fill_val with a sparse file cookie. 8028fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * The region [block * block_size : block * block_size + len) must not already 8128fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * be used in the sparse file. If len is not a multiple of the block size the 8228fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * data will be padded with zeros. 8328fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * 8428fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * Returns 0 on success, negative errno on error. 8528fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross */ 8628fa5bc347390480fe190294c6c385b6a9f0d68bColin Crossint sparse_file_add_fill(struct sparse_file *s, 8728fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross uint32_t fill_val, unsigned int len, unsigned int block); 8828fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross 8928fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross/** 9028fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * sparse_file_add_file - associate a chunk of a file with a sparse file 9128fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * 9228fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * @s - sparse file cookie 9328fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * @filename - filename of the file to be copied 9428fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * @file_offset - offset into the copied file 9528fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * @len - length of the copied block 9628fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * @block - offset in blocks into the sparse file to place the file chunk 9728fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * 9828fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * Associates a chunk of an existing file with a sparse file cookie. 9928fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * The region [block * block_size : block * block_size + len) must not already 10028fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * be used in the sparse file. If len is not a multiple of the block size the 10128fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * data will be padded with zeros. 10228fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * 10328fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * Allows adding large amounts of data to a sparse file without needing to keep 10428fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * it all mapped. File size is limited by available virtual address space, 10528fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * exceptionally large files may need to be added in multiple chunks. 10628fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * 10728fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * Returns 0 on success, negative errno on error. 10828fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross */ 10928fa5bc347390480fe190294c6c385b6a9f0d68bColin Crossint sparse_file_add_file(struct sparse_file *s, 11028fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross const char *filename, int64_t file_offset, unsigned int len, 11128fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross unsigned int block); 11228fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross 11328fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross/** 11428fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * sparse_file_write - write a sparse file to a file 11528fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * 11628fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * @s - sparse file cookie 11728fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * @fd - file descriptor to write to 11828fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * @gz - write a gzipped file 11928fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * @sparse - write in the Android sparse file format 12028fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * @crc - append a crc chunk 12128fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * 12228fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * Writes a sparse file to a file. If gz is true, the data will be passed 12328fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * through zlib. If sparse is true, the file will be written in the Android 12428fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * sparse file format. If sparse is false, the file will be written by seeking 12528fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * over unused chunks, producing a smaller file if the filesystem supports 12628fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * sparse files. If crc is true, the crc of the expanded data will be 12728fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * calculated and appended in a crc chunk. 12828fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * 12928fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross * Returns 0 on success, negative errno on error. 13028fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross */ 13128fa5bc347390480fe190294c6c385b6a9f0d68bColin Crossint sparse_file_write(struct sparse_file *s, int fd, bool gz, bool sparse, 13228fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross bool crc); 13328fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross 13428fa5bc347390480fe190294c6c385b6a9f0d68bColin Cross#endif 135