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