Loading...
Searching...
No Matches
Heap Management
libavutil » Memory Management

Functions responsible for allocating, freeing, and copying memory. More...

## Functions

void * | av_malloc (size_t size) av_malloc_attrib
| Allocate a memory block with alignment suitable for all memory accesses (including vectors if available on the CPU).
void * | av_mallocz (size_t size) av_malloc_attrib
| Allocate a memory block with alignment suitable for all memory accesses (including vectors if available on the CPU) and zero all the bytes of the block.
void * | av_malloc_array (size_t nmemb, size_t size)
| Allocate a memory block for an array with av_malloc().
void * | av_calloc (size_t nmemb, size_t size) av_malloc_attrib
| Allocate a memory block for an array with av_mallocz().
void * | av_realloc (void *ptr, size_t size)
| Allocate, reallocate, or free a block of memory.
av_warn_unused_result int | av_reallocp (void *ptr, size_t size)
| Allocate, reallocate, or free a block of memory through a pointer to a pointer.
void * | av_realloc_f (void *ptr, size_t nelem, size_t elsize)
| Allocate, reallocate, or free a block of memory.
void * | av_realloc_array (void *ptr, size_t nmemb, size_t size)
| Allocate, reallocate, or free an array.
int | av_reallocp_array (void *ptr, size_t nmemb, size_t size)
| Allocate, reallocate an array through a pointer to a pointer.
void * | av_fast_realloc (void *ptr, unsigned int *size, size_t min_size)
| Reallocate the given buffer if it is not large enough, otherwise do nothing.
void | av_fast_malloc (void *ptr, unsigned int *size, size_t min_size)
| Allocate a buffer, reusing the given one if large enough.
void | av_fast_mallocz (void *ptr, unsigned int *size, size_t min_size)
| Allocate and clear a buffer, reusing the given one if large enough.
void | av_free (void *ptr)
| Free a memory block which has been allocated with a function of av_malloc() or av_realloc() family.
void | av_freep (void *ptr)
| Free a memory block which has been allocated with a function of av_malloc() or av_realloc() family, and set the pointer pointing to it to NULL.
char * | av_strdup (const char *s) av_malloc_attrib
| Duplicate a string.
char * | av_strndup (const char *s, size_t len) av_malloc_attrib
| Duplicate a substring of a string.
void * | av_memdup (const void *p, size_t size)
| Duplicate a buffer with av_malloc().
void | av_memcpy_backptr (uint8_t *dst, int back, int cnt)
| Overlapping memcpy() implementation.

## Detailed Description

Functions responsible for allocating, freeing, and copying memory.

All memory allocation functions have a built-in upper limit of INT_MAX bytes. This may be changed with av_max_alloc(), although exercise extreme caution when doing so.

## Function Documentation

## av_malloc()

void * av_malloc | ( | size_t | size | ) |

Allocate a memory block with alignment suitable for all memory accesses (including vectors if available on the CPU).

Parameters

  size | Size in bytes for the memory block to be allocated

Returns
  Pointer to the allocated block, or NULL if the block cannot be allocated

See also
  av_mallocz()

Examples
  avio_read_callback.c, hw_decode.c, and qsv_transcode.c.

Referenced by decode_write(), main(), and main().

## av_mallocz()

void * av_mallocz | ( | size_t | size | ) |

Allocate a memory block with alignment suitable for all memory accesses (including vectors if available on the CPU) and zero all the bytes of the block.

Parameters

  size | Size in bytes for the memory block to be allocated

Returns
  Pointer to the allocated block, or NULL if it cannot be allocated

See also
  av_malloc()

Examples
  qsv_decode.c.

Referenced by main().

## av_malloc_array()

void * av_malloc_array | ( | size_t | nmemb,
|  | size_t | size )

Allocate a memory block for an array with av_malloc().

The allocated memory will have size size * nmemb bytes.

Parameters

  nmemb | Number of element
  size | Size of a single element

Returns
  Pointer to the allocated block, or NULL if the block cannot be allocated

See also
  av_malloc()

Examples
  transcode.c.

Referenced by av_malloc_array(), and init_filters().

## av_calloc()

void * av_calloc | ( | size_t | nmemb,
|  | size_t | size )

Allocate a memory block for an array with av_mallocz().

The allocated memory will have size size * nmemb bytes.

Parameters

  nmemb | Number of elements
  size | Size of the single element

Returns
  Pointer to the allocated block, or NULL if the block cannot be allocated

See also
  av_mallocz()
  av_malloc_array()

Examples
  remux.c, and transcode.c.

Referenced by av_calloc(), main(), and open_input_file().

## av_realloc()

void * av_realloc | ( | void * | ptr,
|  | size_t | size )

Allocate, reallocate, or free a block of memory.

If ptr is NULL and size > 0, allocate a new block. Otherwise, expand or shrink that block of memory according to size.

Parameters

  ptr | Pointer to a memory block already allocated with av_realloc() or NULL
  size | Size in bytes of the memory block to be allocated or reallocated

