2 * \file lzma/memlimit.h
3 * \brief Memory usage limitter
5 * \author Copyright (C) 1999-2006 Igor Pavlov
6 * \author Copyright (C) 2007 Lasse Collin
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.
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.
19 #ifndef LZMA_H_INTERNAL
20 # error Never include this file directly. Use <lzma.h> instead.
25 * \brief Opaque data type used with the memory usage limitting functions
27 typedef struct lzma_memlimit_s lzma_memlimit;
31 * \brief Allocates and initializes a new lzma_memlimit structure
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.
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.
42 * The memory limitter functions are not tied to limitting memory usage
43 * with liblzma itself. You can use them with anything you like.
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.
49 * \param limit Initial memory usage limit in bytes
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.
57 * \note Excluding lzma_memlimit_usage(), the functions whose name begin
58 * lzma_memlimit_ can be used even if lzma_init() hasn't been
61 extern lzma_memlimit *lzma_memlimit_create(size_t limit);
65 * \brief Sets a new memory usage limit
67 * \param mem Pointer to a lzma_memlimit structure returned
68 * earlier by lzma_memry_limit_create().
69 * \param limit New memory usage limit
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
76 extern void lzma_memlimit_set(lzma_memlimit *mem, size_t limit);
80 * \brief Gets the current memory usage limit
82 extern size_t lzma_memlimit_get(const lzma_memlimit *mem);
86 * \brief Gets the amount of currently allocated memory
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().
92 extern size_t lzma_memlimit_used(const lzma_memlimit *mem);
96 * \brief Gets the number of allocations owned by the memory limitter
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.
102 extern size_t lzma_memlimit_count(const lzma_memlimit *mem);
106 * \brief Allocates memory with malloc() if memory limit allows
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.
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.
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.
124 extern void *lzma_memlimit_alloc(
125 lzma_memlimit *mem, size_t nmemb, size_t size);
129 * \brief Removes the pointer from memory limitting list
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().
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.
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
145 extern void lzma_memlimit_detach(lzma_memlimit *mem, void *ptr);
149 * \brief Frees memory and updates the memory limit list
151 * This is like lzma_memlimit_detach() but also frees the given pointer.
153 extern void lzma_memlimit_free(lzma_memlimit *mem, void *ptr);
157 * \brief Frees the memory allocated for and by the memory usage limitter
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
166 extern void lzma_memlimit_end(
167 lzma_memlimit *mem, lzma_bool free_allocated);