sys/contrib/zstd/contrib/seekable_format/zstd_seekable.h

   1 #ifndef SEEKABLE_H
   2 #define SEEKABLE_H
   3
   4 #if defined (__cplusplus)
   5 extern "C" {
   6 #endif
   7
   8 #include <stdio.h>
   9 #include "zstd.h"   /* ZSTDLIB_API */
  10
  11
  12 #define ZSTD_seekTableFooterSize 9
  13
  14 #define ZSTD_SEEKABLE_MAGICNUMBER 0x8F92EAB1
  15
  16 #define ZSTD_SEEKABLE_MAXFRAMES 0x8000000U
  17
  18 /* Limit the maximum size to avoid any potential issues storing the compressed size */
  19 #define ZSTD_SEEKABLE_MAX_FRAME_DECOMPRESSED_SIZE 0x80000000U
  20
  21 /*-****************************************************************************
  22 *  Seekable Format
  23 *
  24 *  The seekable format splits the compressed data into a series of "frames",
  25 *  each compressed individually so that decompression of a section in the
  26 *  middle of an archive only requires zstd to decompress at most a frame's
  27 *  worth of extra data, instead of the entire archive.
  28 ******************************************************************************/
  29
  30 typedef struct ZSTD_seekable_CStream_s ZSTD_seekable_CStream;
  31 typedef struct ZSTD_seekable_s ZSTD_seekable;
  32
  33 /*-****************************************************************************
  34 *  Seekable compression - HowTo
  35 *  A ZSTD_seekable_CStream object is required to tracking streaming operation.
  36 *  Use ZSTD_seekable_createCStream() and ZSTD_seekable_freeCStream() to create/
  37 *  release resources.
  38 *
  39 *  Streaming objects are reusable to avoid allocation and deallocation,
  40 *  to start a new compression operation call ZSTD_seekable_initCStream() on the
  41 *  compressor.
  42 *
  43 *  Data streamed to the seekable compressor will automatically be split into
  44 *  frames of size `maxFrameSize` (provided in ZSTD_seekable_initCStream()),
  45 *  or if none is provided, will be cut off whenever ZSTD_seekable_endFrame() is
  46 *  called or when the default maximum frame size (2GB) is reached.
  47 *
  48 *  Use ZSTD_seekable_initCStream() to initialize a ZSTD_seekable_CStream object
  49 *  for a new compression operation.
  50 *  `maxFrameSize` indicates the size at which to automatically start a new
  51 *  seekable frame.  `maxFrameSize == 0` implies the default maximum size.
  52 *  `checksumFlag` indicates whether or not the seek table should include frame
  53 *  checksums on the uncompressed data for verification.
  54 *  @return : a size hint for input to provide for compression, or an error code
  55 *            checkable with ZSTD_isError()
  56 *
  57 *  Use ZSTD_seekable_compressStream() repetitively to consume input stream.
  58 *  The function will automatically update both `pos` fields.
  59 *  Note that it may not consume the entire input, in which case `pos < size`,
  60 *  and it's up to the caller to present again remaining data.
  61 *  @return : a size hint, preferred nb of bytes to use as input for next
  62 *            function call or an error code, which can be tested using
  63 *            ZSTD_isError().
  64 *            Note 1 : it's just a hint, to help latency a little, any other
  65 *                     value will work fine.
  66 *
  67 *  At any time, call ZSTD_seekable_endFrame() to end the current frame and
  68 *  start a new one.
  69 *
  70 *  ZSTD_seekable_endStream() will end the current frame, and then write the seek
  71 *  table so that decompressors can efficiently find compressed frames.
  72 *  ZSTD_seekable_endStream() may return a number > 0 if it was unable to flush
  73 *  all the necessary data to `output`.  In this case, it should be called again
  74 *  until all remaining data is flushed out and 0 is returned.
  75 ******************************************************************************/
  76
  77 /*===== Seekable compressor management =====*/
  78 ZSTDLIB_API ZSTD_seekable_CStream* ZSTD_seekable_createCStream(void);
  79 ZSTDLIB_API size_t ZSTD_seekable_freeCStream(ZSTD_seekable_CStream* zcs);
  80
  81 /*===== Seekable compression functions =====*/
  82 ZSTDLIB_API size_t ZSTD_seekable_initCStream(ZSTD_seekable_CStream* zcs, int compressionLevel, int checksumFlag, unsigned maxFrameSize);
  83 ZSTDLIB_API size_t ZSTD_seekable_compressStream(ZSTD_seekable_CStream* zcs, ZSTD_outBuffer* output, ZSTD_inBuffer* input);
  84 ZSTDLIB_API size_t ZSTD_seekable_endFrame(ZSTD_seekable_CStream* zcs, ZSTD_outBuffer* output);
  85 ZSTDLIB_API size_t ZSTD_seekable_endStream(ZSTD_seekable_CStream* zcs, ZSTD_outBuffer* output);
  86
  87 /*= Raw seek table API
  88  *  These functions allow for the seek table to be constructed directly.
  89  *  This table can then be appended to a file of concatenated frames.
  90  *  This allows the frames to be compressed independently, even in parallel,
  91  *  and compiled together afterward into a seekable archive.
  92  *
  93  *  Use ZSTD_seekable_createFrameLog() to allocate and initialize a tracking
  94  *  structure.
  95  *
  96  *  Call ZSTD_seekable_logFrame() once for each frame in the archive.
  97  *  checksum is optional, and will not be used if checksumFlag was 0 when the
  98  *  frame log was created.  If present, it should be the least significant 32
  99  *  bits of the XXH64 hash of the uncompressed data.
 100  *
 101  *  Call ZSTD_seekable_writeSeekTable to serialize the data into a seek table.
 102  *  If the entire table was written, the return value will be 0.  Otherwise,
 103  *  it will be equal to the number of bytes left to write. */
 104 typedef struct ZSTD_frameLog_s ZSTD_frameLog;
 105 ZSTDLIB_API ZSTD_frameLog* ZSTD_seekable_createFrameLog(int checksumFlag);
 106 ZSTDLIB_API size_t ZSTD_seekable_freeFrameLog(ZSTD_frameLog* fl);
 107 ZSTDLIB_API size_t ZSTD_seekable_logFrame(ZSTD_frameLog* fl, unsigned compressedSize, unsigned decompressedSize, unsigned checksum);
 108 ZSTDLIB_API size_t ZSTD_seekable_writeSeekTable(ZSTD_frameLog* fl, ZSTD_outBuffer* output);
 109
 110 /*-****************************************************************************
 111 *  Seekable decompression - HowTo
 112 *  A ZSTD_seekable object is required to tracking the seekTable.
 113 *
 114 *  Call ZSTD_seekable_init* to initialize a ZSTD_seekable object with the
 115 *  the seek table provided in the input.
 116 *  There are three modes for ZSTD_seekable_init:
 117 *    - ZSTD_seekable_initBuff() : An in-memory API.  The data contained in
 118 *      `src` should be the entire seekable file, including the seek table.
 119 *      `src` should be kept alive and unmodified until the ZSTD_seekable object
 120 *      is freed or reset.
 121 *    - ZSTD_seekable_initFile() : A simplified file API using stdio.  fread and
 122 *      fseek will be used to access the required data for building the seek
 123 *      table and doing decompression operations.  `src` should not be closed
 124 *      or modified until the ZSTD_seekable object is freed or reset.
 125 *    - ZSTD_seekable_initAdvanced() : A general API allowing the client to
 126 *      provide its own read and seek callbacks.
 127 *        + ZSTD_seekable_read() : read exactly `n` bytes into `buffer`.
 128 *                                 Premature EOF should be treated as an error.
 129 *        + ZSTD_seekable_seek() : seek the read head to `offset` from `origin`,
 130 *                                 where origin is either SEEK_SET (beginning of
 131 *                                 file), or SEEK_END (end of file).
 132 *  Both functions should return a non-negative value in case of success, and a
 133 *  negative value in case of failure.  If implementing using this API and
 134 *  stdio, be careful with files larger than 4GB and fseek.  All of these
 135 *  functions return an error code checkable with ZSTD_isError().
 136 *
 137 *  Call ZSTD_seekable_decompress to decompress `dstSize` bytes at decompressed
 138 *  offset `offset`.  ZSTD_seekable_decompress may have to decompress the entire
 139 *  prefix of the frame before the desired data if it has not already processed
 140 *  this section. If ZSTD_seekable_decompress is called multiple times for a
 141 *  consecutive range of data, it will efficiently retain the decompressor object
 142 *  and avoid redecompressing frame prefixes.  The return value is the number of
 143 *  bytes decompressed, or an error code checkable with ZSTD_isError().
 144 *
 145 *  The seek table access functions can be used to obtain the data contained
 146 *  in the seek table.  If frameIndex is larger than the value returned by
 147 *  ZSTD_seekable_getNumFrames(), they will return error codes checkable with
 148 *  ZSTD_isError().  Note that since the offset access functions return
 149 *  unsigned long long instead of size_t, in this case they will instead return
 150 *  the value ZSTD_SEEKABLE_FRAMEINDEX_TOOLARGE.
 151 ******************************************************************************/
 152
 153 /*===== Seekable decompressor management =====*/
 154 ZSTDLIB_API ZSTD_seekable* ZSTD_seekable_create(void);
 155 ZSTDLIB_API size_t ZSTD_seekable_free(ZSTD_seekable* zs);
 156
 157 /*===== Seekable decompression functions =====*/
 158 ZSTDLIB_API size_t ZSTD_seekable_initBuff(ZSTD_seekable* zs, const void* src, size_t srcSize);
 159 ZSTDLIB_API size_t ZSTD_seekable_initFile(ZSTD_seekable* zs, FILE* src);
 160 ZSTDLIB_API size_t ZSTD_seekable_decompress(ZSTD_seekable* zs, void* dst, size_t dstSize, unsigned long long offset);
 161 ZSTDLIB_API size_t ZSTD_seekable_decompressFrame(ZSTD_seekable* zs, void* dst, size_t dstSize, unsigned frameIndex);
 162
 163 #define ZSTD_SEEKABLE_FRAMEINDEX_TOOLARGE (0ULL-2)
 164 /*===== Seek Table access functions =====*/
 165 ZSTDLIB_API unsigned ZSTD_seekable_getNumFrames(ZSTD_seekable* const zs);
 166 ZSTDLIB_API unsigned long long ZSTD_seekable_getFrameCompressedOffset(ZSTD_seekable* const zs, unsigned frameIndex);
 167 ZSTDLIB_API unsigned long long ZSTD_seekable_getFrameDecompressedOffset(ZSTD_seekable* const zs, unsigned frameIndex);
 168 ZSTDLIB_API size_t ZSTD_seekable_getFrameCompressedSize(ZSTD_seekable* const zs, unsigned frameIndex);
 169 ZSTDLIB_API size_t ZSTD_seekable_getFrameDecompressedSize(ZSTD_seekable* const zs, unsigned frameIndex);
 170 ZSTDLIB_API unsigned ZSTD_seekable_offsetToFrameIndex(ZSTD_seekable* const zs, unsigned long long offset);
 171
 172 /*===== Seekable advanced I/O API =====*/
 173 typedef int(ZSTD_seekable_read)(void* opaque, void* buffer, size_t n);
 174 typedef int(ZSTD_seekable_seek)(void* opaque, long long offset, int origin);
 175 typedef struct {
 176     void* opaque;
 177     ZSTD_seekable_read* read;
 178     ZSTD_seekable_seek* seek;
 179 } ZSTD_seekable_customFile;
 180 ZSTDLIB_API size_t ZSTD_seekable_initAdvanced(ZSTD_seekable* zs, ZSTD_seekable_customFile src);
 181
 182 #if defined (__cplusplus)
 183 }
 184 #endif
 185
 186 #endif