[FFmpeg-devel] [PATCH] avutil/mem: fix doc for reallocs

["zhilizhao(赵志立)"]

Ping.

> On Apr 2, 2022, at 1:05 AM, Zhao Zhili <quinkblack at foxmail.com> wrote:
> 
> 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.
> ---
> 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);
> 
> -- 
> 2.31.1
>