From 5d8d3c1ac211c3b13a2dcce5214dcf250c6c61f2 Mon Sep 17 00:00:00 2001
From: Zhao Zhili <quinkblack@foxmail.com>
Date: Sat, 2 Apr 2022 01:05:37 +0800
Subject: [PATCH] avutil/mem: fix doc for reallocs

The doc says those function are like av_free if size or nmemb is
zero. It doesn't match the code. av_realloc() realloc one byte if
size is zero, which was added by 91ff05f6ac5 ten years ago.
realloc() itself in C is implementation-dependent. Make the doc
match the longstanding behaviour.

Signed-off-by: Zhao Zhili <zhilizhao@tencent.com>
---
 libavutil/mem.h | 23 +++++++++++------------
 1 file changed, 11 insertions(+), 12 deletions(-)

diff --git a/libavutil/mem.h b/libavutil/mem.h
index b9fe80738c..d91174196c 100644
--- a/libavutil/mem.h
+++ b/libavutil/mem.h
@@ -250,8 +250,7 @@ void *av_mallocz_array(size_t nmemb, size_t size) av_malloc_attrib av_alloc_size
 /**
  * Allocate, reallocate, or free a block of memory.
  *
- * 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
+ * If `ptr` is `NULL` and `size` > 0, allocate a new block. Otherwise, expand or
  * shrink that block of memory according to `size`.
  *
  * @param ptr  Pointer to a memory block already allocated with
@@ -260,10 +259,11 @@ void *av_mallocz_array(size_t nmemb, size_t size) av_malloc_attrib av_alloc_size
  *             reallocated
  *
  * @return Pointer to a newly-reallocated block or `NULL` if the block
- *         cannot be reallocated or the function is used to free the memory block
+ *         cannot be reallocated
  *
  * @warning Unlike av_malloc(), the returned pointer is not guaranteed to be
- *          correctly aligned.
+ *          correctly aligned. The returned pointer must be freed after even
+ *          if size is zero.
  * @see av_fast_realloc()
  * @see av_reallocp()
  */
@@ -311,8 +311,7 @@ void *av_realloc_f(void *ptr, size_t nelem, size_t elsize);
 /**
  * Allocate, reallocate, or free an array.
  *
- * If `ptr` is `NULL` and `nmemb` > 0, allocate a new block. If
- * `nmemb` is zero, free the memory block pointed to by `ptr`.
+ * If `ptr` is `NULL` and `nmemb` > 0, allocate a new block.
  *
  * @param ptr   Pointer to a memory block already allocated with
  *              av_realloc() or `NULL`
@@ -320,19 +319,19 @@ void *av_realloc_f(void *ptr, size_t nelem, size_t elsize);
  * @param size  Size of the single element of the array
  *
  * @return Pointer to a newly-reallocated block or NULL if the block
- *         cannot be reallocated or the function is used to free the memory block
+ *         cannot be reallocated
  *
  * @warning Unlike av_malloc(), the allocated memory is not guaranteed to be
- *          correctly aligned.
+ *          correctly aligned. The returned pointer must be freed after even if
+ *          nmemb is zero.
  * @see av_reallocp_array()
  */
 av_alloc_size(2, 3) void *av_realloc_array(void *ptr, size_t nmemb, size_t size);
 
 /**
- * Allocate, reallocate, or free an array through a pointer to a pointer.
+ * Allocate, reallocate an array through a pointer to a pointer.
  *
- * If `*ptr` is `NULL` and `nmemb` > 0, allocate a new block. If `nmemb` is
- * zero, free the memory block pointed to by `*ptr`.
+ * If `*ptr` is `NULL` and `nmemb` > 0, allocate a new block.
  *
  * @param[in,out] ptr   Pointer to a pointer to a memory block already
  *                      allocated with av_realloc(), or a pointer to `NULL`.
@@ -343,7 +342,7 @@ av_alloc_size(2, 3) void *av_realloc_array(void *ptr, size_t nmemb, size_t size)
  * @return Zero on success, an AVERROR error code on failure
  *
  * @warning Unlike av_malloc(), the allocated memory is not guaranteed to be
- *          correctly aligned.
+ *          correctly aligned. *ptr must be freed after even if nmemb is zero.
  */
 int av_reallocp_array(void *ptr, size_t nmemb, size_t size);