From a1aa8f04e8856e755dcb70ea7f4147d3e7da72e3 Mon Sep 17 00:00:00 2001 From: Mattias Andrée Date: Wed, 31 Oct 2018 21:58:09 +0100 Subject: More header file documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Mattias Andrée --- libsimple/aligned_alloc.h | 5 ++ libsimple/aligned_allocz.h | 5 ++ libsimple/aligned_memdup.h | 4 +- libsimple/calloc.h | 52 +++++------ libsimple/malloc.h | 48 +++++----- libsimple/mallocz.h | 168 ++++++++++++++++++++++++++++++++++ libsimple/memalign.h | 4 + libsimple/memalignz.h | 4 + libsimple/memdup.h | 4 +- libsimple/posix_memalign.h | 4 + libsimple/posix_memalignz.h | 4 + libsimple/pvalloc.h | 5 ++ libsimple/pvallocz.h | 5 ++ libsimple/realloc.h | 213 ++++++++++++++++++++++++++++++++++++++++++++ libsimple/strdup.h | 4 +- libsimple/strndup.h | 4 +- libsimple/valloc.h | 4 + libsimple/vallocz.h | 4 + 18 files changed, 475 insertions(+), 66 deletions(-) diff --git a/libsimple/aligned_alloc.h b/libsimple/aligned_alloc.h index 8e7d66f..6155c7d 100644 --- a/libsimple/aligned_alloc.h +++ b/libsimple/aligned_alloc.h @@ -1,5 +1,10 @@ /* See LICENSE file for copyright and license details. */ +/* + * Alignment must be a power of 2. + * Allocation size must be a mutiple of the alignment. + */ + _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __alloc_align__(1), __warn_unused_result__))) static inline void *libsimple_valigned_allocn(size_t __alignment, size_t __n, va_list __ap) { return libsimple_valigned_alloczn(0, __alignment, __n, __ap); } diff --git a/libsimple/aligned_allocz.h b/libsimple/aligned_allocz.h index f34a015..1c81697 100644 --- a/libsimple/aligned_allocz.h +++ b/libsimple/aligned_allocz.h @@ -1,5 +1,10 @@ /* See LICENSE file for copyright and license details. */ +/* + * Alignment must be a power of 2. + * Allocation size must be a mutiple of the alignment. + */ + _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __alloc_align__(2), __warn_unused_result__))) void *libsimple_valigned_alloczn(int, size_t, size_t, va_list); #ifndef valigned_alloczn diff --git a/libsimple/aligned_memdup.h b/libsimple/aligned_memdup.h index 6555280..d2fa91f 100644 --- a/libsimple/aligned_memdup.h +++ b/libsimple/aligned_memdup.h @@ -46,7 +46,7 @@ void *libsimple_aligned_memdup(const void *, size_t, size_t); /** - * Version of `libsimple_aligned_memdup` that calles `libsimple_enprintf` on error + * Version of `libsimple_aligned_memdup` that calls `libsimple_enprintf` on error * * @param status Exit value in case of failure * @param s The bytes to copy @@ -62,7 +62,7 @@ void *libsimple_enaligned_memdup(int, const void *, size_t, size_t); /** - * Version of `libsimple_aligned_memdup` that calles `libsimple_eprintf` on error + * Version of `libsimple_aligned_memdup` that calls `libsimple_eprintf` on error * * @param s The bytes to copy * @param alignment The alignment of the returned pointer diff --git a/libsimple/calloc.h b/libsimple/calloc.h index 2820d02..7b373e9 100644 --- a/libsimple/calloc.h +++ b/libsimple/calloc.h @@ -71,8 +71,7 @@ libsimple_callocn(size_t __n, ... /*, (size_t)0 */) * @param m The size of each element, the behaviour of * this function is unspecified for the value 0 * @return A unique pointer with at least the size `n * m` - * and with the alignment `alignof(max_align_t)`; - * `NULL` on failure + * and with the alignment `alignof(max_align_t)` */ _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __alloc_size__(2, 3), __warn_unused_result__, __returns_nonnull__))) void *libsimple_encalloc(int, size_t, size_t); @@ -85,8 +84,8 @@ void *libsimple_encalloc(int, size_t, size_t); * Dynamically allocates heap allocated, initialised, * memory with default alignment (`alignof(max_align_t)`) * - * The product of all arguments, up to the first 0, - * will be used as the number of bytes to allocated + * The product of all arguments except `status`, up to the + * first 0, will be used as the number of bytes to allocated * * On failure, the `libsimple_enprintf` function is called, * cause the program to print an error message and exit, @@ -98,12 +97,11 @@ void *libsimple_encalloc(int, size_t, size_t); * all arguments should have the type `size_t`, and * list must end with 0 (which is not factor) * @return A unique pointer with at least the specified size - * and with the alignment `alignof(max_align_t)`; - * `NULL` on failure + * and with the alignment `alignof(max_align_t)` */ _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __warn_unused_result__, __returns_nonnull__))) -static inline void *libsimple_envcallocn(int __st, size_t __n, va_list __ap) -{ return libsimple_envmalloczn(__st, 1, __n, __ap); } +static inline void *libsimple_envcallocn(int __status, size_t __n, va_list __ap) +{ return libsimple_envmalloczn(__status, 1, __n, __ap); } #ifndef envcallocn # define envcallocn libsimple_envcallocn #endif @@ -113,8 +111,8 @@ static inline void *libsimple_envcallocn(int __st, size_t __n, va_list __ap) * Dynamically allocates heap allocated, initialised, * memory with default alignment (`alignof(max_align_t)`) * - * The product of all arguments, up to the first 0, - * will be used as the number of bytes to allocated + * The product of all arguments except `status`, up to the + * first 0, will be used as the number of bytes to allocated * * On failure, the `libsimple_enprintf` function is called, * cause the program to print an error message and exit, @@ -126,8 +124,7 @@ static inline void *libsimple_envcallocn(int __st, size_t __n, va_list __ap) * all arguments should have the type `size_t`, and * list must end with 0 (which is not factor) * @return A unique pointer with at least the specified size - * and with the alignment `alignof(max_align_t)`; - * `NULL` on failure + * and with the alignment `alignof(max_align_t)` */ _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __warn_unused_result__, __returns_nonnull__))) static inline void * @@ -156,8 +153,7 @@ libsimple_encallocn(int __status, size_t __n, ... /*, (size_t)0 */) * @param m The size of each element, the behaviour of * this function is unspecified for the value 0 * @return A unique pointer with at least the size `n * m` - * and with the alignment `alignof(max_align_t)`; - * `NULL` on failure + * and with the alignment `alignof(max_align_t)` */ _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __alloc_size__(1, 2), __warn_unused_result__, __returns_nonnull__))) static inline void *libsimple_ecalloc(size_t __n, size_t __m) @@ -178,14 +174,12 @@ static inline void *libsimple_ecalloc(size_t __n, size_t __m) * cause the program to print an error message and exit, * see `libsimple_eprintf` for more information * - * @param status The exit value for the process in case of failure - * @param n First factor for the allocation size, must not be 0 - * @param ap The rest of the factors for the allocation size, - * all arguments should have the type `size_t`, and - * list must end with 0 (which is not factor) - * @return A unique pointer with at least the specified size - * and with the alignment `alignof(max_align_t)`; - * `NULL` on failure + * @param n First factor for the allocation size, must not be 0 + * @param ap The rest of the factors for the allocation size, + * all arguments should have the type `size_t`, and + * list must end with 0 (which is not factor) + * @return A unique pointer with at least the specified size + * and with the alignment `alignof(max_align_t)` */ _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __warn_unused_result__, __returns_nonnull__))) static inline void *libsimple_evcallocn(size_t __n, va_list __ap) @@ -206,14 +200,12 @@ static inline void *libsimple_evcallocn(size_t __n, va_list __ap) * cause the program to print an error message and exit, * see `libsimple_eprintf` for more information * - * @param status The exit value for the process in case of failure - * @param n First factor for the allocation size, must not be 0 - * @param ... The rest of the factors for the allocation size, - * all arguments should have the type `size_t`, and - * list must end with 0 (which is not factor) - * @return A unique pointer with at least the specified size - * and with the alignment `alignof(max_align_t)`; - * `NULL` on failure + * @param n First factor for the allocation size, must not be 0 + * @param ... The rest of the factors for the allocation size, + * all arguments should have the type `size_t`, and + * list must end with 0 (which is not factor) + * @return A unique pointer with at least the specified size + * and with the alignment `alignof(max_align_t)` */ _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __warn_unused_result__, __returns_nonnull__))) static inline void * diff --git a/libsimple/malloc.h b/libsimple/malloc.h index 883a216..b57f81f 100644 --- a/libsimple/malloc.h +++ b/libsimple/malloc.h @@ -69,8 +69,7 @@ libsimple_mallocn(size_t __n, ... /*, (size_t)0 */) * @param n The number of bytes to allocate, the behaviour of * this function is unspecified for the value 0 * @return A unique pointer with at least the specified size - * and with the alignment `alignof(max_align_t)`; - * `NULL` on failure + * and with the alignment `alignof(max_align_t)` */ _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __alloc_size__(2), __warn_unused_result__, __returns_nonnull__))) void *libsimple_enmalloc(int, size_t); @@ -83,8 +82,8 @@ void *libsimple_enmalloc(int, size_t); * Dynamically allocates heap allocated, uninitialised, * memory with default alignment (`alignof(max_align_t)`) * - * The product of all arguments, up to the first 0, - * will be used as the number of bytes to allocated + * The product of all arguments except `status`, up to the + * first 0, will be used as the number of bytes to allocated * * On failure, the `libsimple_enprintf` function is called, * cause the program to print an error message and exit, @@ -96,8 +95,7 @@ void *libsimple_enmalloc(int, size_t); * all arguments should have the type `size_t`, and * list must end with 0 (which is not factor) * @return A unique pointer with at least the specified size - * and with the alignment `alignof(max_align_t)`; - * `NULL` on failure + * and with the alignment `alignof(max_align_t)` */ _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __warn_unused_result__, __returns_nonnull__))) static inline void *libsimple_envmallocn(int __status, size_t __n, va_list __ap) @@ -111,8 +109,8 @@ static inline void *libsimple_envmallocn(int __status, size_t __n, va_list __ap) * Dynamically allocates heap allocated, uninitialised, * memory with default alignment (`alignof(max_align_t)`) * - * The product of all arguments, up to the first 0, - * will be used as the number of bytes to allocated + * The product of all arguments except `status`, up to the + * first 0, will be used as the number of bytes to allocated * * On failure, the `libsimple_enprintf` function is called, * cause the program to print an error message and exit, @@ -124,8 +122,7 @@ static inline void *libsimple_envmallocn(int __status, size_t __n, va_list __ap) * all arguments should have the type `size_t`, and * list must end with 0 (which is not factor) * @return A unique pointer with at least the specified size - * and with the alignment `alignof(max_align_t)`; - * `NULL` on failure + * and with the alignment `alignof(max_align_t)` */ _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __warn_unused_result__, __returns_nonnull__))) static inline void * @@ -152,8 +149,7 @@ libsimple_enmallocn(int __status, size_t __n, ... /*, (size_t)0 */) * @param n The number of bytes to allocate, the behaviour of * this function is unspecified for the value 0 * @return A unique pointer with at least the specified size - * and with the alignment `alignof(max_align_t)`; - * `NULL` on failure + * and with the alignment `alignof(max_align_t)` */ _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __alloc_size__(1), __warn_unused_result__, __returns_nonnull__))) static inline void *libsimple_emalloc(size_t __n) @@ -174,14 +170,12 @@ static inline void *libsimple_emalloc(size_t __n) * cause the program to print an error message and exit, * see `libsimple_eprintf` for more information * - * @param status The exit value for the process in case of failure - * @param n First factor for the allocation size, must not be 0 - * @param ap The rest of the factors for the allocation size, - * all arguments should have the type `size_t`, and - * list must end with 0 (which is not factor) - * @return A unique pointer with at least the specified size - * and with the alignment `alignof(max_align_t)`; - * `NULL` on failure + * @param n First factor for the allocation size, must not be 0 + * @param ap The rest of the factors for the allocation size, + * all arguments should have the type `size_t`, and + * list must end with 0 (which is not factor) + * @return A unique pointer with at least the specified size + * and with the alignment `alignof(max_align_t)` */ _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __warn_unused_result__, __returns_nonnull__))) static inline void *libsimple_evmallocn(size_t __n, va_list __ap) @@ -202,14 +196,12 @@ static inline void *libsimple_evmallocn(size_t __n, va_list __ap) * cause the program to print an error message and exit, * see `libsimple_eprintf` for more information * - * @param status The exit value for the process in case of failure - * @param n First factor for the allocation size, must not be 0 - * @param ... The rest of the factors for the allocation size, - * all arguments should have the type `size_t`, and - * list must end with 0 (which is not factor) - * @return A unique pointer with at least the specified size - * and with the alignment `alignof(max_align_t)`; - * `NULL` on failure + * @param n First factor for the allocation size, must not be 0 + * @param ... The rest of the factors for the allocation size, + * all arguments should have the type `size_t`, and + * list must end with 0 (which is not factor) + * @return A unique pointer with at least the specified size + * and with the alignment `alignof(max_align_t)` */ _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __warn_unused_result__, __returns_nonnull__))) static inline void * diff --git a/libsimple/mallocz.h b/libsimple/mallocz.h index 80b2ef1..2bbd607 100644 --- a/libsimple/mallocz.h +++ b/libsimple/mallocz.h @@ -1,18 +1,54 @@ /* See LICENSE file for copyright and license details. */ + +/* Properly declared elsewhere { */ + _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __alloc_size__(2, 3), __warn_unused_result__, __returns_nonnull__))) void *libsimple_encalloc(int, size_t, size_t); _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __alloc_size__(2), __warn_unused_result__, __returns_nonnull__))) void *libsimple_enmalloc(int, size_t); +/* } */ + +/** + * Dynamically allocates heap allocated, optinally initialised, + * memory with default alignment (`alignof(max_align_t)`) + * + * The product of all arguments except `clear`, up to the + * first 0, will be used as the number of bytes to allocated + * + * @param clear Non-zero if the memory should be initialised + * @param n First factor for the allocation size, must not be 0 + * @param ap The rest of the factors for the allocation size, + * all arguments should have the type `size_t`, and + * list must end with 0 (which is not factor) + * @return A unique pointer with at least the specified size + * and with the alignment `alignof(max_align_t)`; + * `NULL` on failure + * @throws EINVAL `n` is 0 + * @throws ENOMEM Could not allocated enough memory + */ _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __warn_unused_result__))) void *libsimple_vmalloczn(int, size_t, va_list); #ifndef vmalloczn # define vmalloczn libsimple_vmalloczn #endif + +/** + * Dynamically allocates heap allocated, optinally initialised, + * memory with default alignment (`alignof(max_align_t)`) + * + * @param clear Non-zero if the memory should be initialised + * @param n Th number of bytes to allocate + * @return A unique pointer with at least the specified size + * and with the alignment `alignof(max_align_t)`; + * `NULL` on failure + * @throws EINVAL `n` is 0 + * @throws ENOMEM Could not allocated enough memory + */ _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __alloc_size__(2), __warn_unused_result__))) static inline void *libsimple_mallocz(int __clear, size_t __n) { return __clear ? calloc(1, __n) : malloc(__n); } @@ -20,6 +56,25 @@ static inline void *libsimple_mallocz(int __clear, size_t __n) # define mallocz libsimple_mallocz #endif + +/** + * Dynamically allocates heap allocated, optinally initialised, + * memory with default alignment (`alignof(max_align_t)`) + * + * The product of all arguments except `clear`, up to the + * first 0, will be used as the number of bytes to allocated + * + * @param clear Non-zero if the memory should be initialised + * @param n First factor for the allocation size, must not be 0 + * @param ... The rest of the factors for the allocation size, + * all arguments should have the type `size_t`, and + * list must end with 0 (which is not factor) + * @return A unique pointer with at least the specified size + * and with the alignment `alignof(max_align_t)`; + * `NULL` on failure + * @throws EINVAL `n` is 0 + * @throws ENOMEM Could not allocated enough memory + */ _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __warn_unused_result__))) static inline void * libsimple_malloczn(int __clear, size_t __n, ... /*, (size_t)0 */) @@ -33,6 +88,21 @@ libsimple_malloczn(int __clear, size_t __n, ... /*, (size_t)0 */) # define malloczn libsimple_malloczn #endif + +/** + * Dynamically allocates heap allocated, optinally initialised, + * memory with default alignment (`alignof(max_align_t)`) + * + * On failure, the `libsimple_enprintf` function is called, + * cause the program to print an error message and exit, + * see `libsimple_enprintf` for more information + * + * @param status The exit value for the process in case of failure + * @param clear Non-zero if the memory should be initialised + * @param n Th number of bytes to allocate + * @return A unique pointer with at least the specified size + * and with the alignment `alignof(max_align_t)` + */ _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __alloc_size__(3), __warn_unused_result__, __returns_nonnull__))) static inline void *libsimple_enmallocz(int __status, int __clear, size_t __n) { return __clear ? libsimple_encalloc(__status, 1, __n) : libsimple_enmalloc(__status, __n); } @@ -40,12 +110,56 @@ static inline void *libsimple_enmallocz(int __status, int __clear, size_t __n) # define enmallocz libsimple_enmallocz #endif + +/** + * Dynamically allocates heap allocated, optinally initialised, + * memory with default alignment (`alignof(max_align_t)`) + * + * The product of all arguments except `clear` and `status`, + * up to the first 0, will be used as the number of bytes to + * allocated + * + * On failure, the `libsimple_enprintf` function is called, + * cause the program to print an error message and exit, + * see `libsimple_enprintf` for more information + * + * @param status The exit value for the process in case of failure + * @param clear Non-zero if the memory should be initialised + * @param n First factor for the allocation size, must not be 0 + * @param ap The rest of the factors for the allocation size, + * all arguments should have the type `size_t`, and + * list must end with 0 (which is not factor) + * @return A unique pointer with at least the specified size + * and with the alignment `alignof(max_align_t)` + */ _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __warn_unused_result__, __returns_nonnull__))) void *libsimple_envmalloczn(int, int, size_t, va_list); #ifndef envmalloczn # define envmalloczn libsimple_envmalloczn #endif + +/** + * Dynamically allocates heap allocated, optinally initialised, + * memory with default alignment (`alignof(max_align_t)`) + * + * The product of all arguments except `clear` and `status`, + * up to the first 0, will be used as the number of bytes to + * allocated + * + * On failure, the `libsimple_enprintf` function is called, + * cause the program to print an error message and exit, + * see `libsimple_enprintf` for more information + * + * @param status The exit value for the process in case of failure + * @param clear Non-zero if the memory should be initialised + * @param n First factor for the allocation size, must not be 0 + * @param ... The rest of the factors for the allocation size, + * all arguments should have the type `size_t`, and + * list must end with 0 (which is not factor) + * @return A unique pointer with at least the specified size + * and with the alignment `alignof(max_align_t)` + */ _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __warn_unused_result__, __returns_nonnull__))) static inline void * libsimple_enmalloczn(int __status, int __clear, size_t __n, ... /*, (size_t)0 */) @@ -59,6 +173,20 @@ libsimple_enmalloczn(int __status, int __clear, size_t __n, ... /*, (size_t)0 */ # define enmalloczn libsimple_enmalloczn #endif + +/** + * Dynamically allocates heap allocated, optinally initialised, + * memory with default alignment (`alignof(max_align_t)`) + * + * On failure, the `libsimple_eprintf` function is called, + * cause the program to print an error message and exit, + * see `libsimple_eprintf` for more information + * + * @param clear Non-zero if the memory should be initialised + * @param n Th number of bytes to allocate + * @return A unique pointer with at least the specified size + * and with the alignment `alignof(max_align_t)` + */ _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __alloc_size__(2), __warn_unused_result__, __returns_nonnull__))) static inline void *libsimple_emallocz(int __clear, size_t __n) { return libsimple_enmallocz(libsimple_default_failure_exit, __clear, __n); } @@ -66,6 +194,26 @@ static inline void *libsimple_emallocz(int __clear, size_t __n) # define emallocz libsimple_emallocz #endif + +/** + * Dynamically allocates heap allocated, optinally initialised, + * memory with default alignment (`alignof(max_align_t)`) + * + * The product of all arguments except `clear`, up to the + * first 0 will be used as the number of bytes to allocated + * + * On failure, the `libsimple_eprintf` function is called, + * cause the program to print an error message and exit, + * see `libsimple_eprintf` for more information + * + * @param clear Non-zero if the memory should be initialised + * @param n First factor for the allocation size, must not be 0 + * @param ap The rest of the factors for the allocation size, + * all arguments should have the type `size_t`, and + * list must end with 0 (which is not factor) + * @return A unique pointer with at least the specified size + * and with the alignment `alignof(max_align_t)` + */ _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __warn_unused_result__, __returns_nonnull__))) static inline void *libsimple_evmalloczn(int __clear, size_t __n, va_list __ap) { return libsimple_envmalloczn(libsimple_default_failure_exit, __clear, __n, __ap); } @@ -73,6 +221,26 @@ static inline void *libsimple_evmalloczn(int __clear, size_t __n, va_list __ap) # define evmalloczn libsimple_evmalloczn #endif + +/** + * Dynamically allocates heap allocated, optinally initialised, + * memory with default alignment (`alignof(max_align_t)`) + * + * The product of all arguments except `clear` up to the + * first 0, will be used as the number of bytes to allocated + * + * On failure, the `libsimple_eprintf` function is called, + * cause the program to print an error message and exit, + * see `libsimple_eprintf` for more information + * + * @param clear Non-zero if the memory should be initialised + * @param n First factor for the allocation size, must not be 0 + * @param ... The rest of the factors for the allocation size, + * all arguments should have the type `size_t`, and + * list must end with 0 (which is not factor) + * @return A unique pointer with at least the specified size + * and with the alignment `alignof(max_align_t)` + */ _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __warn_unused_result__, __returns_nonnull__))) static inline void * libsimple_emalloczn(int __clear, size_t __n, ... /*, (size_t)0 */) diff --git a/libsimple/memalign.h b/libsimple/memalign.h index 046edd4..466de3e 100644 --- a/libsimple/memalign.h +++ b/libsimple/memalign.h @@ -1,5 +1,9 @@ /* See LICENSE file for copyright and license details. */ +/* + * Alignment must be a power of 2. + */ + _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __alloc_align__(1), __warn_unused_result__))) static inline void *libsimple_vmemalignn(size_t __alignment, size_t __n, va_list __ap) { return libsimple_vmemalignzn(0, __alignment, __n, __ap); } diff --git a/libsimple/memalignz.h b/libsimple/memalignz.h index 8a20295..4b47d0e 100644 --- a/libsimple/memalignz.h +++ b/libsimple/memalignz.h @@ -1,5 +1,9 @@ /* See LICENSE file for copyright and license details. */ +/* + * Alignment must be a power of 2. + */ + _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __alloc_align__(2), __warn_unused_result__))) static inline void * libsimple_vmemalignzn(int __clear, size_t __alignment, size_t __n, va_list __ap) /* TODO test ([v]memalign[z]n) */ diff --git a/libsimple/memdup.h b/libsimple/memdup.h index b7f2d6b..ce84f6b 100644 --- a/libsimple/memdup.h +++ b/libsimple/memdup.h @@ -37,7 +37,7 @@ void *libsimple_memdup(const void *, size_t); /** - * Version of `libsimple_memdup` that calles `libsimple_enprintf` on error + * Version of `libsimple_memdup` that calls `libsimple_enprintf` on error * * @param status Exit value in case of failure * @param s The bytes to copy @@ -52,7 +52,7 @@ void *libsimple_enmemdup(int, const void *, size_t); /** - * Version of `libsimple_memdup` that calles `libsimple_eprintf` on error + * Version of `libsimple_memdup` that calls `libsimple_eprintf` on error * * @param s The bytes to copy * @param n The number of bytes to copy diff --git a/libsimple/posix_memalign.h b/libsimple/posix_memalign.h index dfe7a53..5443418 100644 --- a/libsimple/posix_memalign.h +++ b/libsimple/posix_memalign.h @@ -1,5 +1,9 @@ /* See LICENSE file for copyright and license details. */ +/* + * Alignment must be a power of 2 and a multiple of `sizeof(void *)`. + */ + _LIBSIMPLE_GCC_ONLY(__attribute__((__nonnull__(1)))) static inline int libsimple_vposix_memalignn(void **__memptr, size_t __alignment, size_t __n, va_list __ap) { return libsimple_vposix_memalignzn(__memptr, 0, __alignment, __n, __ap); } diff --git a/libsimple/posix_memalignz.h b/libsimple/posix_memalignz.h index 94fc82c..2bbd310 100644 --- a/libsimple/posix_memalignz.h +++ b/libsimple/posix_memalignz.h @@ -1,5 +1,9 @@ /* See LICENSE file for copyright and license details. */ +/* + * Alignment must be a power of 2 and a multiple of `sizeof(void *)`. + */ + _LIBSIMPLE_GCC_ONLY(__attribute__((__nonnull__(1)))) int libsimple_vposix_memalignzn(void **, int, size_t, size_t, va_list); #ifndef vposix_memalignzn diff --git a/libsimple/pvalloc.h b/libsimple/pvalloc.h index 876366b..dfd7b31 100644 --- a/libsimple/pvalloc.h +++ b/libsimple/pvalloc.h @@ -1,5 +1,10 @@ /* See LICENSE file for copyright and license details. */ +/* + * The alignment will be the page size. + * The allocation size is rounded up to the next multiple of the alignment. + */ + _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __warn_unused_result__))) static inline void *libsimple_vpvallocn(size_t __n, va_list __ap) { return libsimple_vpvalloczn(0, __n, __ap); } diff --git a/libsimple/pvallocz.h b/libsimple/pvallocz.h index f1e58ed..2fc628d 100644 --- a/libsimple/pvallocz.h +++ b/libsimple/pvallocz.h @@ -1,5 +1,10 @@ /* See LICENSE file for copyright and license details. */ +/* + * The alignment will be the page size. + * The allocation size is rounded up to the next multiple of the alignment. + */ + _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __warn_unused_result__))) static inline void * libsimple_vpvalloczn(int __clear, size_t __n, va_list __ap) /* TODO test ([v]pvalloc[z]n) */ diff --git a/libsimple/realloc.h b/libsimple/realloc.h index 3e2fece..8ece86d 100644 --- a/libsimple/realloc.h +++ b/libsimple/realloc.h @@ -1,11 +1,63 @@ /* See LICENSE file for copyright and license details. */ + +/** + * Dynamically reallocates heap allocated, uninitialised, + * memory with default alignment (`alignof(max_align_t)`) + * as the new alignment + * + * The product of all arguments, up to the first 0, + * will be used as the number of bytes to allocated + * + * On success, either `ptr` is returned, or a new non-null + * pointer is returned with the same content (truncated to + * `n` bytes if size shrunk), in which case `ptr` is + * deallocated. On failure `ptr` is still valid. If `ptr` + * is `NULL` a new allocation is made. + * + * @param ptr Pointer to reallocated, `NULL` for a new allocation + * @param n First factor for the allocation size, must not be 0 + * @param ap The rest of the factors for the allocation size, + * all arguments should have the type `size_t`, and + * list must end with 0 (which is not factor) + * @return Either `ptr` or a unique pointer with at least + * the specified size and with the alignment + * `alignof(max_align_t)`; `NULL` on failure + * @throws EINVAL `n` is 0 + * @throws ENOMEM Could not allocated enough memory + */ _LIBSIMPLE_GCC_ONLY(__attribute__((__warn_unused_result__))) void *libsimple_vreallocn(void *, size_t, va_list); #ifndef vreallocn # define vreallocn libsimple_vreallocn #endif + +/** + * Dynamically reallocates heap allocated, uninitialised, + * memory with default alignment (`alignof(max_align_t)`) + * as the new alignment + * + * The product of all arguments, up to the first 0, + * will be used as the number of bytes to allocated + * + * On success, either `ptr` is returned, or a new non-null + * pointer is returned with the same content (truncated to + * `n` bytes if size shrunk), in which case `ptr` is + * deallocated. On failure `ptr` is still valid. If `ptr` + * is `NULL` a new allocation is made. + * + * @param ptr Pointer to reallocated, `NULL` for a new allocation + * @param n First factor for the allocation size, must not be 0 + * @param ... The rest of the factors for the allocation size, + * all arguments should have the type `size_t`, and + * list must end with 0 (which is not factor) + * @return Either `ptr` or a unique pointer with at least + * the specified size and with the alignment + * `alignof(max_align_t)`; `NULL` on failure + * @throws EINVAL `n` is 0 + * @throws ENOMEM Could not allocated enough memory + */ _LIBSIMPLE_GCC_ONLY(__attribute__((__warn_unused_result__))) static inline void * libsimple_reallocn(void *__ptr, size_t __n, ... /*, (size_t)0 */) @@ -19,18 +71,100 @@ libsimple_reallocn(void *__ptr, size_t __n, ... /*, (size_t)0 */) # define reallocn libsimple_reallocn #endif + +/** + * Dynamically reallocates heap allocated, uninitialised, + * memory with default alignment (`alignof(max_align_t)`) + * as the new alignment + * + * On success, either `ptr` is returned, or a new non-null + * pointer is returned with the same content (truncated to + * `n` bytes if size shrunk), in which case `ptr` is + * deallocated. On failure `ptr` is still valid. If `ptr` + * is `NULL` a new allocation is made. + * + * On failure, the `libsimple_enprintf` function is called, + * cause the program to print an error message and exit, + * see `libsimple_enprintf` for more information + * + * @param status The exit value for the process in case of failure + * @param ptr Pointer to reallocated, `NULL` for a new allocation + * @param n The number of bytes to allocate, the behaviour of + * this function is unspecified for the value 0 + * @return Either `ptr` or a unique pointer with at least + * the specified size and with the alignment + * `alignof(max_align_t)` + */ _LIBSIMPLE_GCC_ONLY(__attribute__((__alloc_size__(3), __warn_unused_result__, __returns_nonnull__))) void *libsimple_enrealloc(int, void *, size_t); #ifndef enrealloc # define enrealloc libsimple_enrealloc #endif + +/** + * Dynamically reallocates heap allocated, uninitialised, + * memory with default alignment (`alignof(max_align_t)`) + * as the new alignment + * + * The product of all arguments except `status`, up to the + * first 0, will be used as the number of bytes to allocated + * + * On success, either `ptr` is returned, or a new non-null + * pointer is returned with the same content (truncated to + * `n` bytes if size shrunk), in which case `ptr` is + * deallocated. On failure `ptr` is still valid. If `ptr` + * is `NULL` a new allocation is made. + * + * On failure, the `libsimple_enprintf` function is called, + * cause the program to print an error message and exit, + * see `libsimple_enprintf` for more information + * + * @param status The exit value for the process in case of failure + * @param ptr Pointer to reallocated, `NULL` for a new allocation + * @param n First factor for the allocation size, must not be 0 + * @param ap The rest of the factors for the allocation size, + * all arguments should have the type `size_t`, and + * list must end with 0 (which is not factor) + * @return Either `ptr` or a unique pointer with at least + * the specified size and with the alignment + * `alignof(max_align_t)` + */ _LIBSIMPLE_GCC_ONLY(__attribute__((__warn_unused_result__, __returns_nonnull__))) void *libsimple_envreallocn(int, void *, size_t, va_list); #ifndef envreallocn # define envreallocn libsimple_envreallocn #endif + +/** + * Dynamically reallocates heap allocated, uninitialised, + * memory with default alignment (`alignof(max_align_t)`) + * as the new alignment + * + * The product of all arguments except `status`, up to the + * first 0, will be used as the number of bytes to allocated + * + * On success, either `ptr` is returned, or a new non-null + * pointer is returned with the same content (truncated to + * `n` bytes if size shrunk), in which case `ptr` is + * deallocated. On failure `ptr` is still valid. If `ptr` + * is `NULL` a new allocation is made. + * + * On failure, the `libsimple_enprintf` function is called, + * cause the program to print an error message and exit, + * see `libsimple_enprintf` for more information + * + * @param status The exit value for the process in case of failure + * @param ptr Pointer to reallocated, `NULL` for a new allocation + * @param n First factor for the allocation size, must not be 0 + * @param ... The rest of the factors for the allocation size, + * all arguments should have the type `size_t`, and + * list must end with 0 (which is not factor) + * @return Either `ptr` or a unique pointer with at least + * the specified size and with the alignment + * `alignof(max_align_t)` + */ _LIBSIMPLE_GCC_ONLY(__attribute__((__warn_unused_result__, __returns_nonnull__))) static inline void * libsimple_enreallocn(int __status, void *__ptr, size_t __n, ... /*, (size_t)0 */) @@ -44,6 +178,29 @@ libsimple_enreallocn(int __status, void *__ptr, size_t __n, ... /*, (size_t)0 */ # define enreallocn libsimple_enreallocn #endif + +/** + * Dynamically reallocates heap allocated, uninitialised, + * memory with default alignment (`alignof(max_align_t)`) + * as the new alignment + * + * On success, either `ptr` is returned, or a new non-null + * pointer is returned with the same content (truncated to + * `n` bytes if size shrunk), in which case `ptr` is + * deallocated. On failure `ptr` is still valid. If `ptr` + * is `NULL` a new allocation is made. + * + * On failure, the `libsimple_eprintf` function is called, + * cause the program to print an error message and exit, + * see `libsimple_eprintf` for more information + * + * @param ptr Pointer to reallocated, `NULL` for a new allocation + * @param n The number of bytes to allocate, the behaviour of + * this function is unspecified for the value 0 + * @return Either `ptr` or a unique pointer with at least + * the specified size and with the alignment + * `alignof(max_align_t)` + */ _LIBSIMPLE_GCC_ONLY(__attribute__((__alloc_size__(2), __warn_unused_result__, __returns_nonnull__))) static inline void *libsimple_erealloc(void *__ptr, size_t __n) { return enrealloc(libsimple_default_failure_exit, __ptr, __n); } @@ -51,6 +208,34 @@ static inline void *libsimple_erealloc(void *__ptr, size_t __n) # define erealloc libsimple_erealloc #endif + +/** + * Dynamically reallocates heap allocated, uninitialised, + * memory with default alignment (`alignof(max_align_t)`) + * as the new alignment + * + * The product of all arguments, up to the first 0, + * will be used as the number of bytes to allocated + * + * On success, either `ptr` is returned, or a new non-null + * pointer is returned with the same content (truncated to + * `n` bytes if size shrunk), in which case `ptr` is + * deallocated. On failure `ptr` is still valid. If `ptr` + * is `NULL` a new allocation is made. + * + * On failure, the `libsimple_eprintf` function is called, + * cause the program to print an error message and exit, + * see `libsimple_eprintf` for more information + * + * @param ptr Pointer to reallocated, `NULL` for a new allocation + * @param n First factor for the allocation size, must not be 0 + * @param ap The rest of the factors for the allocation size, + * all arguments should have the type `size_t`, and + * list must end with 0 (which is not factor) + * @return Either `ptr` or a unique pointer with at least + * the specified size and with the alignment + * `alignof(max_align_t)` + */ _LIBSIMPLE_GCC_ONLY(__attribute__((__warn_unused_result__, __returns_nonnull__))) static inline void *libsimple_evreallocn(void *__ptr, size_t __n, va_list __ap) { return libsimple_envreallocn(libsimple_default_failure_exit, __ptr, __n, __ap); } @@ -58,6 +243,34 @@ static inline void *libsimple_evreallocn(void *__ptr, size_t __n, va_list __ap) # define evreallocn libsimple_evreallocn #endif + +/** + * Dynamically reallocates heap allocated, uninitialised, + * memory with default alignment (`alignof(max_align_t)`) + * as the new alignment + * + * The product of all arguments, up to the first 0, + * will be used as the number of bytes to allocated + * + * On success, either `ptr` is returned, or a new non-null + * pointer is returned with the same content (truncated to + * `n` bytes if size shrunk), in which case `ptr` is + * deallocated. On failure `ptr` is still valid. If `ptr` + * is `NULL` a new allocation is made. + * + * On failure, the `libsimple_eprintf` function is called, + * cause the program to print an error message and exit, + * see `libsimple_eprintf` for more information + * + * @param ptr Pointer to reallocated, `NULL` for a new allocation + * @param n First factor for the allocation size, must not be 0 + * @param ... The rest of the factors for the allocation size, + * all arguments should have the type `size_t`, and + * list must end with 0 (which is not factor) + * @return Either `ptr` or a unique pointer with at least + * the specified size and with the alignment + * `alignof(max_align_t)` + */ _LIBSIMPLE_GCC_ONLY(__attribute__((__warn_unused_result__, __returns_nonnull__))) static inline void * libsimple_ereallocn(void *__ptr, size_t __n, ... /*, (size_t)0 */) diff --git a/libsimple/strdup.h b/libsimple/strdup.h index 9f069f4..33994e3 100644 --- a/libsimple/strdup.h +++ b/libsimple/strdup.h @@ -22,7 +22,7 @@ /** - * Version of strdup(3) that calles `libsimple_enprintf` on error + * Version of strdup(3) that calls `libsimple_enprintf` on error * * @param status Exit value in case of failure * @param s The string to copy @@ -36,7 +36,7 @@ char *libsimple_enstrdup(int, const char *); /** - * Version of strdup(3) that calles `libsimple_eprintf` on error + * Version of strdup(3) that calls `libsimple_eprintf` on error * * @param s The string to copy * @return Duplicate of `s` diff --git a/libsimple/strndup.h b/libsimple/strndup.h index 4a7dc22..2b5bbd0 100644 --- a/libsimple/strndup.h +++ b/libsimple/strndup.h @@ -26,7 +26,7 @@ /** - * Version of strndup(3) that calles `libsimple_enprintf` on error + * Version of strndup(3) that calls `libsimple_enprintf` on error * * @param status Exit value in case of failure * @param s The string to copy @@ -41,7 +41,7 @@ char *libsimple_enstrndup(int, const char *, size_t); /** - * Version of strndup(3) that calles `libsimple_eprintf` on error + * Version of strndup(3) that calls `libsimple_eprintf` on error * * @param s The string to copy * @param n The maximum number of bytes to copy diff --git a/libsimple/valloc.h b/libsimple/valloc.h index 02d301a..6f9d57b 100644 --- a/libsimple/valloc.h +++ b/libsimple/valloc.h @@ -1,5 +1,9 @@ /* See LICENSE file for copyright and license details. */ +/* + * The alignment will be the page size. + */ + _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __warn_unused_result__))) static inline void *libsimple_vvallocn(size_t __n, va_list __ap) { return libsimple_vvalloczn(0, __n, __ap); } diff --git a/libsimple/vallocz.h b/libsimple/vallocz.h index d32598e..2831cf8 100644 --- a/libsimple/vallocz.h +++ b/libsimple/vallocz.h @@ -1,5 +1,9 @@ /* See LICENSE file for copyright and license details. */ +/* + * The alignment will be the page size. + */ + _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __warn_unused_result__))) static inline void * libsimple_vvalloczn(int __clear, size_t __n, va_list __ap) /* TODO test ([v]valloc[z]n) */ -- cgit v1.2.3-70-g09d2