src/liblzma/api/lzma/memlimit.h

   1 /**
   2  * \file        lzma/memlimit.h
   3  * \brief       Memory usage limitter
   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 limitting 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 limitter functions are not tied to limitting 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 number of allocations owned by the memory limitter
  97  *
  98  * The count does not include the helper structures; if no memory has
  99  * been allocated with lzma_memlimit_alloc() or all memory allocated
 100  * has been freed or detached, this will return zero.
 101  */
 102 extern size_t lzma_memlimit_count(const lzma_memlimit *mem);
 103
 104
 105 /**
 106  * \brief       Allocates memory with malloc() if memory limit allows
 107  *
 108  * \param       mem     Pointer to a lzma_memlimit structure returned
 109  *                      earlier by lzma_memry_limit_create().
 110  * \param       nmemb   Number of elements to allocate. While liblzma always
 111  *                      sets this to one, this function still takes the
 112  *                      value of nmemb into account to keep the function
 113  *                      usable with zlib and libbzip2.
 114  * \param       size    Size of an element.
 115  *
 116  * \return      Pointer to memory allocated with malloc(nmemb * size),
 117  *              except if nmemb * size == 0 which returns malloc(1).
 118  *              On error, NULL is returned.
 119  *
 120  * \note        This function assumes that nmemb * size is at maximum of
 121  *              SIZE_MAX. If it isn't, an overflow will occur resulting
 122  *              invalid amount of memory being allocated.
 123  */
 124 extern void *lzma_memlimit_alloc(
 125                 lzma_memlimit *mem, size_t nmemb, size_t size);
 126
 127
 128 /**
 129  * \brief       Removes the pointer from memory limitting list
 130  *
 131  * \param       mem     Pointer to a lzma_memlimit structure returned
 132  *                      earlier by lzma_memry_limit_create().
 133  * \param       ptr     Pointer returned earlier by lzma_memlimit_alloc().
 134  *
 135  * This function removes ptr from the internal list and decreases the
 136  * counter of used memory accordingly. The ptr itself isn't freed. This is
 137  * useful when Extra Records allocated by liblzma using lzma_memlimit
 138  * are needed by the application and must not be freed when the
 139  * lzma_memlimit structure is destroyed.
 140  *
 141  * It is OK to call this function with ptr that hasn't been allocated with
 142  * lzma_memlimit_alloc(). In that case, this has no effect other than wasting
 143  * a few CPU cycles.
 144  */
 145 extern void lzma_memlimit_detach(lzma_memlimit *mem, void *ptr);
 146
 147
 148 /**
 149  * \brief       Frees memory and updates the memory limit list
 150  *
 151  * This is like lzma_memlimit_detach() but also frees the given pointer.
 152  */
 153 extern void lzma_memlimit_free(lzma_memlimit *mem, void *ptr);
 154
 155
 156 /**
 157  * \brief       Frees the memory allocated for and by the memory usage limitter
 158  *
 159  * \param       mem             Pointer to memory limitter
 160  * \param       free_allocated  If this is non-zero, all the memory allocated
 161  *                              by lzma_memlimit_alloc() using *mem is also
 162  *                              freed if it hasn't already been freed with
 163  *                              lzma_memlimit_free(). Usually this should be
 164  *                              set to true.
 165  */
 166 extern void lzma_memlimit_end(
 167                 lzma_memlimit *mem, lzma_bool free_allocated);