From 1afd32d34d4221853d9e5c8c2a000d94d216388d Mon Sep 17 00:00:00 2001 From: Mattias Andrée Date: Sat, 27 Oct 2018 14:02:44 +0200 Subject: Add doc to aligned_memdup.h, memdup.h, strdup.h, and strndup.h MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Mattias Andrée --- libsimple/aligned_memdup.h | 37 +++++++++++++++++++++++++++++++++++++ libsimple/memdup.h | 33 +++++++++++++++++++++++++++++++++ libsimple/strdup.h | 22 ++++++++++++++++++++++ libsimple/strndup.h | 25 +++++++++++++++++++++++++ 4 files changed, 117 insertions(+) diff --git a/libsimple/aligned_memdup.h b/libsimple/aligned_memdup.h index 8138eb2..6555280 100644 --- a/libsimple/aligned_memdup.h +++ b/libsimple/aligned_memdup.h @@ -1,5 +1,14 @@ /* See LICENSE file for copyright and license details. */ + +/** + * Stack allocation version of `libsimple_aligned_memdup` + * + * @param s:const void * The bytes to copy + * @param alignment:size_t The alignment of the returned pointer + * @param n:size_t The number of bytes to copy + * @return :void * Duplicate of `s` with automatic storage + */ #if defined(__GNUC__) || defined(__clang__) # define libsimple_aligned_memdupa(s, alignment, n)\ ({\ @@ -20,18 +29,46 @@ # endif #endif + +/** + * Create a new allocation, with custom alignment, and copy bytes into it + * + * @param s The bytes to copy + * @param alignment The alignment of the returned pointer + * @param n The number of bytes to copy + * @return Duplicate of `s`, `NULL` on failure + */ _LIBSIMPLE_GCC_ONLY(__attribute__((__alloc_align__(2), __alloc_size__(3), __nonnull__, __warn_unused_result__))) void *libsimple_aligned_memdup(const void *, size_t, size_t); #ifndef aligned_memdup # define aligned_memdup libsimple_aligned_memdup #endif + +/** + * Version of `libsimple_aligned_memdup` that calles `libsimple_enprintf` on error + * + * @param status Exit value in case of failure + * @param s The bytes to copy + * @param alignment The alignment of the returned pointer + * @param n The number of bytes to copy + * @return Duplicate of `s` + */ _LIBSIMPLE_GCC_ONLY(__attribute__((__alloc_align__(3), __alloc_size__(4), __warn_unused_result__, __returns_nonnull__))) void *libsimple_enaligned_memdup(int, const void *, size_t, size_t); #ifndef enaligned_memdup # define enaligned_memdup libsimple_enaligned_memdup #endif + +/** + * Version of `libsimple_aligned_memdup` that calles `libsimple_eprintf` on error + * + * @param s The bytes to copy + * @param alignment The alignment of the returned pointer + * @param n The number of bytes to copy + * @return Duplicate of `s` + */ _LIBSIMPLE_GCC_ONLY(__attribute__((__alloc_align__(2), __alloc_size__(3), __warn_unused_result__, __returns_nonnull__))) static inline void *libsimple_ealigned_memdup(const void *__s, size_t __alignment, size_t __n) { return enaligned_memdup(libsimple_default_failure_exit, __s, __alignment, __n); } diff --git a/libsimple/memdup.h b/libsimple/memdup.h index 44d3a2a..b7f2d6b 100644 --- a/libsimple/memdup.h +++ b/libsimple/memdup.h @@ -1,5 +1,13 @@ /* See LICENSE file for copyright and license details. */ + +/** + * Stack allocation version of `libsimple_memdup` + * + * @param s:const void * The bytes to copy + * @param n:size_t The number of bytes to copy + * @return :void * Duplicate of `s` with automatic storage + */ #if defined(__GNUC__) || defined(__clang__) # define libsimple_memdupa(s, n)\ ({\ @@ -13,18 +21,43 @@ # endif #endif + +/** + * Create a new allocation and copy bytes into it + * + * @param s The bytes to copy + * @param n The number of bytes to copy + * @return Duplicate of `s`, `NULL` on failure + */ _LIBSIMPLE_GCC_ONLY(__attribute__((__alloc_size__(2), __nonnull__, __warn_unused_result__))) void *libsimple_memdup(const void *, size_t); #ifndef memdup # define memdup libsimple_memdup #endif + +/** + * Version of `libsimple_memdup` that calles `libsimple_enprintf` on error + * + * @param status Exit value in case of failure + * @param s The bytes to copy + * @param n The number of bytes to copy + * @return Duplicate of `s` + */ _LIBSIMPLE_GCC_ONLY(__attribute__((__alloc_size__(3), __warn_unused_result__, __returns_nonnull__))) void *libsimple_enmemdup(int, const void *, size_t); #ifndef enmemdup # define enmemdup libsimple_enmemdup #endif + +/** + * Version of `libsimple_memdup` that calles `libsimple_eprintf` on error + * + * @param s The bytes to copy + * @param n The number of bytes to copy + * @return Duplicate of `s` + */ _LIBSIMPLE_GCC_ONLY(__attribute__((__alloc_size__(2), __warn_unused_result__, __returns_nonnull__))) static inline void *libsimple_ememdup(const void *__s, size_t __n) { return enmemdup(libsimple_default_failure_exit, __s, __n); } diff --git a/libsimple/strdup.h b/libsimple/strdup.h index 1397893..9f069f4 100644 --- a/libsimple/strdup.h +++ b/libsimple/strdup.h @@ -1,5 +1,12 @@ /* See LICENSE file for copyright and license details. */ + +/** + * Stack allocation version of strdup(3) + * + * @param s:const char * The string to copy + * @return :char * Duplicate of `s` with automatic storage + */ #if defined(__GNUC__) || defined(__clang__) # define libsimple_strdupa(s)\ ({\ @@ -13,12 +20,27 @@ # endif #endif + +/** + * Version of strdup(3) that calles `libsimple_enprintf` on error + * + * @param status Exit value in case of failure + * @param s The string to copy + * @return Duplicate of `s` + */ _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __assume_aligned__(1), __nonnull__, __warn_unused_result__, __returns_nonnull__))) char *libsimple_enstrdup(int, const char *); #ifndef enstrdup # define enstrdup libsimple_enstrdup #endif + +/** + * Version of strdup(3) that calles `libsimple_eprintf` on error + * + * @param s The string to copy + * @return Duplicate of `s` + */ _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __assume_aligned__(1), __nonnull__, __warn_unused_result__, __returns_nonnull__))) static inline char *libsimple_estrdup(const char *__s) { return enstrdup(libsimple_default_failure_exit, __s); } diff --git a/libsimple/strndup.h b/libsimple/strndup.h index 961b131..4a7dc22 100644 --- a/libsimple/strndup.h +++ b/libsimple/strndup.h @@ -1,5 +1,13 @@ /* See LICENSE file for copyright and license details. */ + +/** + * Stack allocation version of strndup(3) + * + * @param s:const char * The string to copy + * @param n:size_t The maximum number of bytes to copy + * @return :char * Duplicate of `s` with automatic storage + */ #if defined(__GNUC__) || defined(__clang__) # define libsimple_strndupa(s, n)\ ({\ @@ -16,12 +24,29 @@ # endif #endif + +/** + * Version of strndup(3) that calles `libsimple_enprintf` on error + * + * @param status Exit value in case of failure + * @param s The string to copy + * @param n The maximum number of bytes to copy + * @return Duplicate of `s` + */ _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __assume_aligned__(1), __nonnull__, __warn_unused_result__, __returns_nonnull__))) char *libsimple_enstrndup(int, const char *, size_t); #ifndef enstrndup # define enstrndup libsimple_enstrndup #endif + +/** + * Version of strndup(3) that calles `libsimple_eprintf` on error + * + * @param s The string to copy + * @param n The maximum number of bytes to copy + * @return Duplicate of `s` + */ _LIBSIMPLE_GCC_ONLY(__attribute__((__malloc__, __assume_aligned__(1), __nonnull__, __warn_unused_result__, __returns_nonnull__))) static inline char *libsimple_estrndup(const char *__s, size_t __n) { return enstrndup(libsimple_default_failure_exit, __s, __n); } -- cgit v1.2.3-70-g09d2