src/liblzma/common/common.h

   1 ///////////////////////////////////////////////////////////////////////////////
   2 //
   3 /// \file       common.h
   4 /// \brief      Definitions common to the whole liblzma library
   5 //
   6 //  Copyright (C) 2007-2008 Lasse Collin
   7 //
   8 //  This library is free software; you can redistribute it and/or
   9 //  modify it under the terms of the GNU Lesser General Public
  10 //  License as published by the Free Software Foundation; either
  11 //  version 2.1 of the License, or (at your option) any later version.
  12 //
  13 //  This library is distributed in the hope that it will be useful,
  14 //  but WITHOUT ANY WARRANTY; without even the implied warranty of
  15 //  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16 //  Lesser General Public License for more details.
  17 //
  18 ///////////////////////////////////////////////////////////////////////////////
  19
  20 #ifndef LZMA_COMMON_H
  21 #define LZMA_COMMON_H
  22
  23 #include "../../common/sysdefs.h"
  24 #include "../../common/integer.h"
  25
  26 // Don't use ifdef...
  27 #if HAVE_VISIBILITY
  28 #       define LZMA_API __attribute__((__visibility__("default")))
  29 #else
  30 #       define LZMA_API
  31 #endif
  32
  33
  34 // These allow helping the compiler in some often-executed branches, whose
  35 // result is almost always the same.
  36 #ifdef __GNUC__
  37 #       define likely(expr) __builtin_expect(expr, true)
  38 #       define unlikely(expr) __builtin_expect(expr, false)
  39 #else
  40 #       define likely(expr) (expr)
  41 #       define unlikely(expr) (expr)
  42 #endif
  43
  44
  45 /// Size of temporary buffers needed in some filters
  46 #define LZMA_BUFFER_SIZE 4096
  47
  48
  49 /// Start of internal Filter ID space. These IDs must never be used
  50 /// in Streams.
  51 #define LZMA_FILTER_RESERVED_START (LZMA_VLI_C(1) << 62)
  52
  53
  54 /// Internal helper filter used by Subblock decoder. It is mapped to an
  55 /// otherwise invalid Filter ID, which is impossible to get from any input
  56 /// file (even if malicious file).
  57 #define LZMA_FILTER_SUBBLOCK_HELPER LZMA_VLI_C(0x7000000000000001)
  58
  59
  60 /// Supported flags that can be passed to lzma_stream_decoder()
  61 /// or lzma_auto_decoder().
  62 #define LZMA_SUPPORTED_FLAGS \
  63         ( LZMA_TELL_NO_CHECK \
  64         | LZMA_TELL_UNSUPPORTED_CHECK \
  65         | LZMA_TELL_ANY_CHECK \
  66         | LZMA_CONCATENATED )
  67
  68
  69 ///////////
  70 // Types //
  71 ///////////
  72
  73 /// Type of encoder/decoder specific data; the actual structure is defined
  74 /// differently in different coders.
  75 typedef struct lzma_coder_s lzma_coder;
  76
  77 typedef struct lzma_next_coder_s lzma_next_coder;
  78
  79 typedef struct lzma_filter_info_s lzma_filter_info;
  80
  81
  82 /// Type of a function used to initialize a filter encoder or decoder
  83 typedef lzma_ret (*lzma_init_function)(
  84                 lzma_next_coder *next, lzma_allocator *allocator,
  85                 const lzma_filter_info *filters);
  86
  87 /// Type of a function to do some kind of coding work (filters, Stream,
  88 /// Block encoders/decoders etc.). Some special coders use don't use both
  89 /// input and output buffers, but for simplicity they still use this same
  90 /// function prototype.
  91 typedef lzma_ret (*lzma_code_function)(
  92                 lzma_coder *coder, lzma_allocator *allocator,
  93                 const uint8_t *restrict in, size_t *restrict in_pos,
  94                 size_t in_size, uint8_t *restrict out,
  95                 size_t *restrict out_pos, size_t out_size,
  96                 lzma_action action);
  97
  98 /// Type of a function to free the memory allocated for the coder
  99 typedef void (*lzma_end_function)(
 100                 lzma_coder *coder, lzma_allocator *allocator);
 101
 102
 103 /// Raw coder validates and converts an array of lzma_filter structures to
 104 /// an array of lzma_filter_info structures. This array is used with
 105 /// lzma_next_filter_init to initialize the filter chain.
 106 struct lzma_filter_info_s {
 107         /// Pointer to function used to initialize the filter.
 108         /// This is NULL to indicate end of array.
 109         lzma_init_function init;
 110
 111         /// Pointer to filter's options structure
 112         void *options;
 113 };
 114
 115
 116 /// Hold data and function pointers of the next filter in the chain.
 117 struct lzma_next_coder_s {
 118         /// Pointer to coder-specific data
 119         lzma_coder *coder;
 120
 121         /// "Pointer" to init function. This is never called here.
 122         /// We need only to detect if we are initializing a coder
 123         /// that was allocated earlier. See lzma_next_coder_init and
 124         /// lzma_next_strm_init macros in this file.
 125         uintptr_t init;
 126
 127         /// Pointer to function to do the actual coding
 128         lzma_code_function code;
 129
 130         /// Pointer to function to free lzma_next_coder.coder. This can
 131         /// be NULL; in that case, lzma_free is called to free
 132         /// lzma_next_coder.coder.
 133         lzma_end_function end;
 134
 135         /// Pointer to function to return the type of the integrity check.
 136         /// Most coders won't support this.
 137         lzma_check (*get_check)(const lzma_coder *coder);
 138
 139         /// Pointer to function to get and/or change the memory usage limit.
 140         /// If memlimit == 0, the limit is not changed.
 141         uint64_t (*memconfig)(lzma_coder *coder, uint64_t memlimit);
 142 };
 143
 144
 145 /// Macro to initialize lzma_next_coder structure
 146 #define LZMA_NEXT_CODER_INIT \
 147         (lzma_next_coder){ \
 148                 .coder = NULL, \
 149                 .init = (uintptr_t)(NULL), \
 150                 .code = NULL, \
 151                 .end = NULL, \
 152                 .get_check = NULL, \
 153                 .memconfig = NULL, \
 154         }
 155
 156
 157 /// Internal data for lzma_strm_init, lzma_code, and lzma_end. A pointer to
 158 /// this is stored in lzma_stream.
 159 struct lzma_internal_s {
 160         /// The actual coder that should do something useful
 161         lzma_next_coder next;
 162
 163         /// Track the state of the coder. This is used to validate arguments
 164         /// so that the actual coders can rely on e.g. that LZMA_SYNC_FLUSH
 165         /// is used on every call to lzma_code until next.code has returned
 166         /// LZMA_STREAM_END.
 167         enum {
 168                 ISEQ_RUN,
 169                 ISEQ_SYNC_FLUSH,
 170                 ISEQ_FULL_FLUSH,
 171                 ISEQ_FINISH,
 172                 ISEQ_END,
 173                 ISEQ_ERROR,
 174         } sequence;
 175
 176         /// A copy of lzma_stream avail_in. This is used to verify that the
 177         /// amount of input doesn't change once e.g. LZMA_FINISH has been
 178         /// used.
 179         size_t avail_in;
 180
 181         /// Indicates which lzma_action values are allowed by next.code.
 182         bool supported_actions[4];
 183
 184         /// If true, lzma_code will return LZMA_BUF_ERROR if no progress was
 185         /// made (no input consumed and no output produced by next.code).
 186         bool allow_buf_error;
 187 };
 188
 189
 190 ///////////////
 191 // Functions //
 192 ///////////////
 193
 194 /// Allocates memory
 195 extern void *lzma_alloc(size_t size, lzma_allocator *allocator)
 196                 lzma_attribute((malloc));
 197
 198 /// Frees memory
 199 extern void lzma_free(void *ptr, lzma_allocator *allocator);
 200
 201
 202 /// Allocates strm->internal if it is NULL, and initializes *strm and
 203 /// strm->internal. This function is only called via lzma_next_strm_init macro.
 204 extern lzma_ret lzma_strm_init(lzma_stream *strm);
 205
 206 /// Initializes the next filter in the chain, if any. This takes care of
 207 /// freeing the memory of previously initialized filter if it is different
 208 /// than the filter being initialized now. This way the actual filter
 209 /// initialization functions don't need to use lzma_next_coder_init macro.
 210 extern lzma_ret lzma_next_filter_init(lzma_next_coder *next,
 211                 lzma_allocator *allocator, const lzma_filter_info *filters);
 212
 213 /// Frees the memory allocated for next->coder either using next->end or,
 214 /// if next->end is NULL, using lzma_free.
 215 extern void lzma_next_end(lzma_next_coder *next, lzma_allocator *allocator);
 216
 217
 218 /// Copy as much data as possible from in[] to out[] and update *in_pos
 219 /// and *out_pos accordingly. Returns the number of bytes copied.
 220 extern size_t lzma_bufcpy(const uint8_t *restrict in, size_t *restrict in_pos,
 221                 size_t in_size, uint8_t *restrict out,
 222                 size_t *restrict out_pos, size_t out_size);
 223
 224
 225 /// \brief      Return if expression doesn't evaluate to LZMA_OK
 226 ///
 227 /// There are several situations where we want to return immediatelly
 228 /// with the value of expr if it isn't LZMA_OK. This macro shortens
 229 /// the code a little.
 230 #define return_if_error(expr) \
 231 do { \
 232         const lzma_ret ret_ = (expr); \
 233         if (ret_ != LZMA_OK) \
 234                 return ret_; \
 235 } while (0)
 236
 237
 238 /// If next isn't already initialized, free the previous coder. Then mark
 239 /// that next is _possibly_ initialized for the coder using this macro.
 240 /// "Possibly" means that if e.g. allocation of next->coder fails, the
 241 /// structure isn't actually initialized for this coder, but leaving
 242 /// next->init to func is still OK.
 243 #define lzma_next_coder_init(func, next, allocator) \
 244 do { \
 245         if ((uintptr_t)(&func) != (next)->init) \
 246                 lzma_next_end(next, allocator); \
 247         (next)->init = (uintptr_t)(&func); \
 248 } while (0)
 249
 250
 251 /// Initializes lzma_strm and calls func() to initialize strm->internal->next.
 252 /// (The function being called will use lzma_next_coder_init()). If
 253 /// initialization fails, memory that wasn't freed by func() is freed
 254 /// along strm->internal.
 255 #define lzma_next_strm_init(func, strm, ...) \
 256 do { \
 257         return_if_error(lzma_strm_init(strm)); \
 258         const lzma_ret ret_ = func(&(strm)->internal->next, \
 259                         (strm)->allocator, __VA_ARGS__); \
 260         if (ret_ != LZMA_OK) { \
 261                 lzma_end(strm); \
 262                 return ret_; \
 263         } \
 264 } while (0)
 265
 266 #endif