]> git.sesse.net Git - ffmpeg/blob - libavutil/mem.h
avcodec/mobiclip: Don't check for errors for complete VLCs
[ffmpeg] / libavutil / mem.h
1 /*
2  * copyright (c) 2006 Michael Niedermayer <michaelni@gmx.at>
3  *
4  * This file is part of FFmpeg.
5  *
6  * FFmpeg is free software; you can redistribute it and/or
7  * modify it under the terms of the GNU Lesser General Public
8  * License as published by the Free Software Foundation; either
9  * version 2.1 of the License, or (at your option) any later version.
10  *
11  * FFmpeg is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
14  * Lesser General Public License for more details.
15  *
16  * You should have received a copy of the GNU Lesser General Public
17  * License along with FFmpeg; if not, write to the Free Software
18  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
19  */
20
21 /**
22  * @file
23  * @ingroup lavu_mem
24  * Memory handling functions
25  */
26
27 #ifndef AVUTIL_MEM_H
28 #define AVUTIL_MEM_H
29
30 #include <limits.h>
31 #include <stdint.h>
32
33 #include "attributes.h"
34 #include "error.h"
35 #include "avutil.h"
36
37 /**
38  * @addtogroup lavu_mem
39  * Utilities for manipulating memory.
40  *
41  * FFmpeg has several applications of memory that are not required of a typical
42  * program. For example, the computing-heavy components like video decoding and
43  * encoding can be sped up significantly through the use of aligned memory.
44  *
45  * However, for each of FFmpeg's applications of memory, there might not be a
46  * recognized or standardized API for that specific use. Memory alignment, for
47  * instance, varies wildly depending on operating systems, architectures, and
48  * compilers. Hence, this component of @ref libavutil is created to make
49  * dealing with memory consistently possible on all platforms.
50  *
51  * @{
52  *
53  * @defgroup lavu_mem_macros Alignment Macros
54  * Helper macros for declaring aligned variables.
55  * @{
56  */
57
58 /**
59  * @def DECLARE_ALIGNED(n,t,v)
60  * Declare a variable that is aligned in memory.
61  *
62  * @code{.c}
63  * DECLARE_ALIGNED(16, uint16_t, aligned_int) = 42;
64  * DECLARE_ALIGNED(32, uint8_t, aligned_array)[128];
65  *
66  * // The default-alignment equivalent would be
67  * uint16_t aligned_int = 42;
68  * uint8_t aligned_array[128];
69  * @endcode
70  *
71  * @param n Minimum alignment in bytes
72  * @param t Type of the variable (or array element)
73  * @param v Name of the variable
74  */
75
76 /**
77  * @def DECLARE_ASM_ALIGNED(n,t,v)
78  * Declare an aligned variable appropriate for use in inline assembly code.
79  *
80  * @code{.c}
81  * DECLARE_ASM_ALIGNED(16, uint64_t, pw_08) = UINT64_C(0x0008000800080008);
82  * @endcode
83  *
84  * @param n Minimum alignment in bytes
85  * @param t Type of the variable (or array element)
86  * @param v Name of the variable
87  */
88
89 /**
90  * @def DECLARE_ASM_CONST(n,t,v)
91  * Declare a static constant aligned variable appropriate for use in inline
92  * assembly code.
93  *
94  * @code{.c}
95  * DECLARE_ASM_CONST(16, uint64_t, pw_08) = UINT64_C(0x0008000800080008);
96  * @endcode
97  *
98  * @param n Minimum alignment in bytes
99  * @param t Type of the variable (or array element)
100  * @param v Name of the variable
101  */
102
103 #if defined(__INTEL_COMPILER) && __INTEL_COMPILER < 1110 || defined(__SUNPRO_C)
104     #define DECLARE_ALIGNED(n,t,v)      t __attribute__ ((aligned (n))) v
105     #define DECLARE_ASM_ALIGNED(n,t,v)  t __attribute__ ((aligned (n))) v
106     #define DECLARE_ASM_CONST(n,t,v)    const t __attribute__ ((aligned (n))) v
107 #elif defined(__DJGPP__)
108     #define DECLARE_ALIGNED(n,t,v)      t __attribute__ ((aligned (FFMIN(n, 16)))) v
109     #define DECLARE_ASM_ALIGNED(n,t,v)  t av_used __attribute__ ((aligned (FFMIN(n, 16)))) v
110     #define DECLARE_ASM_CONST(n,t,v)    static const t av_used __attribute__ ((aligned (FFMIN(n, 16)))) v
111 #elif defined(__GNUC__) || defined(__clang__)
112     #define DECLARE_ALIGNED(n,t,v)      t __attribute__ ((aligned (n))) v
113     #define DECLARE_ASM_ALIGNED(n,t,v)  t av_used __attribute__ ((aligned (n))) v
114     #define DECLARE_ASM_CONST(n,t,v)    static const t av_used __attribute__ ((aligned (n))) v
115 #elif defined(_MSC_VER)
116     #define DECLARE_ALIGNED(n,t,v)      __declspec(align(n)) t v
117     #define DECLARE_ASM_ALIGNED(n,t,v)  __declspec(align(n)) t v
118     #define DECLARE_ASM_CONST(n,t,v)    __declspec(align(n)) static const t v
119 #else
120     #define DECLARE_ALIGNED(n,t,v)      t v
121     #define DECLARE_ASM_ALIGNED(n,t,v)  t v
122     #define DECLARE_ASM_CONST(n,t,v)    static const t v
123 #endif
124
125 /**
126  * @}
127  */
128
129 /**
130  * @defgroup lavu_mem_attrs Function Attributes
131  * Function attributes applicable to memory handling functions.
132  *
133  * These function attributes can help compilers emit more useful warnings, or
134  * generate better code.
135  * @{
136  */
137
138 /**
139  * @def av_malloc_attrib
140  * Function attribute denoting a malloc-like function.
141  *
142  * @see <a href="https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-g_t_0040code_007bmalloc_007d-function-attribute-3251">Function attribute `malloc` in GCC's documentation</a>
143  */
144
145 #if AV_GCC_VERSION_AT_LEAST(3,1)
146     #define av_malloc_attrib __attribute__((__malloc__))
147 #else
148     #define av_malloc_attrib
149 #endif
150
151 /**
152  * @def av_alloc_size(...)
153  * Function attribute used on a function that allocates memory, whose size is
154  * given by the specified parameter(s).
155  *
156  * @code{.c}
157  * void *av_malloc(size_t size) av_alloc_size(1);
158  * void *av_calloc(size_t nmemb, size_t size) av_alloc_size(1, 2);
159  * @endcode
160  *
161  * @param ... One or two parameter indexes, separated by a comma
162  *
163  * @see <a href="https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-g_t_0040code_007balloc_005fsize_007d-function-attribute-3220">Function attribute `alloc_size` in GCC's documentation</a>
164  */
165
166 #if AV_GCC_VERSION_AT_LEAST(4,3)
167     #define av_alloc_size(...) __attribute__((alloc_size(__VA_ARGS__)))
168 #else
169     #define av_alloc_size(...)
170 #endif
171
172 /**
173  * @}
174  */
175
176 /**
177  * @defgroup lavu_mem_funcs Heap Management
178  * Functions responsible for allocating, freeing, and copying memory.
179  *
180  * All memory allocation functions have a built-in upper limit of `INT_MAX`
181  * bytes. This may be changed with av_max_alloc(), although exercise extreme
182  * caution when doing so.
183  *
184  * @{
185  */
186
187 /**
188  * Allocate a memory block with alignment suitable for all memory accesses
189  * (including vectors if available on the CPU).
190  *
191  * @param size Size in bytes for the memory block to be allocated
192  * @return Pointer to the allocated block, or `NULL` if the block cannot
193  *         be allocated
194  * @see av_mallocz()
195  */
196 void *av_malloc(size_t size) av_malloc_attrib av_alloc_size(1);
197
198 /**
199  * Allocate a memory block with alignment suitable for all memory accesses
200  * (including vectors if available on the CPU) and zero all the bytes of the
201  * block.
202  *
203  * @param size Size in bytes for the memory block to be allocated
204  * @return Pointer to the allocated block, or `NULL` if it cannot be allocated
205  * @see av_malloc()
206  */
207 void *av_mallocz(size_t size) av_malloc_attrib av_alloc_size(1);
208
209 /**
210  * Allocate a memory block for an array with av_malloc().
211  *
212  * The allocated memory will have size `size * nmemb` bytes.
213  *
214  * @param nmemb Number of element
215  * @param size  Size of a single element
216  * @return Pointer to the allocated block, or `NULL` if the block cannot
217  *         be allocated
218  * @see av_malloc()
219  */
220 av_alloc_size(1, 2) void *av_malloc_array(size_t nmemb, size_t size);
221
222 /**
223  * Allocate a memory block for an array with av_mallocz().
224  *
225  * The allocated memory will have size `size * nmemb` bytes.
226  *
227  * @param nmemb Number of elements
228  * @param size  Size of the single element
229  * @return Pointer to the allocated block, or `NULL` if the block cannot
230  *         be allocated
231  *
232  * @see av_mallocz()
233  * @see av_malloc_array()
234  */
235 av_alloc_size(1, 2) void *av_mallocz_array(size_t nmemb, size_t size);
236
237 /**
238  * Non-inlined equivalent of av_mallocz_array().
239  *
240  * Created for symmetry with the calloc() C function.
241  */
242 void *av_calloc(size_t nmemb, size_t size) av_malloc_attrib;
243
244 /**
245  * Allocate, reallocate, or free a block of memory.
246  *
247  * If `ptr` is `NULL` and `size` > 0, allocate a new block. If `size` is
248  * zero, free the memory block pointed to by `ptr`. Otherwise, expand or
249  * shrink that block of memory according to `size`.
250  *
251  * @param ptr  Pointer to a memory block already allocated with
252  *             av_realloc() or `NULL`
253  * @param size Size in bytes of the memory block to be allocated or
254  *             reallocated
255  *
256  * @return Pointer to a newly-reallocated block or `NULL` if the block
257  *         cannot be reallocated or the function is used to free the memory block
258  *
259  * @warning Unlike av_malloc(), the returned pointer is not guaranteed to be
260  *          correctly aligned.
261  * @see av_fast_realloc()
262  * @see av_reallocp()
263  */
264 void *av_realloc(void *ptr, size_t size) av_alloc_size(2);
265
266 /**
267  * Allocate, reallocate, or free a block of memory through a pointer to a
268  * pointer.
269  *
270  * If `*ptr` is `NULL` and `size` > 0, allocate a new block. If `size` is
271  * zero, free the memory block pointed to by `*ptr`. Otherwise, expand or
272  * shrink that block of memory according to `size`.
273  *
274  * @param[in,out] ptr  Pointer to a pointer to a memory block already allocated
275  *                     with av_realloc(), or a pointer to `NULL`. The pointer
276  *                     is updated on success, or freed on failure.
277  * @param[in]     size Size in bytes for the memory block to be allocated or
278  *                     reallocated
279  *
280  * @return Zero on success, an AVERROR error code on failure
281  *
282  * @warning Unlike av_malloc(), the allocated memory is not guaranteed to be
283  *          correctly aligned.
284  */
285 av_warn_unused_result
286 int av_reallocp(void *ptr, size_t size);
287
288 /**
289  * Allocate, reallocate, or free a block of memory.
290  *
291  * This function does the same thing as av_realloc(), except:
292  * - It takes two size arguments and allocates `nelem * elsize` bytes,
293  *   after checking the result of the multiplication for integer overflow.
294  * - It frees the input block in case of failure, thus avoiding the memory
295  *   leak with the classic
296  *   @code{.c}
297  *   buf = realloc(buf);
298  *   if (!buf)
299  *       return -1;
300  *   @endcode
301  *   pattern.
302  */
303 void *av_realloc_f(void *ptr, size_t nelem, size_t elsize);
304
305 /**
306  * Allocate, reallocate, or free an array.
307  *
308  * If `ptr` is `NULL` and `nmemb` > 0, allocate a new block. If
309  * `nmemb` is zero, free the memory block pointed to by `ptr`.
310  *
311  * @param ptr   Pointer to a memory block already allocated with
312  *              av_realloc() or `NULL`
313  * @param nmemb Number of elements in the array
314  * @param size  Size of the single element of the array
315  *
316  * @return Pointer to a newly-reallocated block or NULL if the block
317  *         cannot be reallocated or the function is used to free the memory block
318  *
319  * @warning Unlike av_malloc(), the allocated memory is not guaranteed to be
320  *          correctly aligned.
321  * @see av_reallocp_array()
322  */
323 av_alloc_size(2, 3) void *av_realloc_array(void *ptr, size_t nmemb, size_t size);
324
325 /**
326  * Allocate, reallocate, or free an array through a pointer to a pointer.
327  *
328  * If `*ptr` is `NULL` and `nmemb` > 0, allocate a new block. If `nmemb` is
329  * zero, free the memory block pointed to by `*ptr`.
330  *
331  * @param[in,out] ptr   Pointer to a pointer to a memory block already
332  *                      allocated with av_realloc(), or a pointer to `NULL`.
333  *                      The pointer is updated on success, or freed on failure.
334  * @param[in]     nmemb Number of elements
335  * @param[in]     size  Size of the single element
336  *
337  * @return Zero on success, an AVERROR error code on failure
338  *
339  * @warning Unlike av_malloc(), the allocated memory is not guaranteed to be
340  *          correctly aligned.
341  */
342 int av_reallocp_array(void *ptr, size_t nmemb, size_t size);
343
344 /**
345  * Reallocate the given buffer if it is not large enough, otherwise do nothing.
346  *
347  * If the given buffer is `NULL`, then a new uninitialized buffer is allocated.
348  *
349  * If the given buffer is not large enough, and reallocation fails, `NULL` is
350  * returned and `*size` is set to 0, but the original buffer is not changed or
351  * freed.
352  *
353  * A typical use pattern follows:
354  *
355  * @code{.c}
356  * uint8_t *buf = ...;
357  * uint8_t *new_buf = av_fast_realloc(buf, &current_size, size_needed);
358  * if (!new_buf) {
359  *     // Allocation failed; clean up original buffer
360  *     av_freep(&buf);
361  *     return AVERROR(ENOMEM);
362  * }
363  * @endcode
364  *
365  * @param[in,out] ptr      Already allocated buffer, or `NULL`
366  * @param[in,out] size     Pointer to the size of buffer `ptr`. `*size` is
367  *                         updated to the new allocated size, in particular 0
368  *                         in case of failure.
369  * @param[in]     min_size Desired minimal size of buffer `ptr`
370  * @return `ptr` if the buffer is large enough, a pointer to newly reallocated
371  *         buffer if the buffer was not large enough, or `NULL` in case of
372  *         error
373  * @see av_realloc()
374  * @see av_fast_malloc()
375  */
376 void *av_fast_realloc(void *ptr, unsigned int *size, size_t min_size);
377
378 /**
379  * Allocate a buffer, reusing the given one if large enough.
380  *
381  * Contrary to av_fast_realloc(), the current buffer contents might not be
382  * preserved and on error the old buffer is freed, thus no special handling to
383  * avoid memleaks is necessary.
384  *
385  * `*ptr` is allowed to be `NULL`, in which case allocation always happens if
386  * `size_needed` is greater than 0.
387  *
388  * @code{.c}
389  * uint8_t *buf = ...;
390  * av_fast_malloc(&buf, &current_size, size_needed);
391  * if (!buf) {
392  *     // Allocation failed; buf already freed
393  *     return AVERROR(ENOMEM);
394  * }
395  * @endcode
396  *
397  * @param[in,out] ptr      Pointer to pointer to an already allocated buffer.
398  *                         `*ptr` will be overwritten with pointer to new
399  *                         buffer on success or `NULL` on failure
400  * @param[in,out] size     Pointer to the size of buffer `*ptr`. `*size` is
401  *                         updated to the new allocated size, in particular 0
402  *                         in case of failure.
403  * @param[in]     min_size Desired minimal size of buffer `*ptr`
404  * @see av_realloc()
405  * @see av_fast_mallocz()
406  */
407 void av_fast_malloc(void *ptr, unsigned int *size, size_t min_size);
408
409 /**
410  * Allocate and clear a buffer, reusing the given one if large enough.
411  *
412  * Like av_fast_malloc(), but all newly allocated space is initially cleared.
413  * Reused buffer is not cleared.
414  *
415  * `*ptr` is allowed to be `NULL`, in which case allocation always happens if
416  * `size_needed` is greater than 0.
417  *
418  * @param[in,out] ptr      Pointer to pointer to an already allocated buffer.
419  *                         `*ptr` will be overwritten with pointer to new
420  *                         buffer on success or `NULL` on failure
421  * @param[in,out] size     Pointer to the size of buffer `*ptr`. `*size` is
422  *                         updated to the new allocated size, in particular 0
423  *                         in case of failure.
424  * @param[in]     min_size Desired minimal size of buffer `*ptr`
425  * @see av_fast_malloc()
426  */
427 void av_fast_mallocz(void *ptr, unsigned int *size, size_t min_size);
428
429 /**
430  * Free a memory block which has been allocated with a function of av_malloc()
431  * or av_realloc() family.
432  *
433  * @param ptr Pointer to the memory block which should be freed.
434  *
435  * @note `ptr = NULL` is explicitly allowed.
436  * @note It is recommended that you use av_freep() instead, to prevent leaving
437  *       behind dangling pointers.
438  * @see av_freep()
439  */
440 void av_free(void *ptr);
441
442 /**
443  * Free a memory block which has been allocated with a function of av_malloc()
444  * or av_realloc() family, and set the pointer pointing to it to `NULL`.
445  *
446  * @code{.c}
447  * uint8_t *buf = av_malloc(16);
448  * av_free(buf);
449  * // buf now contains a dangling pointer to freed memory, and accidental
450  * // dereference of buf will result in a use-after-free, which may be a
451  * // security risk.
452  *
453  * uint8_t *buf = av_malloc(16);
454  * av_freep(&buf);
455  * // buf is now NULL, and accidental dereference will only result in a
456  * // NULL-pointer dereference.
457  * @endcode
458  *
459  * @param ptr Pointer to the pointer to the memory block which should be freed
460  * @note `*ptr = NULL` is safe and leads to no action.
461  * @see av_free()
462  */
463 void av_freep(void *ptr);
464
465 /**
466  * Duplicate a string.
467  *
468  * @param s String to be duplicated
469  * @return Pointer to a newly-allocated string containing a
470  *         copy of `s` or `NULL` if the string cannot be allocated
471  * @see av_strndup()
472  */
473 char *av_strdup(const char *s) av_malloc_attrib;
474
475 /**
476  * Duplicate a substring of a string.
477  *
478  * @param s   String to be duplicated
479  * @param len Maximum length of the resulting string (not counting the
480  *            terminating byte)
481  * @return Pointer to a newly-allocated string containing a
482  *         substring of `s` or `NULL` if the string cannot be allocated
483  */
484 char *av_strndup(const char *s, size_t len) av_malloc_attrib;
485
486 /**
487  * Duplicate a buffer with av_malloc().
488  *
489  * @param p    Buffer to be duplicated
490  * @param size Size in bytes of the buffer copied
491  * @return Pointer to a newly allocated buffer containing a
492  *         copy of `p` or `NULL` if the buffer cannot be allocated
493  */
494 void *av_memdup(const void *p, size_t size);
495
496 /**
497  * Overlapping memcpy() implementation.
498  *
499  * @param dst  Destination buffer
500  * @param back Number of bytes back to start copying (i.e. the initial size of
501  *             the overlapping window); must be > 0
502  * @param cnt  Number of bytes to copy; must be >= 0
503  *
504  * @note `cnt > back` is valid, this will copy the bytes we just copied,
505  *       thus creating a repeating pattern with a period length of `back`.
506  */
507 void av_memcpy_backptr(uint8_t *dst, int back, int cnt);
508
509 /**
510  * @}
511  */
512
513 /**
514  * @defgroup lavu_mem_dynarray Dynamic Array
515  *
516  * Utilities to make an array grow when needed.
517  *
518  * Sometimes, the programmer would want to have an array that can grow when
519  * needed. The libavutil dynamic array utilities fill that need.
520  *
521  * libavutil supports two systems of appending elements onto a dynamically
522  * allocated array, the first one storing the pointer to the value in the
523  * array, and the second storing the value directly. In both systems, the
524  * caller is responsible for maintaining a variable containing the length of
525  * the array, as well as freeing of the array after use.
526  *
527  * The first system stores pointers to values in a block of dynamically
528  * allocated memory. Since only pointers are stored, the function does not need
529  * to know the size of the type. Both av_dynarray_add() and
530  * av_dynarray_add_nofree() implement this system.
531  *
532  * @code
533  * type **array = NULL; //< an array of pointers to values
534  * int    nb    = 0;    //< a variable to keep track of the length of the array
535  *
536  * type to_be_added  = ...;
537  * type to_be_added2 = ...;
538  *
539  * av_dynarray_add(&array, &nb, &to_be_added);
540  * if (nb == 0)
541  *     return AVERROR(ENOMEM);
542  *
543  * av_dynarray_add(&array, &nb, &to_be_added2);
544  * if (nb == 0)
545  *     return AVERROR(ENOMEM);
546  *
547  * // Now:
548  * //  nb           == 2
549  * // &to_be_added  == array[0]
550  * // &to_be_added2 == array[1]
551  *
552  * av_freep(&array);
553  * @endcode
554  *
555  * The second system stores the value directly in a block of memory. As a
556  * result, the function has to know the size of the type. av_dynarray2_add()
557  * implements this mechanism.
558  *
559  * @code
560  * type *array = NULL; //< an array of values
561  * int   nb    = 0;    //< a variable to keep track of the length of the array
562  *
563  * type to_be_added  = ...;
564  * type to_be_added2 = ...;
565  *
566  * type *addr = av_dynarray2_add((void **)&array, &nb, sizeof(*array), NULL);
567  * if (!addr)
568  *     return AVERROR(ENOMEM);
569  * memcpy(addr, &to_be_added, sizeof(to_be_added));
570  *
571  * // Shortcut of the above.
572  * type *addr = av_dynarray2_add((void **)&array, &nb, sizeof(*array),
573  *                               (const void *)&to_be_added2);
574  * if (!addr)
575  *     return AVERROR(ENOMEM);
576  *
577  * // Now:
578  * //  nb           == 2
579  * //  to_be_added  == array[0]
580  * //  to_be_added2 == array[1]
581  *
582  * av_freep(&array);
583  * @endcode
584  *
585  * @{
586  */
587
588 /**
589  * Add the pointer to an element to a dynamic array.
590  *
591  * The array to grow is supposed to be an array of pointers to
592  * structures, and the element to add must be a pointer to an already
593  * allocated structure.
594  *
595  * The array is reallocated when its size reaches powers of 2.
596  * Therefore, the amortized cost of adding an element is constant.
597  *
598  * In case of success, the pointer to the array is updated in order to
599  * point to the new grown array, and the number pointed to by `nb_ptr`
600  * is incremented.
601  * In case of failure, the array is freed, `*tab_ptr` is set to `NULL` and
602  * `*nb_ptr` is set to 0.
603  *
604  * @param[in,out] tab_ptr Pointer to the array to grow
605  * @param[in,out] nb_ptr  Pointer to the number of elements in the array
606  * @param[in]     elem    Element to add
607  * @see av_dynarray_add_nofree(), av_dynarray2_add()
608  */
609 void av_dynarray_add(void *tab_ptr, int *nb_ptr, void *elem);
610
611 /**
612  * Add an element to a dynamic array.
613  *
614  * Function has the same functionality as av_dynarray_add(),
615  * but it doesn't free memory on fails. It returns error code
616  * instead and leave current buffer untouched.
617  *
618  * @return >=0 on success, negative otherwise
619  * @see av_dynarray_add(), av_dynarray2_add()
620  */
621 av_warn_unused_result
622 int av_dynarray_add_nofree(void *tab_ptr, int *nb_ptr, void *elem);
623
624 /**
625  * Add an element of size `elem_size` to a dynamic array.
626  *
627  * The array is reallocated when its number of elements reaches powers of 2.
628  * Therefore, the amortized cost of adding an element is constant.
629  *
630  * In case of success, the pointer to the array is updated in order to
631  * point to the new grown array, and the number pointed to by `nb_ptr`
632  * is incremented.
633  * In case of failure, the array is freed, `*tab_ptr` is set to `NULL` and
634  * `*nb_ptr` is set to 0.
635  *
636  * @param[in,out] tab_ptr   Pointer to the array to grow
637  * @param[in,out] nb_ptr    Pointer to the number of elements in the array
638  * @param[in]     elem_size Size in bytes of an element in the array
639  * @param[in]     elem_data Pointer to the data of the element to add. If
640  *                          `NULL`, the space of the newly added element is
641  *                          allocated but left uninitialized.
642  *
643  * @return Pointer to the data of the element to copy in the newly allocated
644  *         space
645  * @see av_dynarray_add(), av_dynarray_add_nofree()
646  */
647 void *av_dynarray2_add(void **tab_ptr, int *nb_ptr, size_t elem_size,
648                        const uint8_t *elem_data);
649
650 /**
651  * @}
652  */
653
654 /**
655  * @defgroup lavu_mem_misc Miscellaneous Functions
656  *
657  * Other functions related to memory allocation.
658  *
659  * @{
660  */
661
662 /**
663  * Multiply two `size_t` values checking for overflow.
664  *
665  * @param[in]  a,b Operands of multiplication
666  * @param[out] r   Pointer to the result of the operation
667  * @return 0 on success, AVERROR(EINVAL) on overflow
668  */
669 static inline int av_size_mult(size_t a, size_t b, size_t *r)
670 {
671     size_t t = a * b;
672     /* Hack inspired from glibc: don't try the division if nelem and elsize
673      * are both less than sqrt(SIZE_MAX). */
674     if ((a | b) >= ((size_t)1 << (sizeof(size_t) * 4)) && a && t / a != b)
675         return AVERROR(EINVAL);
676     *r = t;
677     return 0;
678 }
679
680 /**
681  * Set the maximum size that may be allocated in one block.
682  *
683  * The value specified with this function is effective for all libavutil's @ref
684  * lavu_mem_funcs "heap management functions."
685  *
686  * By default, the max value is defined as `INT_MAX`.
687  *
688  * @param max Value to be set as the new maximum size
689  *
690  * @warning Exercise extreme caution when using this function. Don't touch
691  *          this if you do not understand the full consequence of doing so.
692  */
693 void av_max_alloc(size_t max);
694
695 /**
696  * @}
697  * @}
698  */
699
700 #endif /* AVUTIL_MEM_H */