Returns
  Pointer to a newly-reallocated block or NULL if the block cannot be reallocated

Warning
  Unlike av_malloc(), the returned pointer is not guaranteed to be correctly aligned. The returned pointer must be freed after even if size is zero.

See also
  av_fast_realloc()
  av_reallocp()

Referenced by av_realloc().

## av_reallocp()

av_warn_unused_result int av_reallocp | ( | void * | ptr,
|  | size_t | size )

Allocate, reallocate, or free a block of memory through a pointer to a pointer.

If *ptr is NULL and size > 0, allocate a new block. If size is zero, free the memory block pointed to by *ptr. Otherwise, expand or shrink that block of memory according to size.

Parameters

  [in,out] | ptr | Pointer to a pointer to a memory block already allocated with av_realloc(), or a pointer to NULL. The pointer is updated on success, or freed on failure.
  [in] | size | Size in bytes for the memory block to be allocated or reallocated

Returns
  Zero on success, an AVERROR error code on failure

Warning
  Unlike av_malloc(), the allocated memory is not guaranteed to be correctly aligned.

Referenced by av_reallocp().

## av_realloc_f()

void * av_realloc_f | ( | void * | ptr,
|  | size_t | nelem,
|  | size_t | elsize )

Allocate, reallocate, or free a block of memory.

This function does the same thing as av_realloc(), except:

- It takes two size arguments and allocates nelem * elsize bytes, after checking the result of the multiplication for integer overflow.
- It frees the input block in case of failure, thus avoiding the memory leak with the classic
  buf = realloc(buf);
  if (!buf)
  return -1;
  pattern.

Referenced by av_realloc_f().

## av_realloc_array()

void * av_realloc_array | ( | void * | ptr,
|  | size_t | nmemb,
|  | size_t | size )

Allocate, reallocate, or free an array.

If ptr is NULL and nmemb > 0, allocate a new block.

Parameters

  ptr | Pointer to a memory block already allocated with av_realloc() or NULL
  nmemb | Number of elements in the array
  size | Size of the single element of the array

Returns
  Pointer to a newly-reallocated block or NULL if the block cannot be reallocated

Warning
  Unlike av_malloc(), the allocated memory is not guaranteed to be correctly aligned. The returned pointer must be freed after even if nmemb is zero.

See also
  av_reallocp_array()

Referenced by av_realloc_array().

## av_reallocp_array()

int av_reallocp_array | ( | void * | ptr,
|  | size_t | nmemb,
|  | size_t | size )

Allocate, reallocate an array through a pointer to a pointer.

If *ptr is NULL and nmemb > 0, allocate a new block.

Parameters

  [in,out] | ptr | Pointer to a pointer to a memory block already allocated with av_realloc(), or a pointer to NULL. The pointer is updated on success, or freed on failure.
  [in] | nmemb | Number of elements
  [in] | size | Size of the single element

Returns
  Zero on success, an AVERROR error code on failure

Warning
  Unlike av_malloc(), the allocated memory is not guaranteed to be correctly aligned. *ptr must be freed after even if nmemb is zero.

Referenced by av_reallocp_array().

## av_fast_realloc()

void * av_fast_realloc | ( | void * | ptr,
|  | unsigned int * | size,
|  | size_t | min_size )

Reallocate the given buffer if it is not large enough, otherwise do nothing.

If the given buffer is NULL, then a new uninitialized buffer is allocated.

If the given buffer is not large enough, and reallocation fails, NULL is returned and *size is set to 0, but the original buffer is not changed or freed.

A typical use pattern follows:

uint8_t *buf = ...;
uint8_t *new_buf = av_fast_realloc(buf, &current_size, size_needed);
if (!new_buf) {
// Allocation failed; clean up original buffer
av_freep(&buf);
return AVERROR(ENOMEM);
}
AVERROR
#define AVERROR(e)
Definition error.h:45
av_freep
void av_freep(void *ptr)
Free a memory block which has been allocated with a function of av_malloc() or av_realloc() family,...
av_fast_realloc
void * av_fast_realloc(void *ptr, unsigned int *size, size_t min_size)
Reallocate the given buffer if it is not large enough, otherwise do nothing.

Parameters

  [in,out] | ptr | Already allocated buffer, or NULL
  [in,out] | size | Pointer to the size of buffer ptr. *size is updated to the new allocated size, in particular 0 in case of failure.
  [in] | min_size | Desired minimal size of buffer ptr

Returns
  ptr if the buffer is large enough, a pointer to newly reallocated buffer if the buffer was not large enough, or NULL in case of error

See also
  av_realloc()
  av_fast_malloc()

Referenced by av_fast_realloc().

## av_fast_malloc()

void av_fast_malloc | ( | void * | ptr,
|  | unsigned int * | size,
|  | size_t | min_size )

Allocate a buffer, reusing the given one if large enough.

Contrary to av_fast_realloc(), the current buffer contents might not be preserved and on error the old buffer is freed, thus no special handling to avoid memleaks is necessary.

*ptr is allowed to be NULL, in which case allocation always happens if size_needed is greater than 0.

