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