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
  63
  64 /**
  65  * \brief       Sets a new memory usage limit
  66  *
  67  * \param       mem     Pointer to a lzma_memlimit structure returned
  68  *                      earlier by lzma_memry_limit_create().
  69  * \param       limit   New memory usage limit
  70  *
  71  * The new usage limit may be smaller than the amount of memory currently
  72  * allocated via *mem: New allocations will fail until enough memory has
  73  * been freed or a new limit is set, but the existing allocatations will
  74  * stay untouched.
  75  */
  76 extern void lzma_memlimit_set(lzma_memlimit *mem, size_t limit);
  77
  78
  79 /**
  80  * \brief       Gets the current memory usage limit
  81  */
  82 extern size_t lzma_memlimit_get(const lzma_memlimit *mem);
  83
  84
  85 /**
  86  * \brief       Gets the amount of currently allocated memory
  87  *
  88  * \note        This value includes the sizes of some helper structures,
  89  *              thus it will always be larger than the total number of
  90  *              bytes allocated via lzma_memlimit_alloc().
  91  */
  92 extern size_t lzma_memlimit_used(const lzma_memlimit *mem);
  93
  94
  95 /**
  96  * \brief       Gets the maximum amount of memory required in total
  97  *
  98  * Returns how much memory was or would have been allocated at the same time.
  99  * If lzma_memlimit_alloc() was requested so much memory that the limit
 100  * would have been exceeded or malloc() simply ran out of memory, the
 101  * requested amount is still included to the value returned by
 102  * lzma_memlimit_max(). This may be used as a hint how much bigger memory
 103  * limit would have been needed.
 104  *
 105  * If the clear flag is set, the internal variable holding the maximum
 106  * value is set to the current memory usage (the same value as returned
 107  * by lzma_memlimit_used()).
 108  *
 109  * \note        Usually liblzma needs to allocate many chunks of memory, and
 110  *              displaying a message like "memory usage limit reached, at
 111  *              least 1024 bytes would have been needed" may be confusing,
 112  *              because the next allocation could have been e.g. 8 MiB.
 113  *
 114  * \todo        The description of this function is unclear.
 115  */
 116 extern size_t lzma_memlimit_max(lzma_memlimit *mem, lzma_bool clear);
 117
 118
 119 /**
 120  * \brief       Checks if memory limit was reached at some point
 121  *
 122  * This function is useful to find out if the reason for LZMA_MEM_ERROR
 123  * was running out of memory or hitting the memory usage limit imposed
 124  * by lzma_memlimit_alloc(). If the clear argument is true, the internal
 125  * flag, that indicates that limit was reached, is cleared.
 126  */
 127 extern lzma_bool lzma_memlimit_reached(lzma_memlimit *mem, lzma_bool clear);
 128
 129
 130 /**
 131  * \brief       Gets the number of allocations owned by the memory limiter
 132  *
 133  * The count does not include the helper structures; if no memory has
 134  * been allocated with lzma_memlimit_alloc() or all memory allocated
 135  * has been freed or detached, this will return zero.
 136  */
 137 extern size_t lzma_memlimit_count(const lzma_memlimit *mem);
 138
 139
 140 /**
 141  * \brief       Allocates memory with malloc() if memory limit allows
 142  *
 143  * \param       mem     Pointer to a lzma_memlimit structure returned
 144  *                      earlier by lzma_memry_limit_create().
 145  * \param       nmemb   Number of elements to allocate. While liblzma always
 146  *                      sets this to one, this function still takes the
 147  *                      value of nmemb into account to keep the function
 148  *                      usable with zlib and libbzip2.
 149  * \param       size    Size of an element.
 150  *
 151  * \return      Pointer to memory allocated with malloc(nmemb * size),
 152  *              except if nmemb * size == 0 which returns malloc(1).
 153  *              On error, NULL is returned.
 154  *
 155  * \note        This function assumes that nmemb * size is at maximum of
 156  *              SIZE_MAX. If it isn't, an overflow will occur resulting
 157  *              invalid amount of memory being allocated.
 158  */
 159 extern void *lzma_memlimit_alloc(
 160                 lzma_memlimit *mem, size_t nmemb, size_t size);
 161
 162
 163 /**
 164  * \brief       Removes the pointer from memory limiting list
 165  *
 166  * \param       mem     Pointer to a lzma_memlimit structure returned
 167  *                      earlier by lzma_memry_limit_create().
 168  * \param       ptr     Pointer returned earlier by lzma_memlimit_alloc().
 169  *
 170  * This function removes ptr from the internal list and decreases the
 171  * counter of used memory accordingly. The ptr itself isn't freed. This is
 172  * useful when Extra Records allocated by liblzma using lzma_memlimit
 173  * are needed by the application and must not be freed when the
 174  * lzma_memlimit structure is destroyed.
 175  *
 176  * It is OK to call this function with ptr that hasn't been allocated with
 177  * lzma_memlimit_alloc(). In that case, this has no effect other than wasting
 178  * a few CPU cycles.
 179  */
 180 extern void lzma_memlimit_detach(lzma_memlimit *mem, void *ptr);
 181
 182
 183 /**
 184  * \brief       Frees memory and updates the memory limit list
 185  *
 186  * This is like lzma_memlimit_detach() but also frees the given pointer.
 187  */
 188 extern void lzma_memlimit_free(lzma_memlimit *mem, void *ptr);
 189
 190
 191 /**
 192  * \brief       Frees the memory allocated for and by the memory usage limiter
 193  *
 194  * \param       mem             Pointer to memory limiter
 195  * \param       free_allocated  If this is non-zero, all the memory allocated
 196  *                              by lzma_memlimit_alloc() using *mem is also
 197  *                              freed if it hasn't already been freed with
 198  *                              lzma_memlimit_free(). Usually this should be
 199  *                              set to true.
 200  */
 201 extern void lzma_memlimit_end(
 202                 lzma_memlimit *mem, lzma_bool free_allocated);