uint8_t *buf = ...;
av_fast_malloc(&buf, &current_size, size_needed);
if (!buf) {
// Allocation failed; buf already freed
return AVERROR(ENOMEM);
}
av_fast_malloc
void av_fast_malloc(void *ptr, unsigned int *size, size_t min_size)
Allocate a buffer, reusing the given one if large enough.

Parameters

  [in,out] | ptr | Pointer to pointer to an already allocated buffer. *ptr will be overwritten with pointer to new buffer on success or NULL on failure
  [in,out] | size | Pointer to the size of buffer *ptr. *size is updated to the new allocated size, in particular 0 in case of failure.
  [in] | min_size | Desired minimal size of buffer *ptr

See also
  av_realloc()
  av_fast_mallocz()

Referenced by av_fast_malloc().

## av_fast_mallocz()

void av_fast_mallocz | ( | void * | ptr,
|  | unsigned int * | size,
|  | size_t | min_size )

Allocate and clear a buffer, reusing the given one if large enough.

Like av_fast_malloc(), but all newly allocated space is initially cleared. Reused buffer is not cleared.

*ptr is allowed to be NULL, in which case allocation always happens if size_needed is greater than 0.

Parameters

  [in,out] | ptr | Pointer to pointer to an already allocated buffer. *ptr will be overwritten with pointer to new buffer on success or NULL on failure
  [in,out] | size | Pointer to the size of buffer *ptr. *size is updated to the new allocated size, in particular 0 in case of failure.
  [in] | min_size | Desired minimal size of buffer *ptr

See also
  av_fast_malloc()

Referenced by av_fast_mallocz().

## av_free()

void av_free | ( | void * | ptr | ) |

Free a memory block which has been allocated with a function of av_malloc() or av_realloc() family.

Parameters

  ptr | Pointer to the memory block which should be freed.

Note
  ptr = NULL is explicitly allowed.
  It is recommended that you use av_freep() instead, to prevent leaving behind dangling pointers.

See also
  av_freep()

Examples
  demux_decode.c, and transcode.c.

Referenced by av_free(), and main().

## av_freep()

void av_freep | ( | void * | ptr | ) |

Free a memory block which has been allocated with a function of av_malloc() or av_realloc() family, and set the pointer pointing to it to NULL.

uint8_t *buf = av_malloc(16);
av_free(buf);
// buf now contains a dangling pointer to freed memory, and accidental
// dereference of buf will result in a use-after-free, which may be a
// security risk.
uint8_t *buf = av_malloc(16);
av_freep(&buf);
// buf is now NULL, and accidental dereference will only result in a
// NULL-pointer dereference.
av_free
void av_free(void *ptr)
Free a memory block which has been allocated with a function of av_malloc() or av_realloc() family.
av_malloc
void * av_malloc(size_t size) av_malloc_attrib
Allocate a memory block with alignment suitable for all memory accesses (including vectors if availab...

Parameters

  ptr | Pointer to the pointer to the memory block which should be freed

Note
  *ptr = NULL is safe and leads to no action.

See also
  av_free()

Examples
  avio_read_callback.c, filter_audio.c, hw_decode.c, qsv_transcode.c, remux.c, resample_audio.c, scale_video.c, and transcode_aac.c.

Referenced by av_freep(), decode_write(), main(), main(), and read_decode_convert_and_store().

## av_strdup()

char * av_strdup | ( | const char * | s | ) |

Duplicate a string.

Parameters

  s | String to be duplicated

Returns
  Pointer to a newly-allocated string containing a copy of s or NULL if the string cannot be allocated

See also
  av_strndup()

Examples
  decode_filter_audio.c, decode_filter_video.c, transcode.c, and transcode_aac.c.

Referenced by av_strdup(), init_filter(), init_filters(), init_filters(), and open_output_file().

## av_strndup()

char * av_strndup | ( | const char * | s,
|  | size_t | len )

Duplicate a substring of a string.

Parameters

  s | String to be duplicated
  len | Maximum length of the resulting string (not counting the terminating byte)

Returns
  Pointer to a newly-allocated string containing a substring of s or NULL if the string cannot be allocated

Referenced by av_strndup().

## av_memdup()

void * av_memdup | ( | const void * | p,
|  | size_t | size )

Duplicate a buffer with av_malloc().

Parameters

  p | Buffer to be duplicated
  size | Size in bytes of the buffer copied

Returns
  Pointer to a newly allocated buffer containing a copy of p or NULL if the buffer cannot be allocated

Referenced by av_memdup().

## av_memcpy_backptr()

void av_memcpy_backptr | ( | uint8_t * | dst,
|  | int | back,
|  | int | cnt )

Overlapping memcpy() implementation.

Parameters

  dst | Destination buffer
  back | Number of bytes back to start copying (i.e. the initial size of the overlapping window); must be > 0
  cnt | Number of bytes to copy; must be >= 0

Note
  cnt > back is valid, this will copy the bytes we just copied, thus creating a repeating pattern with a period length of back.

Referenced by av_memcpy_backptr().