src/liblzma/api/lzma/memlimit.h

   1 /**
   2  * \file        lzma/memlimit.h
   3  * \brief       Memory usage limiter
   4  *
   5  * \author      Copyright (C) 1999-2006 Igor Pavlov
   6  * \author      Copyright (C) 2007 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 #ifndef LZMA_H_INTERNAL
  20 #       error Never include this file directly. Use <lzma.h> instead.
  21 #endif
  22
  23
  24 /**
  25  * \brief       Opaque data type used with the memory usage limiting functions
  26  */
  27 typedef struct lzma_memlimit_s lzma_memlimit;
  28
  29
  30 /**
  31  * \brief       Allocates and initializes a new lzma_memlimit structure
  32  *
  33  * It is easy to make liblzma to use huge amounts of memory. This can
  34  * be a problem especially with the decoder, since it a file requiring
  35  * huge amounts of memory to uncompress could allow even a denial of
  36  * service attack if the memory usage wasn't limited.
  37  *
  38  * liblzma provides a set of functions to control memory usage. Pointers
  39  * to these functions can be used in lzma_allocator structure, which makes
  40  * it easy to limit memory usage with liblzma.
  41  *
  42  * The memory limiter functions are not tied to limiting memory usage
  43  * with liblzma itself. You can use them with anything you like.
  44  *
  45  * In multi-threaded applications, only one thread at once may use the same
  46  * lzma_memlimit structure. If there is a need, this limitation may
  47  * be removed in future versions without breaking the libary API/ABI.
  48  *
  49  * \param       limit   Initial memory usage limit in bytes
  50  *
  51  * \return      Pointer to allocated and initialized lzma_memlimit
  52  *              structure. On error, NULL is returned. The reason behind
  53  *              an error is either that malloc() failed or that the given
  54  *              limit was so small that it didn't allow allocating even
  55  *              the lzma_memlimit structure itself.
  56  *
  57  * \note        Excluding lzma_memlimit_usage(), the functions whose name begin
  58  *              lzma_memlimit_ can be used even if lzma_init() hasn't been
  59  *              called.
  60  */
  61 extern lzma_memlimit *lzma_memlimit_create(size_t limit)
  62                 lzma_attr_warn_unused_result;
  63
  64
  65 /**
  66  * \brief       Sets a new memory usage limit
  67  *
  68  * \param       mem     Pointer to a lzma_memlimit structure returned
  69  *                      earlier by lzma_memry_limit_create().
  70  * \param       limit   New memory usage limit
  71  *
  72  * The new usage limit may be smaller than the amount of memory currently
  73  * allocated via *mem: New allocations will fail until enough memory has
  74  * been freed or a new limit is set, but the existing allocatations will
  75  * stay untouched.
  76  */
  77 extern void lzma_memlimit_set(lzma_memlimit *mem, size_t limit);
  78
  79
  80 /**
  81  * \brief       Gets the current memory usage limit
  82  */
  83 extern size_t lzma_memlimit_get(const lzma_memlimit *mem)
  84                 lzma_attr_pure;
  85
  86
  87 /**
  88  * \brief       Gets the amount of currently allocated memory
  89  *
  90  * \note        This value includes the sizes of some helper structures,
  91  *              thus it will always be larger than the total number of
  92  *              bytes allocated via lzma_memlimit_alloc().
  93  */
  94 extern size_t lzma_memlimit_used(const lzma_memlimit *mem)
  95                 lzma_attr_pure;
  96
  97
  98 /**
  99  * \brief       Gets the maximum amount of memory required in total
 100  *
 101  * Returns how much memory was or would have been allocated at the same time.
 102  * If lzma_memlimit_alloc() was requested so much memory that the limit
 103  * would have been exceeded or malloc() simply ran out of memory, the
 104  * requested amount is still included to the value returned by
 105  * lzma_memlimit_max(). This may be used as a hint how much bigger memory
 106  * limit would have been needed.
 107  *
 108  * If the clear flag is set, the internal variable holding the maximum
 109  * value is set to the current memory usage (the same value as returned
 110  * by lzma_memlimit_used()).
 111  *
 112  * \note        Usually liblzma needs to allocate many chunks of memory, and
 113  *              displaying a message like "memory usage limit reached, at
 114  *              least 1024 bytes would have been needed" may be confusing,
 115  *              because the next allocation could have been e.g. 8 MiB.
 116  *
 117  * \todo        The description of this function is unclear.
 118  */
 119 extern size_t lzma_memlimit_max(lzma_memlimit *mem, lzma_bool clear);
 120
 121
 122 /**
 123  * \brief       Checks if memory limit was reached at some point
 124  *
 125  * This function is useful to find out if the reason for LZMA_MEM_ERROR
 126  * was running out of memory or hitting the memory usage limit imposed
 127  * by lzma_memlimit_alloc(). If the clear argument is true, the internal
 128  * flag, that indicates that limit was reached, is cleared.
 129  */
 130 extern lzma_bool lzma_memlimit_reached(lzma_memlimit *mem, lzma_bool clear);
 131
 132
 133 /**
 134  * \brief       Gets the number of allocations owned by the memory limiter
 135  *
 136  * The count does not include the helper structures; if no memory has
 137  * been allocated with lzma_memlimit_alloc() or all memory allocated
 138  * has been freed or detached, this will return zero.
 139  */
 140 extern size_t lzma_memlimit_count(const lzma_memlimit *mem)
 141                 lzma_attr_pure;
 142
 143
 144 /**
 145  * \brief       Allocates memory with malloc() if memory limit allows
 146  *
 147  * \param       mem     Pointer to a lzma_memlimit structure returned
 148  *                      earlier by lzma_memry_limit_create().
 149  * \param       nmemb   Number of elements to allocate. While liblzma always
 150  *                      sets this to one, this function still takes the
 151  *                      value of nmemb into account to keep the function
 152  *                      usable with zlib and libbzip2.
 153  * \param       size    Size of an element.
 154  *
 155  * \return      Pointer to memory allocated with malloc(nmemb * size),
 156  *              except if nmemb * size == 0 which returns malloc(1).
 157  *              On error, NULL is returned.
 158  *
 159  * \note        This function assumes that nmemb * size is at maximum of
 160  *              SIZE_MAX. If it isn't, an overflow will occur resulting
 161  *              invalid amount of memory being allocated.
 162  */
 163 extern void *lzma_memlimit_alloc(
 164                 lzma_memlimit *mem, size_t nmemb, size_t size)
 165                 lzma_attr_warn_unused_result;
 166
 167
 168 /**
 169  * \brief       Removes the pointer from memory limiting list
 170  *
 171  * \param       mem     Pointer to a lzma_memlimit structure returned
 172  *                      earlier by lzma_memry_limit_create().
 173  * \param       ptr     Pointer returned earlier by lzma_memlimit_alloc().
 174  *
 175  * This function removes ptr from the internal list and decreases the
 176  * counter of used memory accordingly. The ptr itself isn't freed. This is
 177  * useful when Extra Records allocated by liblzma using lzma_memlimit
 178  * are needed by the application and must not be freed when the
 179  * lzma_memlimit structure is destroyed.
 180  *
 181  * It is OK to call this function with ptr that hasn't been allocated with
 182  * lzma_memlimit_alloc(). In that case, this has no effect other than wasting
 183  * a few CPU cycles.
 184  */
 185 extern void lzma_memlimit_detach(lzma_memlimit *mem, void *ptr);
 186
 187
 188 /**
 189  * \brief       Frees memory and updates the memory limit list
 190  *
 191  * This is like lzma_memlimit_detach() but also frees the given pointer.
 192  */
 193 extern void lzma_memlimit_free(lzma_memlimit *mem, void *ptr);
 194
 195
 196 /**
 197  * \brief       Frees the memory allocated for and by the memory usage limiter
 198  *
 199  * \param       mem             Pointer to memory limiter
 200  * \param       free_allocated  If this is non-zero, all the memory allocated
 201  *                              by lzma_memlimit_alloc() using *mem is also
 202  *                              freed if it hasn't already been freed with
 203  *                              lzma_memlimit_free(). Usually this should be
 204  *                              set to true.
 205  */
 206 extern void lzma_memlimit_end(
 207                 lzma_memlimit *mem, lzma_bool free_allocated);