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