From 9537d8e087731fc6d6de22d29b2dccda572d7f06 Mon Sep 17 00:00:00 2001 From: Mattias Andrée Date: Wed, 25 Nov 2015 11:46:10 +0100 Subject: tell in doc in which version things were introduced MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Mattias Andrée --- include/alloca.h | 2 + include/assert.h | 8 ++ include/bits/types.h | 68 +++++++++++ include/ctype.h | 68 +++++++++++ include/err.h | 24 +++- include/errno.h | 6 + include/error.h | 14 +++ include/inttypes.h | 314 +++++++++++++++++++++++++++++++++++++++++++++++- include/iso646.h | 22 ++++ include/libgen.h | 6 + include/malloc.h | 26 ++++ include/slibc-alloc.h | 50 ++++++++ include/slibc-error.h | 12 ++ include/slibc-human.h | 54 +++++++++ include/slibc-print.h | 24 ++++ include/slibc/version.h | 16 +++ include/stdalign.h | 4 + include/stdarg.h | 10 ++ include/stdbool.h | 8 ++ include/stddef.h | 4 + include/stdint.h | 122 +++++++++++++++++++ include/stdio.h | 152 ++++++++++++++++++++++- include/stdlib.h | 30 +++++ include/stdnoreturn.h | 2 + include/string.h | 138 +++++++++++++++++++++ include/strings.h | 26 ++++ include/sys/stat.h | 12 ++ include/unistd.h | 50 ++++++++ include/wchar.h | 128 ++++++++++++++++++++ 29 files changed, 1391 insertions(+), 9 deletions(-) (limited to 'include') diff --git a/include/alloca.h b/include/alloca.h index a800cf0..a660f1e 100644 --- a/include/alloca.h +++ b/include/alloca.h @@ -43,6 +43,8 @@ * @return Pointer to the beginning of the allocated * space. Do not free it, it will be freed * automatically when the function returns. + * + * @since Always. */ void* alloca(size_t); #if defined(__GNUC__) diff --git a/include/assert.h b/include/assert.h index 4523860..5330df9 100644 --- a/include/assert.h +++ b/include/assert.h @@ -37,6 +37,8 @@ * to save CPU-cycles. * * @etymology (Assert)ion. + * + * @since Always. */ #ifdef NDEBUG # define assert(expression) ((void)0) @@ -59,6 +61,8 @@ * @etymology (`assert`) version of (`perror`). * * @param errnum:int The error code, describing the error that occurred. + * + * @since Always. */ # ifdef assert_perror # undef assert_perror @@ -92,6 +96,8 @@ * * @param expression:scalar The expression to evaluate. * @param message:const char* The message to print on error. + * + * @since Always. */ # define static_assert _Static_assert #endif @@ -106,6 +112,8 @@ * @param line The line in the source code whence the assertion was made. * @param func The function in the source code whence the assertion was made, * `NULL` if unknown (C99 is required.) + * + * @since Always. */ __noreturn void __assert_fail(const char*, int, const char*, int, const char*) __GCC_ONLY(__attribute__((__nonnull__(3, 5)))); diff --git a/include/bits/types.h b/include/bits/types.h index 0cb83a4..8a91846 100644 --- a/include/bits/types.h +++ b/include/bits/types.h @@ -63,6 +63,8 @@ /** * Signed integer type of the result of subtracting two pointers. * May not be greater than the width of type `long int`. + * + * @since Always. */ #if defined(__NEED_ptrdiff_t) && !defined(__DEFINED_ptrdiff_t) # define __DEFINED_ptrdiff_t @@ -72,6 +74,8 @@ typedef signed __LIMITED_PTR_INT ptrdiff_t; /** * Unsigned version of `ptrdiff_t` + * + * @since Always. */ #if defined(__NEED_uptrdiff_t) && !defined(__DEFINED_uptrdiff_t) # define __DEFINED_uptrdiff_t @@ -95,6 +99,8 @@ typedef unsigned __LIMITED_PTR_INT uptrdiff_t; * it is implementation specific and may depend on the * libc implementation, the version of the libc implementation, * and the microarchitecture. + * + * @since Always. */ # if defined(__NEED_wchar_t) && !defined(__DEFINED_wchar_t) # define __DEFINED_wchar_t @@ -129,6 +135,8 @@ typedef __WCHAR_SIGNNESS __INT64 wchar_t * it is implementation specific and may depend on the * libc implementation, the version of the libc implementation, * and the microarchitecture. + * + * @since Always. */ # if defined(__NEED_wint_t) && !defined(__DEFINED_wint_t) # define __DEFINED_wint_t @@ -142,6 +150,8 @@ typedef wchar_t wint_t * Unsigned integer type of the result of the * `sizeof` operator. May not be greater than the * width of type `long int`. + * + * @since Always. */ #if defined(__NEED_size_t) && !defined(__DEFINED_size_t) # define __DEFINED_size_t @@ -151,6 +161,8 @@ typedef unsigned __LIMITED_PTR_INT size_t; /** * Signed version of `size_t` + * + * @since Always. */ #if defined(__NEED_ssize_t) && !defined(__DEFINED_ssize_t) # define __DEFINED_ssize_t @@ -161,6 +173,8 @@ typedef signed __LIMITED_PTR_INT ssize_t; /** * A type, of unspecified construct, whose alignment requirement * is at least as strict as that of every scalar type. + * + * @since Always. */ #if defined(__NEED_max_align_t) && !defined(__DEFINED_max_align_t) # define __DEFINED_max_align_t @@ -176,6 +190,8 @@ typedef struct * Signed exact-width integer types. * * These types are guaranteed to use two's complement. + * + * @since Always. */ #if defined(__NEED_intN_t) && !defined(__DEFINED_intN_t) # define __DEFINED_intN_t @@ -188,6 +204,8 @@ typedef signed __INT64 int64_t; /** * Unsigned exact-width integer types. + * + * @since Always. */ #if defined(__NEED_uintN_t) && !defined(__DEFINED_uintN_t) # define __DEFINED_uintN_t @@ -204,6 +222,8 @@ typedef unsigned __INT64 uint64_t; * * `int_least8_t`, `int_least16_t`, `int_least32_t`, and * `int_least64_t` are guaranteed to be defined. + * + * @since Always. */ #if defined(__NEED_int_leastN_t) && !defined(__DEFINED_int_leastN_t) # define __DEFINED_int_leastN_t @@ -220,6 +240,8 @@ typedef signed __INT64 int_least64_t; * * `uint_least8_t`, `uint_least16_t`, `uint_least32_t`, and * `uint_least64_t` are guaranteed to be defined. + * + * @since Always. */ #if defined(__NEED_uint_leastN_t) && !defined(__DEFINED_uint_leastN_t) # define __DEFINED_uint_leastN_t @@ -240,6 +262,8 @@ typedef unsigned __INT64 uint_least64_t; * in serialised/marshalled data, as they may depend * on the C library the program is compiled against * and the version of that library. + * + * @since Always. */ #if defined(__NEED_int_fastN_t) && !defined(__DEFINED_int_fastN_t) # define __DEFINED_int_fastN_t @@ -260,6 +284,8 @@ typedef signed __INT_FAST64 int_fast64_t; * in serialised/marshalled data, as they may depend * on the C library the program is compiled against * and the version of that library. + * + * @since Always. */ #if defined(__NEED_uint_fastN_t) && !defined(__DEFINED_uint_fastN_t) # define __DEFINED_uint_fastN_t @@ -272,6 +298,8 @@ typedef unsigned __INT_FAST64 uint_fast64_t; /** * The widest signed integer type available. + * + * @since Always. */ #if defined(__NEED_intmax_t) && !defined(__DEFINED_intmax_t) # define __DEFINED_intmax_t @@ -284,6 +312,8 @@ typedef signed __INT64 intmax_t; /** * The widest unsigned integer type available. + * + * @since Always. */ #if defined(__NEED_uintmax_t) && !defined(__DEFINED_uintmax_t) # define __DEFINED_uintmax_t @@ -299,6 +329,8 @@ typedef unsigned __INT64 uintmax_t; * It may be defined as volatile, slibc does not do * this however because it is good practice to do * so explcitily when using the `sig_atomic_t` type. + * + * @since Always. */ #if defined(__NEED_sig_atomic_t) && !defined(__DEFINED_sig_atomic_t) # define __DEFINED_sig_atomic_t @@ -313,6 +345,8 @@ typedef int sig_atomic_t; * A structure than holds both the quotient and * the remainer in an integer division, of * `int` type. + * + * @since Always. */ #if defined(__NEED_div_t) && !defined(__DEFINED_div_t) # define __DEFINED_div_t @@ -335,6 +369,8 @@ typedef struct { * A structure than holds both the quotient and * the remainer in an integer division, of * `long int` type. + * + * @since Always. */ #if defined(__NEED_ldiv_t) && !defined(__DEFINED_ldiv_t) # define __DEFINED_ldiv_t @@ -357,6 +393,8 @@ typedef struct { * A structure than holds both the quotient and * the remainer in an integer division, of * `long long int` type. + * + * @since Always. */ #if defined(__NEED_lldiv_t) && !defined(__DEFINED_lldiv_t) # define __DEFINED_lldiv_t @@ -379,6 +417,8 @@ typedef struct { * A structure than holds both the quotient and * the remainer in an integer division, of * `intmax_t` type. + * + * @since Always. */ #if defined(__NEED_imaxdiv_t) && !defined(__DEFINED_imaxdiv_t) # define __DEFINED_imaxdiv_t @@ -399,6 +439,8 @@ typedef struct { /** * Locale datatype. + * + * @since Always. */ #if defined(__NEED_locale_t) && !defined(__DEFINED_locale_t) # define __DEFINED_locale_t @@ -411,6 +453,8 @@ typedef int locale_t; /* TODO not implemented */ /** * State of variadic argument-reading. + * + * @since Always. */ #define __ONLY_va_list # include @@ -419,6 +463,8 @@ typedef int locale_t; /* TODO not implemented */ /** * Datatype for file permissions and file type. + * + * @since Always. */ #if defined(__NEED_mode_t) && !defined(__DEFINED_mode_t) # define __DEFINED_mode_t @@ -428,6 +474,8 @@ typedef unsigned int mode_t; /** * Datatype for process identifiers. + * + * @since Always. */ #if defined(__NEED_pid_t) && !defined(__DEFINED_pid_t) # define __DEFINED_pid_t @@ -437,6 +485,8 @@ typedef signed int pid_t; /** * Datatype for user identifiers. + * + * @since Always. */ #if defined(__NEED_uid_t) && !defined(__DEFINED_uid_t) # define __DEFINED_uid_t @@ -446,6 +496,8 @@ typedef unsigned int uid_t; /** * Datatype for group identifiers. + * + * @since Always. */ #if defined(__NEED_gid_t) && !defined(__DEFINED_gid_t) # define __DEFINED_gid_t @@ -457,6 +509,8 @@ typedef unsigned int gid_t; * Datatype for microseconds. * (The name should be 'µseconds', but we are limited * to ASCII and 'u' looks similar to 'µ'.) + * + * @since Always. */ #if defined(__NEED_useconds_t) && !defined(__DEFINED_useconds_t) # define __DEFINED_useconds_t @@ -466,6 +520,8 @@ typedef signed long useconds_t; /** * Datatype for file offsets. + * + * @since Always. */ #if defined(__NEED_off_t) && !defined(__DEFINED_off_t) # define __DEFINED_off_t @@ -477,6 +533,8 @@ typedef signed __INT64 off_t; * Datatype for inode identifiers, the number identifying * a file on a filesystem. * ('inode' is probably a contraction of 'index node'.) + * + * @since Always. */ #if defined(__NEED_ino_t) && !defined(__DEFINED_ino_t) # define __DEFINED_ino_t @@ -486,6 +544,8 @@ typedef unsigned __INT64 ino_t; /** * Datatype for device identifiers. + * + * @since Always. */ #if defined(__NEED_dev_t) && !defined(__DEFINED_dev_t) # define __DEFINED_dev_t @@ -495,6 +555,8 @@ typedef unsigned __INT64 dev_t; /** * Datatype for filesystem block counts. + * + * @since Always. */ #if defined(__NEED_fsblkcnt_t) && !defined(__DEFINED_fsblkcnt_t) # define __DEFINED_fsblkcnt_t @@ -504,6 +566,8 @@ typedef unsigned __INT64 fsblkcnt_t; /** * Datatype for filesystem file counts. + * + * @since Always. */ #if defined(__NEED_fsfilcnt_t) && !defined(__DEFINED_fsfilcnt_t) # define __DEFINED_fsfilcnt_t @@ -513,6 +577,8 @@ typedef unsigned __INT64 fsfilcnt_t; /** * Datatype for block sizes. + * + * @since Always. */ #if defined(__NEED_blksize_t) && !defined(__DEFINED_blksize_t) # define __DEFINED_blksize_t @@ -522,6 +588,8 @@ typedef signed __LIMITED_PTR_INT blksize_t; /** * Datatype for block counts. + * + * @since Always. */ #if defined(__NEED_blkcnt_t) && !defined(__DEFINED_blkcnt_t) # define __DEFINED_blkcnt_t diff --git a/include/ctype.h b/include/ctype.h index 9b6508c..ec715d8 100644 --- a/include/ctype.h +++ b/include/ctype.h @@ -41,6 +41,8 @@ * @param c The character. * @return Whether the character is in * ['0', '9'], ['A', 'Z'], or ['a', 'z']. + * + * @since Always. */ int (isalnum)(int) /* [0x30, 0x39], [0x41, 0x5A], [0x61, 0x7A] */ __GCC_ONLY(__attribute__((__const__))); @@ -58,6 +60,8 @@ int (isalnum)(int) /* [0x30, 0x39], [0x41, 0x5A], [0x61, 0x7A] */ * @param c The character. * @return Whether the character is in * ['A', 'Z'] or ['a', 'z']. + * + * @since Always. */ int (isalpha)(int) /* [0x41, 0x5A], [0x61, 0x7A] */ __GCC_ONLY(__attribute__((__const__))); @@ -75,6 +79,8 @@ int (isalpha)(int) /* [0x41, 0x5A], [0x61, 0x7A] */ * * @param c The character. * @return Whether the character is a ' ' or a '\t'. + * + * @since Always. */ int (isblank)(int) /* ' ', '\t' */ __GCC_ONLY(__attribute__((__const__))); @@ -94,6 +100,8 @@ int (isblank)(int) /* ' ', '\t' */ * @param c The character. * @return Whether the character is lower than ' ', * or is 0x7F. + * + * @since Always. */ int (iscntrl)(int) /* [0x00, 0x1F], 0x7F */ __GCC_ONLY(__attribute__((__const__))); @@ -110,6 +118,8 @@ int (iscntrl)(int) /* [0x00, 0x1F], 0x7F */ * * @param c The character. * @return Whether the character is in ['0', '9']. + * + * @since Always. */ int (isdigit)(int) /* [0x30, 0x39] */ __GCC_ONLY(__attribute__((__const__))); @@ -124,6 +134,8 @@ int (isdigit)(int) /* [0x30, 0x39] */ * @param c The character. * @return Whether the character is greater * than ' ', but is not 0x7F. + * + * @since Always. */ int (isgraph)(int) /* [0x21, 0x7E] */ __GCC_ONLY(__attribute__((__const__))); @@ -138,6 +150,8 @@ int (isgraph)(int) /* [0x21, 0x7E] */ * * @param c The character. * @return Whether the character is in ['a', 'z']. + * + * @since Always. */ int (islower)(int) /* [0x61, 0x7A] */ __GCC_ONLY(__attribute__((__const__))); @@ -153,6 +167,8 @@ int (islower)(int) /* [0x61, 0x7A] */ * @param c The character. * @return Whether the character is at least * as great as ' ', but is not 0x7F. + * + * @since Always. */ int (isprint)(int) /* [0x20, 0x7E] */ __GCC_ONLY(__attribute__((__const__))); @@ -168,6 +184,8 @@ int (isprint)(int) /* [0x20, 0x7E] */ * * @param c The character. * @return Whether the character is a punctuation. + * + * @since Always. */ int (ispunct)(int) /* isprint && !isalnum && !isspace */ __GCC_ONLY(__attribute__((__const__))); @@ -185,6 +203,8 @@ int (ispunct)(int) /* isprint && !isalnum && !isspace */ * @param c The character. * @return Whether the character is a ' ', '\f', * '\n', '\r', '\t', or '\v'. + * + * @since Always. */ int (isspace)(int) /* 0x20, [0x09, 0x0D] */ __GCC_ONLY(__attribute__((__const__))); @@ -202,6 +222,8 @@ int (isspace)(int) /* 0x20, [0x09, 0x0D] */ * * @param c The character. * @return Whether the character is in ['A', 'Z']. + * + * @since Always. */ int (isupper)(int) /* [0x41, 0x5A] */ __GCC_ONLY(__attribute__((__const__))); @@ -218,6 +240,8 @@ int (isupper)(int) /* [0x41, 0x5A] */ * @param c The character. * @return Whether the character is in * ['0', '9'], ['A', 'Z'], or ['a', 'z']. + * + * @since Always. */ int (isxdigit)(int) /* [0x30, 0x39], [0x41, 0x46], [0x61, 0x66] */ __GCC_ONLY(__attribute__((__const__))); @@ -243,6 +267,8 @@ int (isxdigit)(int) /* [0x30, 0x39], [0x41, 0x46], [0x61, 0x66] */ * @return The character in lowercase. * Guaranteed to be unchanged if the * character already is in lowercase. + * + * @since Always. */ int (tolower)(int) /* [0x41, 0x5A] -> [0x61, 0x7A] */ __GCC_ONLY(__attribute__((__const__))); @@ -263,6 +289,8 @@ int (tolower)(int) /* [0x41, 0x5A] -> [0x61, 0x7A] */ * @return The character in uppercase. * Guaranteed to be unchanged if the * character already is in lowercase. + * + * @since Always. */ int (toupper)(int) /* [0x61, 0x7A] -> [0x41, 0x5A] */ __GCC_ONLY(__attribute__((__const__))); @@ -277,6 +305,8 @@ int (toupper)(int) /* [0x61, 0x7A] -> [0x41, 0x5A] */ * * @param c The character * @return Whether the character is an ASCII character. + * + * @since Always. */ int (isascii)(int) /* [0x00, 0x7E] */ __GCC_ONLY(__attribute__((__const__))); @@ -296,6 +326,8 @@ int (isascii)(int) /* [0x00, 0x7E] */ * * @param c The character. * @return The character with the 8:th bit cleared. + * + * @since Always. */ int (toascii)(int) __warning("Using 'toascii' is, generally, unwise.") @@ -307,6 +339,8 @@ int (toascii)(int) /** * This function is identical to `tolower`. * It is provided for backwards-compatibility with SVID. + * + * @since Always. */ int _tolower(int) __deprecated("Use 'tolower' instead.") @@ -315,6 +349,8 @@ int _tolower(int) /** * This function is identical to `tolower`. * It is provided for backwards-compatibility with SVID. + * + * @since Always. */ int _toupper(int) __deprecated("Use 'toupper' instead.") @@ -332,6 +368,8 @@ int _toupper(int) * @param locale The locale. * @return Whether the character is * alphabetical or numerical. + * + * @since Always. */ int isalnum_l(int, locale_t) __warning("This function is dangerous, use 'iswalnum_l' instead.") @@ -345,6 +383,8 @@ int isalnum_l(int, locale_t) * @param c The character. * @param locale The locale. * @return Whether the character is alphabetical. + * + * @since Always. */ int isalpha_l(int, locale_t) __warning("This function is dangerous, use 'iswalpha_l' instead.") @@ -362,6 +402,8 @@ int isalpha_l(int, locale_t) * @param c The character. * @param locale The locale. * @return Whether the character is a ' ' or a '\t'. + * + * @since Always. */ int isblank_l(int, locale_t) __warning("This function is dangerous, use 'iswblank_l' instead.") @@ -377,6 +419,8 @@ int isblank_l(int, locale_t) * @param c The character. * @param locale The locale. * @return Whether the character is non-printable. + * + * @since Always. */ int iscntrl_l(int, locale_t) __warning("This function is dangerous, use 'iswcntrl_l' instead.") @@ -390,6 +434,8 @@ int iscntrl_l(int, locale_t) * @param c The character. * @param locale The locale. * @return Whether the character is numerical. + * + * @since Always. */ int isdigit_l(int, locale_t) __warning("This function is dangerous, use 'iswdigit_l' instead.") @@ -403,6 +449,8 @@ int isdigit_l(int, locale_t) * @param c The character. * @param locale The locale. * @return Whether the character has a glyph. + * + * @since Always. */ int isgraph_l(int, locale_t) __warning("This function is dangerous, use 'iswgraph_l' instead.") @@ -417,6 +465,8 @@ int isgraph_l(int, locale_t) * @param c The character. * @param locale The locale. * @return Whether the character is a lowercase letter. + * + * @since Always. */ int islower_l(int, locale_t) __warning("This function is dangerous, use 'iswlower_l' instead.") @@ -432,6 +482,8 @@ int islower_l(int, locale_t) * @param locale The locale. * @return Whether the character has a printable * glyph or is a blank space. + * + * @since Always. */ int isprint_l(int, locale_t) __warning("This function is dangerous, use 'iswprint_l' instead.") @@ -447,6 +499,8 @@ int isprint_l(int, locale_t) * @param c The character. * @param locale The locale. * @return Whether the character is a punctuation. + * + * @since Always. */ int ispunct_l(int, locale_t) __warning("This function is dangerous, use 'iswpunct_l' instead.") @@ -461,6 +515,8 @@ int ispunct_l(int, locale_t) * @param locale The locale. * @return Whether the character is a * whitespace character. + * + * @since Always. */ int isspace_l(int, locale_t) __warning("This function is dangerous, use 'iswspace_l' instead.") @@ -475,6 +531,8 @@ int isspace_l(int, locale_t) * @param c The character. * @param locale The locale. * @return Whether the character is a uppercase letter. + * + * @since Always. */ int isupper_l(int, locale_t) __warning("This function is dangerous, use 'iswupper_l' instead.") @@ -491,6 +549,8 @@ int isupper_l(int, locale_t) * @param locale The locale. * @return Whether the character is in * ['0', '9'], ['A', 'Z'], or ['a', 'z']. + * + * @since Always. */ int isxdigit_l(int, locale_t) __warning("This function is dangerous, use 'iswxdigit_l' instead.") @@ -504,6 +564,8 @@ int isxdigit_l(int, locale_t) * @param c The character * @param locale The locale. * @return Whether the character is an ASCII character. + * + * @since Always. */ int isascii_l(int, locale_t) __warning("This function is dangerous, use 'iswascii_l' instead.") @@ -520,6 +582,8 @@ int isascii_l(int, locale_t) * @param c The character. * @param locale The locale. * @return The character with the 8:th bit cleared. + * + * @since Always. */ int toascii_l(int, locale_t) __warning("This function is dangerous, use 'towascii_l' instead.") @@ -542,6 +606,8 @@ int toascii_l(int, locale_t) * @return The character in lowercase. * Guaranteed to be unchanged if the * character already is in lowercase. + * + * @since Always. */ int tolower_l(int, locale_t) __warning("This function is dangerous, use 'iswlower_l' instead.") @@ -564,6 +630,8 @@ int tolower_l(int, locale_t) * @return The character in uppercase. * Guaranteed to be unchanged if the * character already is in lowercase. + * + * @since Always. */ int toupper_l(int, locale_t) __warning("This function is dangerous, use 'iswupper_l' instead.") diff --git a/include/err.h b/include/err.h index 63dcdda..91f5b84 100644 --- a/include/err.h +++ b/include/err.h @@ -41,6 +41,8 @@ * * @param format Formatting-string for the warning. * @param ... Formatting-arguments. + * + * @since Always. */ void warn(const char*, ...) __GCC_ONLY(__attribute__((__format__(__slibc_printf__, 1, 2)))); @@ -55,6 +57,8 @@ void warn(const char*, ...) * * @param format Formatting-string for the warning. * @param args Formatting-arguments. + * + * @since Always. */ void vwarn(const char*, va_list); @@ -68,6 +72,8 @@ void vwarn(const char*, va_list); * * @param format Formatting-string for the warning. * @param ... Formatting-arguments. + * + * @since Always. */ void warnx(const char*, ...) __GCC_ONLY(__attribute__((__format__(__slibc_printf__, 1, 2)))); @@ -82,6 +88,8 @@ void warnx(const char*, ...) * * @param format Formatting-string for the warning. * @param args Formatting-arguments. + * + * @since Always. */ void vwarnx(const char*, va_list); @@ -93,9 +101,11 @@ void vwarnx(const char*, va_list); * * @etymology Report (err)or! * - * @parma status The exit status the process should have. + * @param status The exit status the process should have. * @param format Formatting-string for the warning. * @param ... Formatting-arguments. + * + * @since Always. */ __noreturn void err(int, const char*, ...) __GCC_ONLY(__attribute__((__format__(__slibc_printf__, 2, 3)))); @@ -108,9 +118,11 @@ __noreturn void err(int, const char*, ...) * * @etymology (V)ariadic version of (`err`). * - * @parma status The exit status the process should have. + * @param status The exit status the process should have. * @param format Formatting-string for the warning. * @param args Formatting-arguments. + * + * @since Always. */ __noreturn void verr(int, const char*, va_list); @@ -122,9 +134,11 @@ __noreturn void verr(int, const char*, va_list); * * @etymology (`err`), [x=](lesser variant). * - * @parma status The exit status the process should have. + * @param status The exit status the process should have. * @param format Formatting-string for the warning. * @param ... Formatting-arguments. + * + * @since Always. */ __noreturn void errx(int, const char*, ...) __GCC_ONLY(__attribute__((__format__(__slibc_printf__, 2, 3)))); @@ -137,9 +151,11 @@ __noreturn void errx(int, const char*, ...) * * @etymology (V)ariadic version of (`errx`). * - * @parma status The exit status the process should have. + * @param status The exit status the process should have. * @param format Formatting-string for the warning. * @param args Formatting-arguments. + * + * @since Always. */ __noreturn void verrx(int, const char*, va_list); #endif diff --git a/include/errno.h b/include/errno.h index 293c0d0..749524c 100644 --- a/include/errno.h +++ b/include/errno.h @@ -41,6 +41,8 @@ * that has occurred in the thread. * * @etymology (Err)or (number). + * + * @since Always. */ #define errno (*__errno()) @@ -70,6 +72,8 @@ volatile int* __errno(void) /* TODO not implemented */ * or `argv[0]` is edited. * * This is a GNU and slibc extension. + * + * @since Always. */ #if defined(__GNU_SOURCE) || defined(__SLIBC_SOURCE) extern char* program_invocation_name; /* TODO not implemented */ @@ -83,6 +87,8 @@ extern char* program_invocation_name; /* TODO not implemented */ * or `argv[0]` is edited. * * This is a GNU extension. + * + * @since Always. */ #if defined(__GNU_SOURCE) extern char* program_invocation_short_name; /* TODO not implemented */ diff --git a/include/error.h b/include/error.h index 5d0e24f..f2cf9f6 100644 --- a/include/error.h +++ b/include/error.h @@ -45,6 +45,8 @@ * be printed. * @param format Formatting-string for a detailed description of what happend. * @param args Formatting-arguments for `format`. + * + * @since Always. */ void error(int, int, const char*, ...) __GCC_ONLY(__attribute__((__format__(__slibc_printf__, 3, 4)))); @@ -63,6 +65,8 @@ void error(int, int, const char*, ...) * be printed. * @param format Formatting-string for a detailed description of what happend. * @param args Formatting-arguments for `format`. + * + * @since Always. */ # if defined(__SLIBC_SOURCE) void verror(int, int, const char*, va_list); @@ -86,6 +90,8 @@ void verror(int, int, const char*, va_list); * @param linenum The line number of in the source code file where the error occurred. * @param format Formatting-string for a detailed description of what happend. * @param args Formatting-arguments for `format`. + * + * @since Always. */ void error_at_line(int, int, const char*, unsigned int, const char*, ...) __GCC_ONLY(__attribute__((__format__(__slibc_printf__, 5, 6)))); @@ -107,6 +113,8 @@ void error_at_line(int, int, const char*, unsigned int, const char*, ...) * @param linenum The line number of in the source code file where the error occurred. * @param format Formatting-string for a detailed description of what happend. * @param args Formatting-arguments for `format`. + * + * @since Always. */ # if defined(__SLIBC_SOURCE) void verror_at_line(int, int, const char*, unsigned int, const char*, va_list); @@ -121,6 +129,8 @@ void verror_at_line(int, int, const char*, unsigned int, const char*, va_list); * This is a GNU extension. * * @etymology (`error`)-subsystem: (message count). + * + * @since Always. */ extern volatile unsigned int error_message_count; @@ -141,6 +151,8 @@ extern volatile unsigned int error_message_count; * This is a GNU extension. * * @etymology (`error`)-subsystem: print (one) time (per line). + * + * @since Always. */ extern volatile int error_one_per_line; @@ -154,6 +166,8 @@ extern volatile int error_one_per_line; * This is a GNU extension. * * @etymology (`error`)-subsystem function: (print) the (prog)ram's (name). + * + * @since Always. */ extern void (*volatile error_print_progname)(void); #endif diff --git a/include/inttypes.h b/include/inttypes.h index 5602e97..4a02d5a 100644 --- a/include/inttypes.h +++ b/include/inttypes.h @@ -44,6 +44,8 @@ * the process will be killed by SIGFPE. * @return The quotient in `.quot`, and * the remainder in `.rem`. + * + * @since Always. */ imaxdiv_t imaxdiv(intmax_t, intmax_t) __GCC_ONLY(__attribute__((__const__))); @@ -60,6 +62,8 @@ imaxdiv_t imaxdiv(intmax_t, intmax_t) * * @param value The integer. * @return The absolute value of the integer. + * + * @since Always. */ intmax_t (imaxabs)(intmax_t) __GCC_ONLY(__attribute__((__const__))); @@ -67,7 +71,7 @@ intmax_t (imaxabs)(intmax_t) -/* Printing and scanning code affixes. */ +/* Printing and scanning code affixes. FOR INTERNAL USE. */ /** * Length modifier affix for printing an `int8_t` or an `uint8_t`. @@ -179,6 +183,8 @@ intmax_t (imaxabs)(intmax_t) * an int8_t in decimal form. * * @etymology `(pri)ntf` `%(d)` for `int(8)_t`. + * + * @since Always. */ #define PRId8 __PRI8 "d" @@ -187,6 +193,8 @@ intmax_t (imaxabs)(intmax_t) * an int16_t in decimal form. * * @etymology `(pri)ntf` `%(d)` for `int(16)_t`. + * + * @since Always. */ #define PRId16 __PRI16 "d" @@ -195,6 +203,8 @@ intmax_t (imaxabs)(intmax_t) * an int32_t in decimal form. * * @etymology `(pri)ntf` `%(d)` for `int(32)_t`. + * + * @since Always. */ #define PRId32 __PRI32 "d" @@ -203,6 +213,8 @@ intmax_t (imaxabs)(intmax_t) * an int64_t in decimal form. * * @etymology `(pri)ntf` `%(d)` for `int(64)_t`. + * + * @since Always. */ #define PRId64 __PRI64 "d" @@ -212,6 +224,8 @@ intmax_t (imaxabs)(intmax_t) * an int_least8_t in decimal form. * * @etymology `(pri)ntf` `%(d)` for `int_(least8)_t`. + * + * @since Always. */ #define PRIdLEAST8 PRId8 @@ -220,6 +234,8 @@ intmax_t (imaxabs)(intmax_t) * an int_least16_t in decimal form. * * @etymology `(pri)ntf` `%(d)` for `int_(least16)_t`. + * + * @since Always. */ #define PRIdLEAST16 PRId16 @@ -228,6 +244,8 @@ intmax_t (imaxabs)(intmax_t) * an int_least32_t in decimal form. * * @etymology `(pri)ntf` `%(d)` for `int_(least32)_t`. + * + * @since Always. */ #define PRIdLEAST32 PRId32 @@ -236,6 +254,8 @@ intmax_t (imaxabs)(intmax_t) * an int_least64_t in decimal form. * * @etymology `(pri)ntf` `%(d)` for `int_(least64)_t`. + * + * @since Always. */ #define PRIdLEAST64 PRId64 @@ -245,6 +265,8 @@ intmax_t (imaxabs)(intmax_t) * an int_fast8_t in decimal form. * * @etymology `(pri)ntf` `%(d)` for `int_(fast8)_t`. + * + * @since Always. */ #define PRIdFAST8 __PRIFAST8 "d" @@ -253,6 +275,8 @@ intmax_t (imaxabs)(intmax_t) * an int_fast16_t in decimal form. * * @etymology `(pri)ntf` `%(d)` for `int_(fast16)_t`. + * + * @since Always. */ #define PRIdFAST16 __PRIFAST16 "d" @@ -261,6 +285,8 @@ intmax_t (imaxabs)(intmax_t) * an int_fast32_t in decimal form. * * @etymology `(pri)ntf` `%(d)` for `int_(fast32)_t`. + * + * @since Always. */ #define PRIdFAST32 __PRIFAST32 "d" @@ -269,6 +295,8 @@ intmax_t (imaxabs)(intmax_t) * an int_fast64_t in decimal form. * * @etymology `(pri)ntf` `%(d)` for `int_(fast64)_t`. + * + * @since Always. */ #define PRIdFAST64 __PRIFAST64 "d" @@ -279,6 +307,8 @@ intmax_t (imaxabs)(intmax_t) * an int8_t in decimal form. * * @etymology `(pri)ntf` `%(i)` for `int(8)_t`. + * + * @since Always. */ #define PRIi8 __PRI8 "i" @@ -287,6 +317,8 @@ intmax_t (imaxabs)(intmax_t) * an int16_t in decimal form. * * @etymology `(pri)ntf` `%(i)` for `int(16)_t`. + * + * @since Always. */ #define PRIi16 __PRI16 "i" @@ -295,6 +327,8 @@ intmax_t (imaxabs)(intmax_t) * an int32_t in decimal form. * * @etymology `(pri)ntf` `%(i)` for `int(32)_t`. + * + * @since Always. */ #define PRIi32 __PRI32 "i" @@ -303,6 +337,8 @@ intmax_t (imaxabs)(intmax_t) * an int64_t in decimal form. * * @etymology `(pri)ntf` `%(i)` for `int(64)_t`. + * + * @since Always. */ #define PRIi64 __PRI64 "i" @@ -312,6 +348,8 @@ intmax_t (imaxabs)(intmax_t) * an int_least8_t in decimal form. * * @etymology `(pri)ntf` `%(i)` for `int_(least8)_t`. + * + * @since Always. */ #define PRIiLEAST8 PRIi8 @@ -320,6 +358,8 @@ intmax_t (imaxabs)(intmax_t) * an int_least16_t in decimal form. * * @etymology `(pri)ntf` `%(i)` for `int_(least16)_t`. + * + * @since Always. */ #define PRIiLEAST16 PRIi16 @@ -328,6 +368,8 @@ intmax_t (imaxabs)(intmax_t) * an int_least32_t in decimal form. * * @etymology `(pri)ntf` `%(i)` for `int_(least32)_t`. + * + * @since Always. */ #define PRIiLEAST32 PRIi32 @@ -336,6 +378,8 @@ intmax_t (imaxabs)(intmax_t) * an int_least64_t in decimal form. * * @etymology `(pri)ntf` `%(i)` for `int_(least64)_t`. + * + * @since Always. */ #define PRIiLEAST64 PRIi64 @@ -345,6 +389,8 @@ intmax_t (imaxabs)(intmax_t) * an int_fast8_t in decimal form. * * @etymology `(pri)ntf` `%(i)` for `int_(fast8)_t`. + * + * @since Always. */ #define PRIiFAST8 __PRIFAST8 "i" @@ -353,6 +399,8 @@ intmax_t (imaxabs)(intmax_t) * an int_fast16_t in decimal form. * * @etymology `(pri)ntf` `%(i)` for `int_(fast16)_t`. + * + * @since Always. */ #define PRIiFAST16 __PRIFAST16 "i" @@ -361,6 +409,8 @@ intmax_t (imaxabs)(intmax_t) * an int_fast32_t in decimal form. * * @etymology `(pri)ntf` `%(i)` for `int_(fast32)_t`. + * + * @since Always. */ #define PRIiFAST32 __PRIFAST32 "i" @@ -369,6 +419,8 @@ intmax_t (imaxabs)(intmax_t) * an int_fast64_t in decimal form. * * @etymology `(pri)ntf` `%(i)` for `int_(fast64)_t`. + * + * @since Always. */ #define PRIiFAST64 __PRIFAST64 "i" @@ -379,6 +431,8 @@ intmax_t (imaxabs)(intmax_t) * an uint8_t in octal form. * * @etymology `(pri)ntf` `%(o)` for `int(8)_t`. + * + * @since Always. */ #define PRIo8 __PRI8 "o" @@ -387,6 +441,8 @@ intmax_t (imaxabs)(intmax_t) * an uint16_t in octal form. * * @etymology `(pri)ntf` `%(o)` for `int(16)_t`. + * + * @since Always. */ #define PRIo16 __PRI16 "o" @@ -395,6 +451,8 @@ intmax_t (imaxabs)(intmax_t) * an uint32_t in octal form. * * @etymology `(pri)ntf` `%(o)` for `int(32)_t`. + * + * @since Always. */ #define PRIo32 __PRI32 "o" @@ -403,6 +461,8 @@ intmax_t (imaxabs)(intmax_t) * an uint64_t in octal form. * * @etymology `(pri)ntf` `%(o)` for `int(64)_t`. + * + * @since Always. */ #define PRIo64 __PRI64 "o" @@ -412,6 +472,8 @@ intmax_t (imaxabs)(intmax_t) * an uint_least8_t in octal form. * * @etymology `(pri)ntf` `%(o)` for `uint_(least8)_t`. + * + * @since Always. */ #define PRIoLEAST8 PRIo8 @@ -420,6 +482,8 @@ intmax_t (imaxabs)(intmax_t) * an uint_least16_t in octal form. * * @etymology `(pri)ntf` `%(o)` for `uint_(least16)_t`. + * + * @since Always. */ #define PRIoLEAST16 PRIo16 @@ -428,6 +492,8 @@ intmax_t (imaxabs)(intmax_t) * an uint_least32_t in octal form. * * @etymology `(pri)ntf` `%(o)` for `uint_(least32)_t`. + * + * @since Always. */ #define PRIoLEAST32 PRIo32 @@ -436,6 +502,8 @@ intmax_t (imaxabs)(intmax_t) * an uint_least64_t in octal form. * * @etymology `(pri)ntf` `%(o)` for `uint_(least64)_t`. + * + * @since Always. */ #define PRIoLEAST64 PRIo64 @@ -445,6 +513,8 @@ intmax_t (imaxabs)(intmax_t) * an uint_fast8_t in octal form. * * @etymology `(pri)ntf` `%(o)` for `uint_(fast8)_t`. + * + * @since Always. */ #define PRIoFAST8 __PRIFAST8 "o" @@ -453,6 +523,8 @@ intmax_t (imaxabs)(intmax_t) * an uint_fast16_t in octal form. * * @etymology `(pri)ntf` `%(o)` for `uint_(fast16)_t`. + * + * @since Always. */ #define PRIoFAST16 __PRIFAST16 "o" @@ -461,6 +533,8 @@ intmax_t (imaxabs)(intmax_t) * an uint_fast32_t in octal form. * * @etymology `(pri)ntf` `%(o)` for `uint_(fast32)_t`. + * + * @since Always. */ #define PRIoFAST32 __PRIFAST32 "o" @@ -469,6 +543,8 @@ intmax_t (imaxabs)(intmax_t) * an uint_fast64_t in octal form. * * @etymology `(pri)ntf` `%(o)` for `uint_(fast64)_t`. + * + * @since Always. */ #define PRIoFAST64 __PRIFAST64 "o" @@ -479,6 +555,8 @@ intmax_t (imaxabs)(intmax_t) * an uint8_t in decimal form. * * @etymology `(pri)ntf` `%(u)` for `uint(8)_t`. + * + * @since Always. */ #define PRIu8 __PRI8 "u" @@ -487,6 +565,8 @@ intmax_t (imaxabs)(intmax_t) * an uint16_t in decimal form. * * @etymology `(pri)ntf` `%(u)` for `uint(16)_t`. + * + * @since Always. */ #define PRIu16 __PRI16 "u" @@ -495,6 +575,8 @@ intmax_t (imaxabs)(intmax_t) * an uint32_t in decimal form. * * @etymology `(pri)ntf` `%(u)` for `uint(32)_t`. + * + * @since Always. */ #define PRIu32 __PRI32 "u" @@ -503,6 +585,8 @@ intmax_t (imaxabs)(intmax_t) * an uint64_t in decimal form. * * @etymology `(pri)ntf` `%(u)` for `uint(64)_t`. + * + * @since Always. */ #define PRIu64 __PRI64 "u" @@ -512,6 +596,8 @@ intmax_t (imaxabs)(intmax_t) * an uint_least8_t in decimal form. * * @etymology `(pri)ntf` `%(u)` for `uint_(least8)_t`. + * + * @since Always. */ #define PRIuLEAST8 PRIu8 @@ -520,6 +606,8 @@ intmax_t (imaxabs)(intmax_t) * an uint_least16_t in decimal form. * * @etymology `(pri)ntf` `%(u)` for `uint_(least16)_t`. + * + * @since Always. */ #define PRIuLEAST16 PRIu16 @@ -528,6 +616,8 @@ intmax_t (imaxabs)(intmax_t) * an uint_least32_t in decimal form. * * @etymology `(pri)ntf` `%(u)` for `uint_(least32)_t`. + * + * @since Always. */ #define PRIuLEAST32 PRIu32 @@ -536,6 +626,8 @@ intmax_t (imaxabs)(intmax_t) * an uint_least64_t in decimal form. * * @etymology `(pri)ntf` `%(u)` for `uint_(least64)_t`. + * + * @since Always. */ #define PRIuLEAST64 PRIu64 @@ -545,6 +637,8 @@ intmax_t (imaxabs)(intmax_t) * an uint_fast8_t in decimal form. * * @etymology `(pri)ntf` `%(u)` for `uint_(fast8)_t`. + * + * @since Always. */ #define PRIuFAST8 __PRIFAST8 "u" @@ -553,6 +647,8 @@ intmax_t (imaxabs)(intmax_t) * an uint_fast16_t in decimal form. * * @etymology `(pri)ntf` `%(u)` for `uint_(fast16)_t`. + * + * @since Always. */ #define PRIuFAST16 __PRIFAST16 "u" @@ -561,6 +657,8 @@ intmax_t (imaxabs)(intmax_t) * an uint_fast32_t in decimal form. * * @etymology `(pri)ntf` `%(u)` for `uint_(fast32)_t`. + * + * @since Always. */ #define PRIuFAST32 __PRIFAST32 "u" @@ -569,6 +667,8 @@ intmax_t (imaxabs)(intmax_t) * an uint_fast64_t in decimal form. * * @etymology `(pri)ntf` `%(u)` for `uint_(fast64)_t`. + * + * @since Always. */ #define PRIuFAST64 __PRIFAST64 "u" @@ -579,6 +679,8 @@ intmax_t (imaxabs)(intmax_t) * uint8_t in lowercase hexadecimal form. * * @etymology `(pri)ntf` `%(x)` for `uint(8)_t`. + * + * @since Always. */ #define PRIx8 __PRI8 "x" @@ -587,6 +689,8 @@ intmax_t (imaxabs)(intmax_t) * uint16_t in lowercase hexadecimal form. * * @etymology `(pri)ntf` `%(x)` for `uint(16)_t`. + * + * @since Always. */ #define PRIx16 __PRI16 "x" @@ -595,6 +699,8 @@ intmax_t (imaxabs)(intmax_t) * uint32_t in lowercase hexadecimal form. * * @etymology `(pri)ntf` `%(x)` for `uint(32)_t`. + * + * @since Always. */ #define PRIx32 __PRI32 "x" @@ -603,6 +709,8 @@ intmax_t (imaxabs)(intmax_t) * uint64_t in lowercase hexadecimal form. * * @etymology `(pri)ntf` `%(x)` for `uint(64)_t`. + * + * @since Always. */ #define PRIx64 __PRI64 "x" @@ -612,6 +720,8 @@ intmax_t (imaxabs)(intmax_t) * uint_least8_t in lowercase hexadecimal form. * * @etymology `(pri)ntf` `%(x)` for `uint_(least8)_t`. + * + * @since Always. */ #define PRIxLEAST8 PRIx8 @@ -620,6 +730,8 @@ intmax_t (imaxabs)(intmax_t) * uint_least16_t in lowercase hexadecimal form. * * @etymology `(pri)ntf` `%(x)` for `uint_(least16)_t`. + * + * @since Always. */ #define PRIxLEAST16 PRIx16 @@ -628,6 +740,8 @@ intmax_t (imaxabs)(intmax_t) * uint_least32_t in lowercase hexadecimal form. * * @etymology `(pri)ntf` `%(x)` for `uint_(least32)_t`. + * + * @since Always. */ #define PRIxLEAST32 PRIx32 @@ -636,6 +750,8 @@ intmax_t (imaxabs)(intmax_t) * uint_least64_t in lowercase hexadecimal form. * * @etymology `(pri)ntf` `%(x)` for `uint_(least64)_t`. + * + * @since Always. */ #define PRIxLEAST64 PRIx64 @@ -645,6 +761,8 @@ intmax_t (imaxabs)(intmax_t) * uint_fast8_t in lowercase hexadecimal form. * * @etymology `(pri)ntf` `%(x)` for `uint_(fast8)_t`. + * + * @since Always. */ #define PRIxFAST8 __PRIFAST8 "x" @@ -653,6 +771,8 @@ intmax_t (imaxabs)(intmax_t) * uint_fast16_t in lowercase hexadecimal form. * * @etymology `(pri)ntf` `%(x)` for `uint_(fast16)_t`. + * + * @since Always. */ #define PRIxFAST16 __PRIFAST16 "x" @@ -661,6 +781,8 @@ intmax_t (imaxabs)(intmax_t) * uint_fast32_t in lowercase hexadecimal form. * * @etymology `(pri)ntf` `%(x)` for `uint_(fast32)_t`. + * + * @since Always. */ #define PRIxFAST32 __PRIFAST32 "x" @@ -669,6 +791,8 @@ intmax_t (imaxabs)(intmax_t) * uint_fast64_t in lowercase hexadecimal form. * * @etymology `(pri)ntf` `%(x)` for `uint_(fast64)_t`. + * + * @since Always. */ #define PRIxFAST64 __PRIFAST64 "x" @@ -679,6 +803,8 @@ intmax_t (imaxabs)(intmax_t) * uint8_t in uppercase hexadecimal form. * * @etymology `(pri)ntf` `%(X)` for `uint(8)_t`. + * + * @since Always. */ #define PRIX8 __PRI8 "X" @@ -687,6 +813,8 @@ intmax_t (imaxabs)(intmax_t) * uint16_t in uppercase hexadecimal form. * * @etymology `(pri)ntf` `%(X)` for `uint(16)_t`. + * + * @since Always. */ #define PRIX16 __PRI16 "X" @@ -695,6 +823,8 @@ intmax_t (imaxabs)(intmax_t) * uint32_t in uppercase hexadecimal form. * * @etymology `(pri)ntf` `%(X)` for `uint(32)_t`. + * + * @since Always. */ #define PRIX32 __PRI32 "X" @@ -703,6 +833,8 @@ intmax_t (imaxabs)(intmax_t) * uint64_t in uppercase hexadecimal form. * * @etymology `(pri)ntf` `%(X)` for `uint(64)_t`. + * + * @since Always. */ #define PRIX64 __PRI64 "X" @@ -712,6 +844,8 @@ intmax_t (imaxabs)(intmax_t) * uint_least8_t in uppercase hexadecimal form. * * @etymology `(pri)ntf` `%(X)` for `uint_(least8)_t`. + * + * @since Always. */ #define PRIXLEAST8 PRIX8 @@ -720,6 +854,8 @@ intmax_t (imaxabs)(intmax_t) * uint_least16_t in uppercase hexadecimal form. * * @etymology `(pri)ntf` `%(X)` for `uint_(least16)_t`. + * + * @since Always. */ #define PRIXLEAST16 PRIX16 @@ -728,6 +864,8 @@ intmax_t (imaxabs)(intmax_t) * uint_least32_t in uppercase hexadecimal form. * * @etymology `(pri)ntf` `%(X)` for `uint_(least32)_t`. + * + * @since Always. */ #define PRIXLEAST32 PRIX32 @@ -736,6 +874,8 @@ intmax_t (imaxabs)(intmax_t) * uint_least64_t in uppercase hexadecimal form. * * @etymology `(pri)ntf` `%(X)` for `uint_(least64)_t`. + * + * @since Always. */ #define PRIXLEAST64 PRIX64 @@ -745,6 +885,8 @@ intmax_t (imaxabs)(intmax_t) * uint_fast8_t in uppercase hexadecimal form. * * @etymology `(pri)ntf` `%(X)` for `uint_(fast8)_t`. + * + * @since Always. */ #define PRIXFAST8 __PRIFAST8 "X" @@ -753,6 +895,8 @@ intmax_t (imaxabs)(intmax_t) * uint_fast16_t in uppercase hexadecimal form. * * @etymology `(pri)ntf` `%(X)` for `uint_(fast16)_t`. + * + * @since Always. */ #define PRIXFAST16 __PRIFAST16 "X" @@ -761,6 +905,8 @@ intmax_t (imaxabs)(intmax_t) * uint_fast32_t in uppercase hexadecimal form. * * @etymology `(pri)ntf` `%(X)` for `uint_(fast32)_t`. + * + * @since Always. */ #define PRIXFAST32 __PRIFAST32 "X" @@ -769,6 +915,8 @@ intmax_t (imaxabs)(intmax_t) * uint_fast64_t in uppercase hexadecimal form. * * @etymology `(pri)ntf` `%(X)` for `uint_(fast64)_t`. + * + * @since Always. */ #define PRIXFAST64 __PRIFAST64 "X" @@ -779,6 +927,8 @@ intmax_t (imaxabs)(intmax_t) * intmax_t in decimal form. * * @etymology `(pri)ntf` `%(d)` for `int(max)_t`. + * + * @since Always. */ #define PRIdMAX __PRIMAX "d" @@ -787,6 +937,8 @@ intmax_t (imaxabs)(intmax_t) * intmax_t in decimal form. * * @etymology `(pri)ntf` `%(i)` for `int(max)_t`. + * + * @since Always. */ #define PRIiMAX __PRIMAX "i" @@ -795,6 +947,8 @@ intmax_t (imaxabs)(intmax_t) * uintmax_t in octal form. * * @etymology `(pri)ntf` `%(o)` for `uint(max)_t`. + * + * @since Always. */ #define PRIoMAX __PRIMAX "o" @@ -803,6 +957,8 @@ intmax_t (imaxabs)(intmax_t) * uintmax_t in decimal form. * * @etymology `(pri)ntf` `%(u)` for `uint(max)_t`. + * + * @since Always. */ #define PRIuMAX __PRIMAX "u" @@ -811,6 +967,8 @@ intmax_t (imaxabs)(intmax_t) * uintmax_t in lowercase hexadecimal form. * * @etymology `(pri)ntf` `%(x)` for `uint(max)_t`. + * + * @since Always. */ #define PRIxMAX __PRIMAX "x" @@ -819,6 +977,8 @@ intmax_t (imaxabs)(intmax_t) * uintmax_t in uppercase hexadecimal form. * * @etymology `(pri)ntf` `%(X)` for `uint(max)_t`. + * + * @since Always. */ #define PRIXMAX __PRIMAX "X" @@ -830,6 +990,8 @@ intmax_t (imaxabs)(intmax_t) * in decimal form. * * @etymology `(pri)ntf` `%(d)` for `int(ptr)_t` and alike. + * + * @since Always. */ #define PRIdPTR __PRIPTR "d" @@ -839,6 +1001,8 @@ intmax_t (imaxabs)(intmax_t) * in decimal form. * * @etymology `(pri)ntf` `%(i)` for `int(ptr)_t` and alike. + * + * @since Always. */ #define PRIiPTR __PRIPTR "i" @@ -848,6 +1012,8 @@ intmax_t (imaxabs)(intmax_t) * in octal form. * * @etymology `(pri)ntf` `%(o)` for `uint(ptr)_t` and alike. + * + * @since Always. */ #define PRIoPTR __PRIPTR "o" @@ -857,6 +1023,8 @@ intmax_t (imaxabs)(intmax_t) * in decimal form. * * @etymology `(pri)ntf` `%(u)` for `uint(ptr)_t` and alike. + * + * @since Always. */ #define PRIuPTR __PRIPTR "u" @@ -866,6 +1034,8 @@ intmax_t (imaxabs)(intmax_t) * in lowercase hexadecimal form. * * @etymology `(pri)ntf` `%(x)` for `uint(ptr)_t` and alike. + * + * @since Always. */ #define PRIxPTR __PRIPTR "x" @@ -875,6 +1045,8 @@ intmax_t (imaxabs)(intmax_t) * in uppercase hexadecimal form. * * @etymology `(pri)ntf` `%(X)` for `uint(ptr)_t` and alike. + * + * @since Always. */ #define PRIXPTR __PRIPTR "X" @@ -888,6 +1060,8 @@ intmax_t (imaxabs)(intmax_t) * an int8_t from decimal form. * * @etymology `(sc)a(n)f` `%(d)` for `int(8)_t`. + * + * @since Always. */ #define SCNd8 __SCN8 "d" @@ -896,6 +1070,8 @@ intmax_t (imaxabs)(intmax_t) * an int16_t from decimal form. * * @etymology `(sc)a(n)f` `%(d)` for `int(16)_t`. + * + * @since Always. */ #define SCNd16 __SCN16 "d" @@ -904,6 +1080,8 @@ intmax_t (imaxabs)(intmax_t) * an int32_t from decimal form. * * @etymology `(sc)a(n)f` `%(d)` for `int(32)_t`. + * + * @since Always. */ #define SCNd32 __SCN32 "d" @@ -912,6 +1090,8 @@ intmax_t (imaxabs)(intmax_t) * an int64_t from decimal form. * * @etymology `(sc)a(n)f` `%(d)` for `int(64)_t`. + * + * @since Always. */ #define SCNd64 __SCN64 "d" @@ -921,6 +1101,8 @@ intmax_t (imaxabs)(intmax_t) * an int_least8_t from decimal form. * * @etymology `(sc)a(n)f` `%(d)` for `int_(least8)_t`. + * + * @since Always. */ #define SCNdLEAST8 SCNd8 @@ -929,6 +1111,8 @@ intmax_t (imaxabs)(intmax_t) * an int_least16_t from decimal form. * * @etymology `(sc)a(n)f` `%(d)` for `int_(least16)_t`. + * + * @since Always. */ #define SCNdLEAST16 SCNd16 @@ -937,6 +1121,8 @@ intmax_t (imaxabs)(intmax_t) * an int_least32_t from decimal form. * * @etymology `(sc)a(n)f` `%(d)` for `int_(least32)_t`. + * + * @since Always. */ #define SCNdLEAST32 SCNd32 @@ -945,6 +1131,8 @@ intmax_t (imaxabs)(intmax_t) * an int_least64_t from decimal form. * * @etymology `(sc)a(n)f` `%(d)` for `int_(least64)_t`. + * + * @since Always. */ #define SCNdLEAST64 SCNd64 @@ -954,6 +1142,8 @@ intmax_t (imaxabs)(intmax_t) * an int_fast8_t from decimal form. * * @etymology `(sc)a(n)f` `%(d)` for `int_(fast8)_t`. + * + * @since Always. */ #define SCNdFAST8 __SCNFAST8 "d" @@ -962,6 +1152,8 @@ intmax_t (imaxabs)(intmax_t) * an int_fast16_t from decimal form. * * @etymology `(sc)a(n)f` `%(d)` for `int_(fast16)_t`. + * + * @since Always. */ #define SCNdFAST16 __SCNFAST16 "d" @@ -970,6 +1162,8 @@ intmax_t (imaxabs)(intmax_t) * an int_fast32_t from decimal form. * * @etymology `(sc)a(n)f` `%(d)` for `int_(fast32)_t`. + * + * @since Always. */ #define SCNdFAST32 __SCNFAST32 "d" @@ -978,6 +1172,8 @@ intmax_t (imaxabs)(intmax_t) * an int_fast64_t from decimal form. * * @etymology `(sc)a(n)f` `%(d)` for `int_(fast64)_t`. + * + * @since Always. */ #define SCNdFAST64 __SCNFAST64 "d" @@ -988,6 +1184,8 @@ intmax_t (imaxabs)(intmax_t) * an int8_t from decimal form. * * @etymology `(sc)a(n)f` `%(i)` for `int(8)_t`. + * + * @since Always. */ #define SCNi8 __SCN8 "i" @@ -996,6 +1194,8 @@ intmax_t (imaxabs)(intmax_t) * an int16_t from decimal form. * * @etymology `(sc)a(n)f` `%(i)` for `int(16)_t`. + * + * @since Always. */ #define SCNi16 __SCN16 "i" @@ -1004,6 +1204,8 @@ intmax_t (imaxabs)(intmax_t) * an int32_t from decimal form. * * @etymology `(sc)a(n)f` `%(i)` for `int(32)_t`. + * + * @since Always. */ #define SCNi32 __SCN32 "i" @@ -1012,6 +1214,8 @@ intmax_t (imaxabs)(intmax_t) * an int64_t from decimal form. * * @etymology `(sc)a(n)f` `%(i)` for `int(64)_t`. + * + * @since Always. */ #define SCNi64 __SCN64 "i" @@ -1021,6 +1225,8 @@ intmax_t (imaxabs)(intmax_t) * an int_least8_t from decimal form. * * @etymology `(sc)a(n)f` `%(i)` for `int_(least8)_t`. + * + * @since Always. */ #define SCNiLEAST8 SCNi8 @@ -1029,6 +1235,8 @@ intmax_t (imaxabs)(intmax_t) * an int_least16_t from decimal form. * * @etymology `(sc)a(n)f` `%(i)` for `int_(least16)_t`. + * + * @since Always. */ #define SCNiLEAST16 SCNi16 @@ -1037,6 +1245,8 @@ intmax_t (imaxabs)(intmax_t) * an int_least32_t from decimal form. * * @etymology `(sc)a(n)f` `%(i)` for `int_(least32)_t`. + * + * @since Always. */ #define SCNiLEAST32 SCNi32 @@ -1045,6 +1255,8 @@ intmax_t (imaxabs)(intmax_t) * an int_least64_t from decimal form. * * @etymology `(sc)a(n)f` `%(i)` for `int_(least64)_t`. + * + * @since Always. */ #define SCNiLEAST64 SCNi64 @@ -1054,6 +1266,8 @@ intmax_t (imaxabs)(intmax_t) * an int_fast8_t from decimal form. * * @etymology `(sc)a(n)f` `%(i)` for `int_(fast8)_t`. + * + * @since Always. */ #define SCNiFAST8 __SCNFAST8 "i" @@ -1062,6 +1276,8 @@ intmax_t (imaxabs)(intmax_t) * an int_fast16_t from decimal form. * * @etymology `(sc)a(n)f` `%(i)` for `int_(fast16)_t`. + * + * @since Always. */ #define SCNiFAST16 __SCNFAST16 "i" @@ -1070,6 +1286,8 @@ intmax_t (imaxabs)(intmax_t) * an int_fast32_t from decimal form. * * @etymology `(sc)a(n)f` `%(i)` for `int_(fast32)_t`. + * + * @since Always. */ #define SCNiFAST32 __SCNFAST32 "i" @@ -1078,6 +1296,8 @@ intmax_t (imaxabs)(intmax_t) * an int_fast64_t from decimal form. * * @etymology `(sc)a(n)f` `%(i)` for `int_(fast64)_t`. + * + * @since Always. */ #define SCNiFAST64 __SCNFAST64 "i" @@ -1088,6 +1308,8 @@ intmax_t (imaxabs)(intmax_t) * an uint8_t from octal form. * * @etymology `(sc)a(n)f` `%(o)` for `uint(8)_t`. + * + * @since Always. */ #define SCNo8 __SCN8 "o" @@ -1096,6 +1318,8 @@ intmax_t (imaxabs)(intmax_t) * an uint16_t from octal form. * * @etymology `(sc)a(n)f` `%(o)` for `uint(16)_t`. + * + * @since Always. */ #define SCNo16 __SCN16 "o" @@ -1104,6 +1328,8 @@ intmax_t (imaxabs)(intmax_t) * an uint32_t from octal form. * * @etymology `(sc)a(n)f` `%(o)` for `uint(32)_t`. + * + * @since Always. */ #define SCNo32 __SCN32 "o" @@ -1112,6 +1338,8 @@ intmax_t (imaxabs)(intmax_t) * an uint64_t from octal form. * * @etymology `(sc)a(n)f` `%(o)` for `uint(64)_t`. + * + * @since Always. */ #define SCNo64 __SCN64 "o" @@ -1121,6 +1349,8 @@ intmax_t (imaxabs)(intmax_t) * an uint_least8_t from octal form. * * @etymology `(sc)a(n)f` `%(o)` for `uint_(least8)_t`. + * + * @since Always. */ #define SCNoLEAST8 SCNo8 @@ -1129,6 +1359,8 @@ intmax_t (imaxabs)(intmax_t) * an uint_least16_t from octal form. * * @etymology `(sc)a(n)f` `%(o)` for `uint_(least16)_t`. + * + * @since Always. */ #define SCNoLEAST16 SCNo16 @@ -1137,6 +1369,8 @@ intmax_t (imaxabs)(intmax_t) * an uint_least32_t from octal form. * * @etymology `(sc)a(n)f` `%(o)` for `uint_(least32)_t`. + * + * @since Always. */ #define SCNoLEAST32 SCNo32 @@ -1145,6 +1379,8 @@ intmax_t (imaxabs)(intmax_t) * an uint_least64_t from octal form. * * @etymology `(sc)a(n)f` `%(o)` for `uint_(least64)_t`. + * + * @since Always. */ #define SCNoLEAST64 SCNo64 @@ -1154,6 +1390,8 @@ intmax_t (imaxabs)(intmax_t) * an uint_fast8_t from octal form. * * @etymology `(sc)a(n)f` `%(o)` for `uint_(fast8)_t`. + * + * @since Always. */ #define SCNoFAST8 __SCNFAST8 "o" @@ -1162,6 +1400,8 @@ intmax_t (imaxabs)(intmax_t) * an uint_fast16_t from octal form. * * @etymology `(sc)a(n)f` `%(o)` for `uint_(fast16)_t`. + * + * @since Always. */ #define SCNoFAST16 __SCNFAST16 "o" @@ -1170,6 +1410,8 @@ intmax_t (imaxabs)(intmax_t) * an uint_fast32_t from octal form. * * @etymology `(sc)a(n)f` `%(o)` for `uint_(fast32)_t`. + * + * @since Always. */ #define SCNoFAST32 __SCNFAST32 "o" @@ -1178,6 +1420,8 @@ intmax_t (imaxabs)(intmax_t) * an uint_fast64_t from octal form. * * @etymology `(sc)a(n)f` `%(o)` for `uint_(fast64)_t`. + * + * @since Always. */ #define SCNoFAST64 __SCNFAST64 "o" @@ -1188,6 +1432,8 @@ intmax_t (imaxabs)(intmax_t) * an uint8_t from decimal form. * * @etymology `(sc)a(n)f` `%(u)` for `uint(8)_t`. + * + * @since Always. */ #define SCNu8 __SCN8 "u" @@ -1196,6 +1442,8 @@ intmax_t (imaxabs)(intmax_t) * an uint16_t from decimal form. * * @etymology `(sc)a(n)f` `%(u)` for `uint(16)_t`. + * + * @since Always. */ #define SCNu16 __SCN16 "u" @@ -1204,6 +1452,8 @@ intmax_t (imaxabs)(intmax_t) * an uint32_t from decimal form. * * @etymology `(sc)a(n)f` `%(u)` for `uint(32)_t`. + * + * @since Always. */ #define SCNu32 __SCN32 "u" @@ -1212,6 +1462,8 @@ intmax_t (imaxabs)(intmax_t) * an uint64_t from decimal form. * * @etymology `(sc)a(n)f` `%(u)` for `uint(64)_t`. + * + * @since Always. */ #define SCNu64 __SCN64 "u" @@ -1221,6 +1473,8 @@ intmax_t (imaxabs)(intmax_t) * an uint_least8_t from decimal form. * * @etymology `(sc)a(n)f` `%(u)` for `uint_(least8)_t`. + * + * @since Always. */ #define SCNuLEAST8 SCNu8 @@ -1229,6 +1483,8 @@ intmax_t (imaxabs)(intmax_t) * an uint_least16_t from decimal form. * * @etymology `(sc)a(n)f` `%(u)` for `uint_(least16)_t`. + * + * @since Always. */ #define SCNuLEAST16 SCNu16 @@ -1237,6 +1493,8 @@ intmax_t (imaxabs)(intmax_t) * an uint_least32_t from decimal form. * * @etymology `(sc)a(n)f` `%(u)` for `uint_(least32)_t`. + * + * @since Always. */ #define SCNuLEAST32 SCNu32 @@ -1245,6 +1503,8 @@ intmax_t (imaxabs)(intmax_t) * an uint_least64_t from decimal form. * * @etymology `(sc)a(n)f` `%(u)` for `uint_(least64)_t`. + * + * @since Always. */ #define SCNuLEAST64 SCNu64 @@ -1254,6 +1514,8 @@ intmax_t (imaxabs)(intmax_t) * an uint_fast8_t from decimal form. * * @etymology `(sc)a(n)f` `%(u)` for `uint_(fast8)_t`. + * + * @since Always. */ #define SCNuFAST8 __SCNFAST8 "u" @@ -1262,6 +1524,8 @@ intmax_t (imaxabs)(intmax_t) * an uint_fast16_t from decimal form. * * @etymology `(sc)a(n)f` `%(u)` for `uint_(fast16)_t`. + * + * @since Always. */ #define SCNuFAST16 __SCNFAST16 "u" @@ -1270,6 +1534,8 @@ intmax_t (imaxabs)(intmax_t) * an uint_fast32_t from decimal form. * * @etymology `(sc)a(n)f` `%(u)` for `uint_(fast32)_t`. + * + * @since Always. */ #define SCNuFAST32 __SCNFAST32 "u" @@ -1278,6 +1544,8 @@ intmax_t (imaxabs)(intmax_t) * an uint_fast64_t from decimal form. * * @etymology `(sc)a(n)f` `%(u)` for `uint_(fast64)_t`. + * + * @since Always. */ #define SCNuFAST64 __SCNFAST64 "u" @@ -1288,6 +1556,8 @@ intmax_t (imaxabs)(intmax_t) * uint8_t from hexadecimal form. * * @etymology `(sc)a(n)f` `%(x)` for `uint(8)_t`. + * + * @since Always. */ #define SCNx8 __SCN8 "x" @@ -1296,6 +1566,8 @@ intmax_t (imaxabs)(intmax_t) * uint16_t from hexadecimal form. * * @etymology `(sc)a(n)f` `%(x)` for `uint(16)_t`. + * + * @since Always. */ #define SCNx16 __SCN16 "x" @@ -1304,6 +1576,8 @@ intmax_t (imaxabs)(intmax_t) * uint32_t from hexadecimal form. * * @etymology `(sc)a(n)f` `%(x)` for `uint(32)_t`. + * + * @since Always. */ #define SCNx32 __SCN32 "x" @@ -1312,6 +1586,8 @@ intmax_t (imaxabs)(intmax_t) * uint64_t from hexadecimal form. * * @etymology `(sc)a(n)f` `%(x)` for `uint(64)_t`. + * + * @since Always. */ #define SCNx64 __SCN64 "x" @@ -1321,6 +1597,8 @@ intmax_t (imaxabs)(intmax_t) * uint_least8_t from hexadecimal form. * * @etymology `(sc)a(n)f` `%(x)` for `uint_(least8)_t`. + * + * @since Always. */ #define SCNxLEAST8 SCNx8 @@ -1329,6 +1607,8 @@ intmax_t (imaxabs)(intmax_t) * uint_least16_t from hexadecimal form. * * @etymology `(sc)a(n)f` `%(x)` for `uint_(least16)_t`. + * + * @since Always. */ #define SCNxLEAST16 SCNx16 @@ -1337,6 +1617,8 @@ intmax_t (imaxabs)(intmax_t) * uint_least32_t from hexadecimal form. * * @etymology `(sc)a(n)f` `%(x)` for `uint_(least32)_t`. + * + * @since Always. */ #define SCNxLEAST32 SCNx32 @@ -1345,6 +1627,8 @@ intmax_t (imaxabs)(intmax_t) * uint_least64_t from hexadecimal form. * * @etymology `(sc)a(n)f` `%(x)` for `uint_(least64)_t`. + * + * @since Always. */ #define SCNxLEAST64 SCNx64 @@ -1354,6 +1638,8 @@ intmax_t (imaxabs)(intmax_t) * uint_fast8_t from hexadecimal form. * * @etymology `(sc)a(n)f` `%(x)` for `uint_(fast8)_t`. + * + * @since Always. */ #define SCNxFAST8 __SCNFAST8 "x" @@ -1362,6 +1648,8 @@ intmax_t (imaxabs)(intmax_t) * uint_fast16_t from hexadecimal form. * * @etymology `(sc)a(n)f` `%(x)` for `uint_(fast16)_t`. + * + * @since Always. */ #define SCNxFAST16 __SCNFAST16 "x" @@ -1370,6 +1658,8 @@ intmax_t (imaxabs)(intmax_t) * uint_fast32_t from hexadecimal form. * * @etymology `(sc)a(n)f` `%(x)` for `uint_(fast32)_t`. + * + * @since Always. */ #define SCNxFAST32 __SCNFAST32 "x" @@ -1378,6 +1668,8 @@ intmax_t (imaxabs)(intmax_t) * uint_fast64_t from hexadecimal form. * * @etymology `(sc)a(n)f` `%(x)` for `uint_(fast64)_t`. + * + * @since Always. */ #define SCNxFAST64 __SCNFAST64 "x" @@ -1388,6 +1680,8 @@ intmax_t (imaxabs)(intmax_t) * intmax_t from decimal form. * * @etymology `(sc)a(n)f` `%(d)` for `int(max)_t`. + * + * @since Always. */ #define SCNdMAX __SCNMAX "d" @@ -1396,6 +1690,8 @@ intmax_t (imaxabs)(intmax_t) * intmax_t from decimal form. * * @etymology `(sc)a(n)f` `%(i)` for `int(max)_t`. + * + * @since Always. */ #define SCNiMAX __SCNMAX "i" @@ -1404,6 +1700,8 @@ intmax_t (imaxabs)(intmax_t) * uintmax_t from octal form. * * @etymology `(sc)a(n)f` `%(o)` for `uint(max)_t`. + * + * @since Always. */ #define SCNoMAX __SCNMAX "o" @@ -1412,6 +1710,8 @@ intmax_t (imaxabs)(intmax_t) * uintmax_t from decimal form. * * @etymology `(sc)a(n)f` `%(u)` for `uint(max)_t`. + * + * @since Always. */ #define SCNuMAX __SCNMAX "u" @@ -1420,6 +1720,8 @@ intmax_t (imaxabs)(intmax_t) * uintmax_t from hexadecimal form. * * @etymology `(sc)a(n)f` `%(x)` for `uint(max)_t`. + * + * @since Always. */ #define SCNxMAX __SCNMAX "x" @@ -1431,6 +1733,8 @@ intmax_t (imaxabs)(intmax_t) * from decimal form. * * @etymology `(sc)a(n)f` `%(d)` for `int(ptr)_t` and alike. + * + * @since Always. */ #define SCNdPTR __SCNPTR "d" @@ -1440,6 +1744,8 @@ intmax_t (imaxabs)(intmax_t) * from decimal form. * * @etymology `(sc)a(n)f` `%(i)` for `int(ptr)_t` and alike. + * + * @since Always. */ #define SCNiPTR __SCNPTR "i" @@ -1449,6 +1755,8 @@ intmax_t (imaxabs)(intmax_t) * from octal form. * * @etymology `(sc)a(n)f` `%(o)` for `uint(ptr)_t` and alike. + * + * @since Always. */ #define SCNoPTR __SCNPTR "o" @@ -1458,6 +1766,8 @@ intmax_t (imaxabs)(intmax_t) * from decimal form. * * @etymology `(sc)a(n)f` `%(u)` for `uint(ptr)_t` and alike. + * + * @since Always. */ #define SCNuPTR __SCNPTR "u" @@ -1467,6 +1777,8 @@ intmax_t (imaxabs)(intmax_t) * from hexadecimal form. * * @etymology `(sc)a(n)f` `%(x)` for `uint(ptr)_t` and alike. + * + * @since Always. */ #define SCNxPTR __SCNPTR "x" diff --git a/include/iso646.h b/include/iso646.h index 51edb6a..67ea99b 100644 --- a/include/iso646.h +++ b/include/iso646.h @@ -35,56 +35,78 @@ /** * Alias for logical and (&&). + * + * @since Always. */ #define and && /** * Alias for bitwise and assignement (&=). + * + * @since Always. */ #define and_eq &= /** * Alias for bitwise and (&). + * + * @since Always. */ #define bitand & /** * Alias for bitwise inclusive or (|). + * + * @since Always. */ #define bitor | /** * Alias for bitwise complement (~). + * + * @since Always. */ #define compl ~ /** * Alias for logical complement (!). + * + * @since Always. */ #define not ! /** * Alias for inequality comparer (!=). + * + * @since Always. */ #define not_eq != /** * Alias for logical inclusive (||). + * + * @since Always. */ #define or || /** * Alias for bitwise inclusive or assignment (|=). + * + * @since Always. */ #define or_eq |= /** * Alias for bitwise exclusive or (^). + * + * @since Always. */ #define xor ^ /** * Alias for bitwise exclusive or assignment (^=). + * + * @since Always. */ #define xor_eq ^= diff --git a/include/libgen.h b/include/libgen.h index 8f6b884..a62bd41 100644 --- a/include/libgen.h +++ b/include/libgen.h @@ -39,6 +39,8 @@ * of `filename` or, if `filename` is `NULL` * or is empty, a statically allocationed string, * so it must not freed or edited. + * + * @since Always. */ char* __xpg_basename(char*) __GCC_ONLY(__attribute__((__warn_unused_result__))); @@ -55,6 +57,8 @@ char* __xpg_basename(char*) * or does no contain a non-trailing slash, * a statically allocationed string, so it * must not freed or edited. + * + * @since Always. */ char* dirname(char*) __GCC_ONLY(__attribute__((__warn_unused_result__))); @@ -82,6 +86,8 @@ char* dirname(char*) * if `filename` is `NULL` or does no contain a * non-trailing slash, a statically allocationed * string, so it must not freed or edited. + * + * @since Always. */ char* cleanname(char*) #endif diff --git a/include/malloc.h b/include/malloc.h index 6410ad0..578a765 100644 --- a/include/malloc.h +++ b/include/malloc.h @@ -51,6 +51,8 @@ * indicate the error. * * @throws ENOMEM The process cannot allocate more memory. + * + * @since Always. */ void* malloc(size_t) __GCC_ONLY(__attribute__((__malloc__, __warn_unused_result__))); @@ -73,6 +75,8 @@ void* malloc(size_t) * `errno` is set to indicate the error. * * @throws ENOMEM The process cannot allocate more memory. + * + * @since Always. */ void* calloc(size_t, size_t) __GCC_ONLY(__attribute__((__malloc__, __warn_unused_result__))); @@ -99,6 +103,8 @@ void* calloc(size_t, size_t) * indicate the error. * * @throws ENOMEM The process cannot allocate more memory. + * + * @since Always. */ void* mallocz(size_t, int) __GCC_ONLY(__attribute__((__malloc__, __warn_unused_result__))); @@ -125,6 +131,8 @@ void* mallocz(size_t, int) * indicate the error. * * @throws ENOMEM The process cannot allocate more memory. + * + * @since Always. */ void* zalloc(size_t) __warning("'zalloc' is klibc extension, use 'calloc(1, n)' instead of 'zalloc(n)'.") @@ -154,6 +162,8 @@ void* zalloc(size_t) * is returned and `errno` is set to indicate the error. * * @throws ENOMEM The process cannot allocate more memory. + * + * @since Always. */ void* realloc(void*, size_t) __GCC_ONLY(__attribute__((__warn_unused_result__))) @@ -168,6 +178,8 @@ void* realloc(void*, size_t) * The process may crash if it does not point to the * beginning of a memory allocation on the heap. * However, if it is `NULL`, nothing will happen. + * + * @since Always. */ void free(void*) __slibc_warning("Use 'fast_free' or 'secure_free' instead."); @@ -183,6 +195,8 @@ void free(void*) * The process may crash if it does not point to the * beginning of a memory allocation on the heap. * However, if it is `NULL`, nothing will happen. + * + * @since Always. */ #if !defined(__PORTABLE) void cfree(void*, ...) @@ -214,6 +228,8 @@ void cfree(void*, ...) * * @throws ENOMEM The process cannot allocate more memory. * @throws EINVAL If `boundary` is not a power of two. + * + * @since Always. */ void* memalign(size_t, size_t) #ifdef __C11__ @@ -240,6 +256,8 @@ void* memalign(size_t, size_t) * * @throws ENOMEM The process cannot allocate more memory. * @throws EINVAL If `boundary` is not a power-of-two multiple of `sizeof(void*)`. + * + * @since Always. */ int posix_memalign(void**, size_t, size_t) __GCC_ONLY(__attribute__((__nonnull__))); @@ -263,6 +281,8 @@ int posix_memalign(void**, size_t, size_t) * indicate the error. * * @throws ENOMEM The process cannot allocate more memory. + * + * @since Always. */ void* valloc(size_t) __GCC_ONLY(__attribute__((__malloc__, __warn_unused_result__))) @@ -285,6 +305,8 @@ void* valloc(size_t) * indicate the error. * * @throws ENOMEM The process cannot allocate more memory. + * + * @since Always. */ void* pvalloc(size_t) __GCC_ONLY(__attribute__((__malloc__, __warn_unused_result__))) @@ -315,6 +337,8 @@ void* pvalloc(size_t) * * @throws ENOMEM The process cannot allocate more memory. * @throws EINVAL If `boundary` is not a power of two. + * + * @since Always. */ void* aligned_alloc(size_t, size_t) __GCC_ONLY(__attribute__((__malloc__, __warn_unused_result__))); @@ -332,6 +356,8 @@ void* aligned_alloc(size_t, size_t) * * @param segment The memory segment. * @return The size of the memory segment, 0 if `segment` is `NULL`. + * + * @since Always. */ size_t malloc_usable_size(void*) __GCC_ONLY(__attribute__((__warn_unused_result__))); diff --git a/include/slibc-alloc.h b/include/slibc-alloc.h index 7a697d1..043616a 100644 --- a/include/slibc-alloc.h +++ b/include/slibc-alloc.h @@ -32,16 +32,22 @@ * They are independent of each other, and * multiple can be selected by using bitwise or * between them. + * + * @since Always. */ enum extalloc_mode { /** * Clear disowned memory. + * + * @since Always. */ EXTALLOC_CLEAR = 1, /** * Create new allocation with `malloc` if necessary. + * + * @since Always. */ EXTALLOC_MALLOC = 2, @@ -53,22 +59,30 @@ enum extalloc_mode * They are independent of each other, and * multiple can be selected by using bitwise or * between them. + * + * @since Always. */ enum rememalign_mode { /** * Clear disowned memory. + * + * @since Always. */ REMEMALIGN_CLEAR = 1, /** * Initialise new memory. + * + * @since Always. */ REMEMALIGN_INIT = 2, /** * If a new allocation is created, copy the data * from the old allocation over to the new allocation. + * + * @since Always. */ REMEMALIGN_MEMCPY = 4, @@ -80,22 +94,30 @@ enum rememalign_mode * They are independent of each other, and * multiple can be selected by using bitwise or * between them. + * + * @since Always. */ enum falloc_mode { /** * Clear disowned memory. + * + * @since Always. */ FALLOC_CLEAR = 1, /** * Initialise new memory. + * + * @since Always. */ FALLOC_INIT = 2, /** * If a new allocation is created, copy the data * from the old allocation over to the new allocation. + * + * @since Always. */ FALLOC_MEMCPY = 4, @@ -109,6 +131,8 @@ enum falloc_mode * @etymology (Fast) variant of (`free`). * * @param segment The memory segment to free. + * + * @since Always. */ void fast_free(void*); @@ -119,6 +143,8 @@ void fast_free(void*); * @etymology (Secure) variant of (`free`). * * @param segment The memory segment to free. + * + * @since Always. */ void secure_free(void*); @@ -144,6 +170,8 @@ void secure_free(void*); * implemented in slibc. It is however not guaranteed * that this will happen, undefined behaviour may be * invoked instead. + * + * @since Always. */ size_t allocsize(void*) __GCC_ONLY(__attribute__((__warn_unused_result__))); @@ -161,6 +189,8 @@ size_t allocsize(void*) * @return The new allocation, see `realloc` for more details. * * @throws ENOMEM The process cannot allocate more memory. + * + * @since Always. */ void* crealloc(void*, size_t) __GCC_ONLY(__attribute__((__warn_unused_result__))); @@ -176,6 +206,8 @@ void* crealloc(void*, size_t) * @return The new allocation, see `realloc` for more details. * * @throws ENOMEM The process cannot allocate more memory. + * + * @since Always. */ void* fast_realloc(void*, size_t) __GCC_ONLY(__attribute__((__warn_unused_result__))); @@ -191,6 +223,8 @@ void* fast_realloc(void*, size_t) * @return The new allocation, see `realloc` for more details. * * @throws ENOMEM The process cannot allocate more memory. + * + * @since Always. */ void* secure_realloc(void*, size_t) __GCC_ONLY(__attribute__((__warn_unused_result__))); @@ -218,6 +252,8 @@ void* secure_realloc(void*, size_t) * @return The new allocation, see `realloc` for more details. * * @throws ENOMEM The process cannot allocate more memory. + * + * @since Always. */ void* custom_realloc(void*, size_t, int, int, int) __GCC_ONLY(__attribute__((__warn_unused_result__))); @@ -246,6 +282,8 @@ void* custom_realloc(void*, size_t, int, int, int) * * @throws 0 `errno` is set to zero success if `NULL` is returned. * @throws ENOMEM The process cannot allocate more memory. + * + * @since Always. */ void* extalloc(void*, size_t, enum extalloc_mode) __GCC_ONLY(__attribute__((__nonnull__, __warn_unused_result__))); @@ -266,6 +304,8 @@ void* extalloc(void*, size_t, enum extalloc_mode) * @throws 0 `errno` is set to zero success if `NULL` is returned. * @throws EINVAL `mode` is invalid, or `boundary` is not a power of two. * @throws ENOMEM The process cannot allocate more memory. + * + * @since Always. */ void* rememalign(void*, size_t, size_t, enum rememalign_mode) __GCC_ONLY(__attribute__((__warn_unused_result__))); @@ -290,6 +330,8 @@ void* rememalign(void*, size_t, size_t, enum rememalign_mode) * @return The new allocation, see `realloc` for more details. * * @throws ENOMEM The process cannot allocate more memory. + * + * @since Always. */ void* naive_realloc(void*, size_t, size_t) /* sic! we limit ourself to ASCII */ __GCC_ONLY(__attribute__((__nonnull__, __warn_unused_result__))); @@ -308,6 +350,8 @@ void* naive_realloc(void*, size_t, size_t) /* sic! we limit ourself to ASCII */ * * @throws 0 `malloc` is require to perform the action. * @throws ENOMEM The process cannot allocate more memory. + * + * @since Always. */ void* naive_extalloc(void*, size_t) /* sic! we limit ourself to ASCII */ __GCC_ONLY(__attribute__((__nonnull__, __warn_unused_result__))); @@ -366,6 +410,8 @@ void* naive_extalloc(void*, size_t) /* sic! we limit ourself to ASCII */ * @throws 0 `new_size` is zero. * @throws EINVAL The arguments are invalid. * @throws ENOMEM The process cannot allocate more memory. + * + * @since Always. */ void* falloc(void*, size_t*, size_t, size_t, size_t, enum falloc_mode); @@ -375,6 +421,8 @@ void* falloc(void*, size_t*, size_t, size_t, size_t, enum falloc_mode); * so that another attempt to free the segment will not crash the process. * * @etymology Macro version of (`fast_free`). + * + * @since Always. */ #define FAST_FREE(segment) (fast_free(segment), (void)((segment) = NULL)); @@ -383,6 +431,8 @@ void* falloc(void*, size_t*, size_t, size_t, size_t, enum falloc_mode); * so that another attempt to free the segment will not crash the process. * * @etymology Macro version of (`secure_free`). + * + * @since Always. */ #define SECURE_FREE(segment) (secure_free(segment), (void)((segment) = NULL)); diff --git a/include/slibc-error.h b/include/slibc-error.h index 66d1e50..7e1bca2 100644 --- a/include/slibc-error.h +++ b/include/slibc-error.h @@ -77,6 +77,8 @@ * ``` * * This is a slibc extension. + * + * @since Always. */ #define FAILABLE_CALL(expression) \ ({ typeof(expression) __slibc_r = (expression); *__slibc_error_line() = __LINE__; __slibc_r; }) @@ -123,6 +125,8 @@ * that was the line that failed, if `condition` * evaluates to non-zero. * @return 1 if `condition` evaluates to non-zero, 0 otherwise. + * + * @since Always. */ #define FAILURE_CHECK(condition, offset) \ ((condition) ? (*__slibc_error_line() = (__LINE__ - (offset)), 1) : 0) @@ -168,6 +172,8 @@ * to describe what action failed. If the first argument is * `NULL`, this is not printed and only the location of the * error and `errno` is used to describe the error. + * + * @since Always. */ #define PRINT_FAILURE(...) \ (PRINT_CUSTOM_FAILURE(errno, NULL, __VA_ARGS__)) @@ -191,6 +197,8 @@ * to describe what action failed. If the first argument is * `NULL`, this is not printed and only the location of the * error and `error_string` is used to describe the error. + * + * @since Always. */ #define PRINT_CUSTOM_FAILURE(error_code, error_string, ...) \ (slibc_perror(NULL, __FILE__, *__slibc_error_line(), __func__, &(error_code), error_string, __VA_ARGS__)) @@ -198,6 +206,8 @@ /** * Helper function to keep track of the line of origin, in a * thread-safe manner, without requiring new revisions of C. + * + * @since Always. */ int* __slibc_error_line(void) __GCC_ONLY(__attribute__((__const__))); /* TODO not implemented */ @@ -222,6 +232,8 @@ int* __slibc_error_line(void) __GCC_ONLY(__attribute__((__const__))); /* TODO no * @param format Formatting-string for a description of the action that failed. `NULL` if * no description other than the location and `error_string` should be printed. * @param ... Formatting-arguments for `format`. + * + * @since Always. */ void slibc_perror(const char*, const char*, int, const char*, int*, const char*, const char*, ...) __GCC_ONLY(__attribute__((__nonnull__(2, 4), __format__(__slibc_printf__, 7, 8)))); diff --git a/include/slibc-human.h b/include/slibc-human.h index 9a4e5dc..de505a1 100644 --- a/include/slibc-human.h +++ b/include/slibc-human.h @@ -35,6 +35,8 @@ /** * Representation settings for file permissions. + * + * @since Always. */ enum humanmode_mode { @@ -44,6 +46,8 @@ enum humanmode_mode * * If used in combination with `HUMANMODE_MASK`, * 0750 resolves to 'u=rwx,g=r-x,o=---'. + * + * @since Always. */ HUMANMODE_STAT = 1, @@ -53,6 +57,8 @@ enum humanmode_mode * * If used in combination with `HUMANMODE_STAT`, * 0750 resolves to 'u=rwx,g=r-x,o=---'. + * + * @since Always. */ HUMANMODE_MASK = 2, }; @@ -61,6 +67,8 @@ enum humanmode_mode /** * Representation settings for converting * sizes to human-readable format. + * + * @since Always. */ enum humansize_mode { @@ -69,6 +77,8 @@ enum humansize_mode * * Cannot be combined with `HUMANSIZE_IEC` * or `HUMANSIZE_IEC_EXPLICIT`. + * + * @since Always. */ HUMANSIZE_SI = 1, @@ -77,6 +87,8 @@ enum humansize_mode * * Cannot be combined with `HUMANSIZE_SI` * or `HUMANSIZE_IEC_EXPLICIT`. + * + * @since Always. */ HUMANSIZE_IEC = 2, @@ -85,12 +97,16 @@ enum humansize_mode * * Cannot be combined with `HUMANSIZE_SI` * or `HUMANSIZE_IEC`. + * + * @since Always. */ HUMANSIZE_IEC_EXPLICIT = 4, /** * 'B' is only included if there is no prefix. + * + * @since Always. */ HUMANSIZE_PREFIX_ONLY = 8, @@ -103,6 +119,8 @@ enum humansize_mode * and `detail == 3` may yeild '3TB 2MB' for the same size. * * Cannot be combined with `HUMANSIZE_ROUND`. + * + * @since Always. */ HUMANSIZE_EXACT = 16, @@ -112,6 +130,8 @@ enum humansize_mode * `detail` < 0 is allowed, * * Cannot be combined with `HUMANSIZE_EXACT`. + * + * @since Always. */ HUMANSIZE_ROUND = 32, }; @@ -120,6 +140,8 @@ enum humansize_mode /** * Settings for treating ambiguous file size * and file offset representations when parsing. + * + * @since Always. */ enum machinesize_mode { @@ -129,6 +151,8 @@ enum machinesize_mode * If `MACHINESIZE_IEC` is also used, * 1000-base is used if 'B' is explicitly * included, otherwise 1024-base is used. + * + * @since Always. */ MACHINESIZE_SI = 1, @@ -138,6 +162,8 @@ enum machinesize_mode * If `MACHINESIZE_SI` is also used, * 1000-base is used if 'B' is explicitly * included, otherwise 1024-base is used. + * + * @since Always. */ MACHINESIZE_IEC = 2, }; @@ -146,6 +172,8 @@ enum machinesize_mode /** * Ways to handled unrecognised escapes, * and other configurations. + * + * @since Always. */ enum unescape_mode { @@ -155,6 +183,8 @@ enum unescape_mode * * Cannot be used together with * `UNESCAPE_VERBATIM` or `UNESCAPE_IGNORE`. + * + * @since Always. */ UNESCAPE_EINVAL = 1, @@ -164,6 +194,8 @@ enum unescape_mode * * Cannot be used together with * `UNESCAPE_EINVAL` or `UNESCAPE_IGNORE`. + * + * @since Always. */ UNESCAPE_VERBATIM = 2, @@ -173,6 +205,8 @@ enum unescape_mode * * Cannot be used together with * `UNESCAPE_EINVAL` or `UNESCAPE_VERBATIM`. + * + * @since Always. */ UNESCAPE_IGNORE = 4, @@ -182,6 +216,8 @@ enum unescape_mode * * If not used, '\&' is handled as an * unsupported escape. + * + * @since Always. */ UNESCAPE_AMPERSAND = 8, @@ -191,6 +227,8 @@ enum unescape_mode * * If not used, '\0' resolves to a * 0 byte (termination). + * + * @since Always. */ UNESCAPE_MOD_UTF8 = 16, }; @@ -212,6 +250,8 @@ enum unescape_mode * * @throws EINVAL If `mode` is invalid. * @throws ENOMEM The process cannot allocate more memory. + * + * @since Always. */ char* humanmode(char* restrict, mode_t, enum humanmode_mode); @@ -231,6 +271,8 @@ char* humanmode(char* restrict, mode_t, enum humanmode_mode); * @return Zero on success, -1 on error. * * @throws EINVAL If `str` is not parseable. + * + * @since Always. */ int machinemode(mode_t* restrict, mode_t* restrict, const char* restrict) __GCC_ONLY(__attributes__((__nonnull__(3)))); @@ -262,6 +304,8 @@ int machinemode(mode_t* restrict, mode_t* restrict, const char* restrict) * @throws EINVAL If `mode` is invalid. * @throws EINVAL If `mode & HUMANSIZE_EXACT` and `detail < 0`. * @throws ENOMEM The process cannot allocate more memory. + * + * @since Always. */ char* humansize(char*, size_t, size_t, enum humansize_mode, int, const char* restrict, const char* restrict, const char* restrict) @@ -269,6 +313,7 @@ char* humansize(char*, size_t, size_t, enum humansize_mode, int, const char* res /* TODO machinesize */ /* @etymology Convert to (machine)-representation: `(size)_t`. */ +/* @since Always. */ int machinesize(size_t* restrict size, const char* restrict str, enum machinesize_mode mode, const char* restrict space, const char* restrict point); @@ -276,17 +321,20 @@ int machinesize(size_t* restrict size, const char* restrict str, enum machinesiz #ifdef __C99__ /* TODO humandur */ /* @etymology Convert to (human)-representation: (dur)ation. */ +/* @since Always. */ int humandur(intmax_t sec, long int nsec, const char* restrict point, const char* restrict format, const char* restrict intraspacing, const char* restrict interspacing); /* TODO machinedur */ /* @etymology Convert to (machine)-representation: (dur)ation. */ +/* @since Always. */ int machinedur(intmax_t* restrict sec, long int* nsec, const char* restrict str, const char* restrict space, const char* restrict point); /* TODO machineint */ /* @etymology Convert to (machine)-representation: signed (int)eger. */ +/* @since Always. */ char* machineint(intmax_t* restrict r, const char* restrict str) __GCC_ONLY(__attribute__((__warn_unused_result__))); # ifdef __CONST_CORRECT @@ -295,6 +343,7 @@ char* machineint(intmax_t* restrict r, const char* restrict str) /* TODO machineuint */ /* @etymology Convert to (machine)-representation: (u)nsigned (int)eger. */ +/* @since Always. */ char* machineuint(uintmax_t* restrict r, const char* restrict str) __GCC_ONLY(__attribute__((__warn_unused_result__))); # ifdef __CONST_CORRECT @@ -304,6 +353,7 @@ char* machineuint(uintmax_t* restrict r, const char* restrict str) /* TODO machinefloat */ /* @etymology Convert to (machine)-representation: (float)ing-point number. */ +/* @since Always. */ int machinefloat(long double* restrict r, const char* restrict str, const char* restrict space, const char* restrict comma); #ifdef __CONST_CORRECT @@ -338,6 +388,8 @@ int machinefloat(long double* restrict r, const char* restrict str, * @throws 0 `str` is `NULL`. * @throws EINVAL If `mode` is invalid. * @throws EINVAL If `str` is invalid and `mode & UNESCAPE_EINVAL`. + * + * @since Always. */ char* unescape(char*, enum unescape_mode); @@ -357,6 +409,8 @@ char* unescape(char*, enum unescape_mode); * @throws 0 `str` is `NULL`. * @throws EINVAL If `quote` is invalid. * @throws ENOMEM The process cannot allocate more memory. + * + * @since Always. */ char* escape(const char* restrict) __GCC_ONLY(__attribute__((__malloc__, __warn_unused_result__))); diff --git a/include/slibc-print.h b/include/slibc-print.h index dc3b90c..194e9cb 100644 --- a/include/slibc-print.h +++ b/include/slibc-print.h @@ -38,17 +38,23 @@ * function is called again. * * @etymology (`generic_printf`)-subsystem: (ext)ension (queue). + * + * @since Always. */ struct generic_printf_ext_queue { /** * Sizes, in bytes, of the missing arguments. * Only 1, 2, 4 and 8 are allowed. + * + * @since Always. */ char sizes[4]; /** * The indices of the missing arguments. + * + * @since Always. */ size_t indices[4]; @@ -60,6 +66,8 @@ struct generic_printf_ext_queue * omitted arguments. To avoid a deadlock, * add arguments in the order of their index * if there are more than 4 missing arguments. + * + * @since Always. */ size_t count; }; @@ -78,6 +86,8 @@ struct generic_printf_ext_queue * `vgeneric_wprintf` via the parameter `data`. * @return Zero on success, -1 on error. `errno` shall * be set on error. + * + * @since Always. */ typedef int (* generic_printf_write_func_t)(const char*, size_t, void*); @@ -86,6 +96,8 @@ typedef int (* generic_printf_write_func_t)(const char*, size_t, void*); * `generic_wprintf` and `vgeneric_wprintf`. * * @etymology (`generic_wprintf`)-subsystem: (write-func)tion, `(t)ypedef`. + * + * @since Always. */ typedef int (* generic_wprintf_write_func_t)(const wchar_t*, size_t, void*); @@ -109,6 +121,8 @@ typedef int (* generic_wprintf_write_func_t)(const wchar_t*, size_t, void*); * value of `argn`, if `queue_data` must be set. * * @throws EINVAL If `code` could not be recognised. + * + * @since Always. */ typedef ssize_t (* generic_printf_ext_func_t)(const char*, intmax_t*, size_t, int, void*, struct generic_printf_ext_queue*); @@ -118,6 +132,8 @@ typedef ssize_t (* generic_printf_ext_func_t)(const char*, intmax_t*, size_t, in * `generic_wprintf` and `vgeneric_wprintf`. * * @etymology (`generic_wprintf`)-subsystem: (ext)ension(-func)tion, `(t)ypedef`. + * + * @since Always. */ typedef ssize_t (* generic_wprintf_ext_func_t)(const wchar_t*, intmax_t*, size_t, int, void*, struct generic_printf_ext_queue*); @@ -150,6 +166,8 @@ typedef ssize_t (* generic_wprintf_ext_func_t)(const wchar_t*, intmax_t*, size_t * * @throws Any error thrown by `write_function` or `extension_function`. * @throws EINVAL `format` contained unsupported formatting codes. + * + * @since Always. */ int generic_printf(generic_printf_write_func_t, generic_printf_ext_func_t, size_t, int, size_t* restrict, int, void*, const char*, ...) @@ -183,6 +201,8 @@ int generic_printf(generic_printf_write_func_t, generic_printf_ext_func_t, * * @throws Any error thrown by `write_function` or `extension_function`. * @throws EINVAL `format` contained unsupported formatting codes. + * + * @since Always. */ int vgeneric_printf(generic_printf_write_func_t, generic_printf_ext_func_t, size_t, int, size_t* restrict, int, void*, const char*, va_list) @@ -216,6 +236,8 @@ int vgeneric_printf(generic_printf_write_func_t, generic_printf_ext_func_t, * * @throws Any error thrown by `write_function` or `extension_function`. * @throws EINVAL `format` contained unsupported formatting codes. + * + * @since Always. */ int generic_wprintf(generic_wprintf_write_func_t, generic_wprintf_ext_func_t, size_t, int, size_t* restrict, int, void*, const wchar_t*, ...) @@ -250,6 +272,8 @@ int generic_wprintf(generic_wprintf_write_func_t, generic_wprintf_ext_func_t, * * @throws Any error thrown by `write_function` or `extension_function`. * @throws EINVAL `format` contained unsupported formatting codes. + * + * @since Always. */ int vgeneric_wprintf(generic_wprintf_write_func_t, generic_wprintf_ext_func_t, size_t, int, size_t* restrict, int, void*, const wchar_t*, va_list) diff --git a/include/slibc/version.h b/include/slibc/version.h index 00eebba..73f0395 100644 --- a/include/slibc/version.h +++ b/include/slibc/version.h @@ -34,24 +34,32 @@ * however `.` is omitted if the patch-number is nought, * `.` is omitted if the both the patch- and micro-number * are nought. + * + * @since Always. */ #define __SLIBC_MAJOR__ 0 /** * The minor-number in the version of slibc that * you are compiling against. + * + * @since Always. */ #define __SLIBC_MINOR__ 1 /** * The micro-number in the version of slibc that * you are compiling against. + * + * @since Always. */ #define __SLIBC_MICRO__ 0 /** * The patch-number in the version of slibc that * you are compiling against. + * + * @since Always. */ #define __SLIBC_PATCH__ 0 @@ -80,6 +88,8 @@ * * You can check if this header is defined to * check whether you are using slibc at all. + * + * @since Always. */ #define __SLIBC__ \ __SLIBC_CONSTRUCT_VERSION(__SLIBC_MAJOR__, __SLIBC_MINOR__, \ @@ -95,6 +105,8 @@ * @param minor The minor-number of the least required version of slibc. * @param micro The micro-number of the least required version of slibc. * @param patch The patch-number of the least required version of slibc. + * + * @since Always. */ #define __SLIBC_REQ_4__(major, minor, micro, patch) \ (__SLIBC__ >= __SLIBC_CONSTRUCT_VERSION(major, minor, micro, patch)) @@ -107,6 +119,8 @@ * @param major The major-number of the least required version of slibc. * @param minor The minor-number of the least required version of slibc. * @param micro The micro-number of the least required version of slibc. + * + * @since Always. */ #define __SLIBC_REQ_3__(major, minor, micro) \ __SLIBC_REQ_4__(major, minor, micro, patch) @@ -118,6 +132,8 @@ * * @param major The major-number of the least required version of slibc. * @param minor The minor-number of the least required version of slibc. + * + * @since Always. */ #define __SLIBC_REQ__(major, minor) \ __SLIBC_REQ_4__(major, minor, 0, 0) diff --git a/include/stdalign.h b/include/stdalign.h index e322a50..9d7d8e9 100644 --- a/include/stdalign.h +++ b/include/stdalign.h @@ -32,6 +32,8 @@ * @etymology (Align as) type. * * @param type The type whose alignment shall be used. + * + * @since Always. */ #if !defined(__C11__) && defined(__GNUC__) # define _Alignas(type) __attribute__((__aligned__(type))) @@ -46,6 +48,8 @@ * * @param type The type. * @return The alignment of the type. + * + * @since Always. */ #if !defined(__C11__) && defined(__GNUC__) # define _Alignof(type) __alignof__(type) diff --git a/include/stdarg.h b/include/stdarg.h index 9012fb6..0f6306d 100644 --- a/include/stdarg.h +++ b/include/stdarg.h @@ -43,6 +43,8 @@ * State of variadic argument-reading. * * @etymology (V)ariadic (a)rguments-subsystem: argument-(list). + * + * @since Always. */ #ifndef __DEFINED_va_list # define __DEFINED_va_list @@ -62,6 +64,8 @@ typedef __builtin_va_list va_list; * * @param state:va_list The state of the variadic argument-reading. * @param last:identifier The the last non-variadic argument. + * + * @since Always. */ #ifndef va_start # ifndef __PORTABLE @@ -77,6 +81,8 @@ typedef __builtin_va_list va_list; * @etymology (V)ariadic (a)rguments-subsystem: (end) of use. * * @param state:va_list The state of the variadic argument-reading. + * + * @since Always. */ #ifndef va_end # ifndef __PORTABLE @@ -97,6 +103,8 @@ typedef __builtin_va_list va_list; * are promoted in the cal, thus you must not use a * type smaller than `int`, lest bad things will happen. * @return :`type` The next argument. + * + * @since Always. */ #ifndef va_arg # define va_arg(state, type) __builtin_va_arg(state, type) @@ -109,6 +117,8 @@ typedef __builtin_va_list va_list; * * @param destination:va_list The copy if `source`. * @param source:va_list The state of the variadic argument-reading. + * + * @since Always. */ #ifndef va_copy # define va_copy(destination, source) __builtin_va_copy(destination, source) diff --git a/include/stdbool.h b/include/stdbool.h index 95f6f2c..531f583 100644 --- a/include/stdbool.h +++ b/include/stdbool.h @@ -36,16 +36,22 @@ * value to be converted to zero. * * @etymology (Bool)ean. + * + * @since Always. */ #define bool _Bool /** * A true value. + * + * @since Always. */ #define true 1 /** * An untrue value. + * + * @since Always. */ #define false 0 @@ -53,6 +59,8 @@ * This macro can be relied on being defined and set to 1 if * has defined the type `bool` (as a macro) and * the constants (macros) `true` and `false`. + * + * @since Always. */ #define __bool_true_false_are_defined 1 diff --git a/include/stddef.h b/include/stddef.h index 0f45c6a..c2a806b 100644 --- a/include/stddef.h +++ b/include/stddef.h @@ -43,6 +43,8 @@ * features, is harmful too. * * @etymology Pointer with numerical value (0). + * + * @since Always. */ #ifndef NULL # define NULL ((void*)0) @@ -72,6 +74,8 @@ * @param member:identifier The identifier for a member, direct or indirect, * of the structure. * @return :size_t The offset of the member. + * + * @since Always. */ #define offsetof(type, member) \ ((size_t)((char*)&(((type*)NULL)->member) - (char*)NULL)) diff --git a/include/stdint.h b/include/stdint.h index 038521f..ab3cd85 100644 --- a/include/stdint.h +++ b/include/stdint.h @@ -42,12 +42,16 @@ /** * Macro that ensure that a signed numeral literal * of at most 8 encoding bits does not overflow. + * + * @since Always. */ # define INT8_C(value) value /** * Macro that ensure that an unsigned numeral literal * of at most 8 encoding bits does not overflow. + * + * @since Always. */ # define UINT8_C(value) value @@ -55,12 +59,16 @@ /** * Macro that ensure that a signed numeral literal * of at most 16 encoding bits does not overflow. + * + * @since Always. */ # define INT16_C(value) value /** * Macro that ensure that an unsigned numeral literal * of at most 16 encoding bits does not overflow. + * + * @since Always. */ # define UINT16_C(value) value ## U @@ -68,6 +76,8 @@ /** * Macro that ensure that a signed numeral literal * of at most 32 encoding bits does not overflow. + * + * @since Always. */ # if __INT_BIT == 16 # define INT32_C(value) value ## L @@ -78,6 +88,8 @@ /** * Macro that ensure that an unsigned numeral literal * of at most 32 encoding bits does not overflow. + * + * @since Always. */ # if __INT_BIT == 16 # define UINT32_C(value) value ## UL @@ -89,6 +101,8 @@ /** * Macro that ensure that a signed numeral literal * of at most 64 encoding bits does not overflow. + * + * @since Always. */ # if __LONG_BIT == 32 # define INT64_C(value) value ## LL @@ -99,6 +113,8 @@ /** * Macro that ensure that an unsigned numeral literal * of at most 64 encoding bits does not overflow. + * + * @since Always. */ # if __LONG_BIT == 32 # define UINT64_C(value) value ## ULL @@ -111,6 +127,8 @@ * Macro that ensure that any signed numeral literal * does not overflow, unless there is no scalar integer * type that can hold it. + * + * @since Always. */ # if __LONG_BIT == __LONG_LONG_BIT # define INTMAX_C(value) value ## L @@ -122,6 +140,8 @@ * Macro that ensure that any unsigned numeral literal * does not overflow, unless there is no scalar integer * type that can hold it. + * + * @since Always. */ # if __LONG_BIT == __LONG_LONG_BIT # define UINTMAX_C(value) value ## UL @@ -133,214 +153,294 @@ /** * Maximum value of `uint8_t`. + * + * @since Always. */ # define UINT8_MAX (UINT8_C(0xFF)) /** * Maximum value of `int8_t`. + * + * @since Always. */ # define INT8_MAX (INT8_C(0x7F)) /** * Minimum value of `int8_t`. + * + * @since Always. */ # define INT8_MIN (-(INT8_MAX) - 1) /** * Maximum value of `uint16_t`. + * + * @since Always. */ # define UINT16_MAX (UINT16_C(0xFFFF)) /** * Maximum value of `int16_t`. + * + * @since Always. */ # define INT16_MAX (INT16_C(0x7FFF)) /** * Minimum value of `int16_t`. + * + * @since Always. */ # define INT16_MIN (-(INT16_MAX) - 1) /** * Maximum value of `uint32_t`. + * + * @since Always. */ # define UINT32_MAX (UINT32_C(0xFFFFFFFF)) /** * Maximum value of `int32_t`. + * + * @since Always. */ # define INT32_MAX (INT32_C(0x7FFFFFFF)) /** * Minimum value of `int32_t`. + * + * @since Always. */ # define INT32_MIN (-(INT32_MAX) - 1) /** * Maximum value of `uint64_t`. + * + * @since Always. */ # define UINT64_MAX (UINT64_C(0xFFFFFFFFFFFFFFFF)) /** * Maximum value of `int64_t`. + * + * @since Always. */ # define INT64_MAX (INT64_C(0x7FFFFFFFFFFFFFFF)) /** * Minimum value of `int64_t`. + * + * @since Always. */ # define INT64_MIN (-(INT64_MAX) - 1) /** * Maximum value of `uint_least8_t`. + * + * @since Always. */ # define UINT_LEAST8_MAX UINT8_MAX /** * Maximum value of `int_least8_t`. + * + * @since Always. */ # define INT_LEAST8_MAX INT8_MAX /** * Minimum value of `int_least8_t`. + * + * @since Always. */ # define INT_LEAST8_MIN (__MAX_TO_MIN(INT_LEAST8_MAX)) /** * Maximum value of `uint_least16_t`. + * + * @since Always. */ # define UINT_LEAST16_MAX UINT16_MAX /** * Maximum value of `int_least16_t`. + * + * @since Always. */ # define INT_LEAST16_MAX INT16_MAX /** * Minimum value of `int_least16_t`. + * + * @since Always. */ # define INT_LEAST16_MIN (__MAX_TO_MIN(INT_LEAST16_MAX)) /** * Maximum value of `uint_least32_t`. + * + * @since Always. */ # define UINT_LEAST32_MAX UINT32_MAX /** * Maximum value of `int_least32_t`. + * + * @since Always. */ # define INT_LEAST32_MAX INT32_MAX /** * Minimum value of `int_least32_t`. + * + * @since Always. */ # define INT_LEAST32_MIN (__MAX_TO_MIN(INT_LEAST32_MAX)) /** * Maximum value of `uint_least64_t`. + * + * @since Always. */ # define UINT_LEAST64_MAX UINT64_MAX /** * Maximum value of `int_least64_t`. + * + * @since Always. */ # define INT_LEAST64_MAX INT64_MAX /** * Minimum value of `int_least64_t`. + * + * @since Always. */ # define INT_LEAST64_MIN (__MAX_TO_MIN(INT_LEAST64_MAX)) /** * Maximum value of `uint_fast8_t`. + * + * @since Always. */ # define UINT_FAST8_MAX __UINT_FAST8_MAX /** * Maximum value of `int_fast8_t`. + * + * @since Always. */ # define INT_FAST8_MAX __INT_FAST8_MAX /** * Minimum value of `int_fast8_t`. + * + * @since Always. */ # define INT_FAST8_MIN (__MAX_TO_MIN(INT_FAST8_MAX)) /** * Maximum value of `uint_fast16_t`. + * + * @since Always. */ # define UINT_FAST16_MAX __UINT_FAST16_MAX /** * Maximum value of `int_fast16_t`. + * + * @since Always. */ # define INT_FAST16_MAX __INT_FAST16_MAX /** * Minimum value of `int_fast16_t`. + * + * @since Always. */ # define INT_FAST16_MIN (__MAX_TO_MIN(INT_FAST16_MAX)) /** * Maximum value of `uint_fast32_t`. + * + * @since Always. */ # define UINT_FAST32_MAX __UINT_FAST32_MAX /** * Maximum value of `int_fast32_t`. + * + * @since Always. */ # define INT_FAST32_MAX __INT_FAST32_MAX /** * Minimum value of `int_fast32_t`. + * + * @since Always. */ # define INT_FAST32_MIN (__MAX_TO_MIN(INT_FAST32_MAX)) /** * Maximum value of `uint_fast64_t`. + * + * @since Always. */ # define UINT_FAST64_MAX __UINT_FAST64_MAX /** * Maximum value of `int_fast64_t`. + * + * @since Always. */ # define INT_FAST64_MAX __INT_FAST64_MAX /** * Minimum value of `int_fast64_t`. + * + * @since Always. */ # define INT_FAST64_MIN (__MAX_TO_MIN(INT_FAST64_MAX)) /** * Maximum value of `uintmax_t`. + * + * @since Always. */ # define UINTMAX_MAX __UINTMAX_MAX /** * Maximum value of `intmax_t`. + * + * @since Always. */ # define INTMAX_MAX __INTMAX_MAX /** * Minimum value of `intmax_t`. + * + * @since Always. */ # define INTMAX_MIN (__MAX_TO_MIN(INTMAX_MIN)) /** * Maximum value of `uintptr_t`. + * + * @since Always. */ # if __PTR_BIT == 8 # define UINTPTR_MAX UINT8_MAX @@ -354,6 +454,8 @@ /** * Maximum value of `intptr_t`. + * + * @since Always. */ # if __PTR_BIT == 8 # define INTPTR_MAX INT8_MAX @@ -367,6 +469,8 @@ /** * Minimum value of `intptr_t`. + * + * @since Always. */ # define INTPTR_MIN (__MAX_TO_MIN(INTPTR_MAX)) #endif @@ -374,16 +478,22 @@ /** * Maximum value of `size_t`. + * + * @since Always. */ #define SIZE_MAX UINTPTR_MAX /** * Maximum value of `ssize_t`. + * + * @since Always. */ #define SSIZE_MAX INTPTR_MAX /** * Minimum value of `ssize_t`. + * + * @since Always. */ #define SSIZE_MIN INTPTR_MIN @@ -391,22 +501,30 @@ #ifndef __PORTABLE /** * Maximum value of `wchar_t`. + * + * @since Always. */ # define WCHAR_MAX __WCHAR_MAX /** * Minimum value of `wchar_t`. + * + * @since Always. */ # define WCHAR_MIN (__MAX_TO_MIN(WCHAR_MAX)) /** * Maximum value of `wint_t`. + * + * @since Always. */ # define WINT_MAX WCHAR_MAX /** * Minimum value of `wint_t`. + * + * @since Always. */ # define WINT_MIN WCHAR_MIN #endif @@ -414,6 +532,8 @@ /** * Maximum value of `sig_atomic_t`. + * + * @since Always. */ #if __SIG_ATOMIC_BIT == 8 # define SIG_ATOMIC_MAX INT8_MAX @@ -427,6 +547,8 @@ /** * Minimum value of `sig_atomic_t`. + * + * @since Always. */ #define SIG_ATOMIC_MIN (__MAX_TO_MIN(__SIG_ATOMIC_MAX)) diff --git a/include/stdio.h b/include/stdio.h index 0f78e6e..c1b4a09 100644 --- a/include/stdio.h +++ b/include/stdio.h @@ -61,6 +61,8 @@ int fflush(FILE*); * * @throws EINVAL `format` contained unsupported formatting codes. * @throws Any error specified for `fwrite`. + * + * @since Always. */ int printf(const char* restrict, ...) __GCC_ONLY(__attribute__((__nonnull__(1), __format__(__slibc_printf__, 1, 2)))); @@ -84,6 +86,8 @@ int printf(const char* restrict, ...) * * @throws EINVAL `format` contained unsupported formatting codes. * @throws Any error specified for `fwrite`. + * + * @since Always. */ int fprintf(FILE* restrict, const char* restrict, ...) __GCC_ONLY(__attribute__((__nonnull__(1, 2), __format__(__slibc_printf__, 2, 3)))); @@ -109,6 +113,8 @@ int fprintf(FILE* restrict, const char* restrict, ...) * * @throws EINVAL `format` contained unsupported formatting codes. * @throws Any error specified for `fwrite_unlocked`. + * + * @since Always. */ int fprintf_unlocked(FILE* restrict, const char* restrict, ...) __GCC_ONLY(__attribute__((__nonnull__(1, 2), __format__(__slibc_printf__, 2, 3)))); @@ -134,6 +140,8 @@ int fprintf_unlocked(FILE* restrict, const char* restrict, ...) * * @throws EINVAL `format` contained unsupported formatting codes. * @throws Any error specified for `write`. + * + * @since Always. */ int dprintf(int, const char* restrict, ...) __GCC_ONLY(__attribute__((__nonnull__(2), __format__(__slibc_printf__, 2, 3)))); @@ -147,7 +155,7 @@ int dprintf(int, const char* restrict, ...) * This is a slibc extension added for completeness. * * @param fd The file descriptor. - * @parma flags Flags to pass to `send`, see `send` + * @param flags Flags to pass to `send`, see `send` * for more information. * @param format The formatting-string. * @param ... The formatting-arguments. @@ -162,6 +170,8 @@ int dprintf(int, const char* restrict, ...) * * @throws EINVAL `format` contained unsupported formatting codes. * @throws Any error specified for `write`. + * + * @since Always. */ int sockprintf(int, int, const char* restrict, ...) __GCC_ONLY(__attribute__((__nonnull__(3), __format__(__slibc_printf__, 3, 4)))); @@ -187,6 +197,8 @@ int sockprintf(int, int, const char* restrict, ...) * use "%zn" to find the actual length. * * @throws EINVAL `format` contained unsupported formatting codes. + * + * @since Always. */ int sprintf(char* restrict, const char* restrict, ...) __GCC_ONLY(__attribute__((__nonnull__(1, 2), __format__(__slibc_printf__, 2, 3)))); @@ -211,6 +223,8 @@ int sprintf(char* restrict, const char* restrict, ...) * actual length. * * @throws EINVAL `format` contained unsupported formatting codes. + * + * @since Always. */ int snprintf(char* restrict, size_t, const char* restrict, ...) __GCC_ONLY(__attribute__((__nonnull__(3), __format__(__slibc_printf__, 3, 4)))); @@ -245,6 +259,8 @@ int snprintf(char* restrict, size_t, const char* restrict, ...) * @throws EINVAL `format` contained unsupported formatting codes. * @throws ENOMEM The process cannot allocation the * sufficient amount of memory. + * + * @since Always. */ int asprintf(char** restrict, const char* restrict, ...) __GCC_ONLY(__attribute__((__nonnull__(1, 2), __format__(__slibc_printf__, 2, 3), __warn_unused_result__))); @@ -280,6 +296,8 @@ int asprintf(char** restrict, const char* restrict, ...) * use "%zn" to find the actual length. * * @throws EINVAL `format` contained unsupported formatting codes. + * + * @since Always. */ #define asprintfa(buffer, format, ...) \ ({ \ @@ -333,6 +351,8 @@ int asprintf(char** restrict, const char* restrict, ...) * @throws EINVAL `format` contained unsupported formatting codes. * @throws ENOMEM The process cannot allocation the * sufficient amount of memory. + * + * @since Always. */ int bprintf(char** restrict, size_t* restrict, size_t, int, const char* restrict, ...) __GCC_ONLY(__attribute__((__nonnull__(1, 2, 5), __format__(__slibc_printf__, 5, 6), __warn_unused_result__))); @@ -356,6 +376,8 @@ int bprintf(char** restrict, size_t* restrict, size_t, int, const char* restrict * * @throws EINVAL `format` contained unsupported formatting codes. * @throws Any error specified for `fwrite`. + * + * @since Always. */ int vprintf(const char* restrict, va_list) __GCC_ONLY(__attribute__((__nonnull__(1)))); @@ -378,6 +400,8 @@ int vprintf(const char* restrict, va_list) * * @throws EINVAL `format` contained unsupported formatting codes. * @throws Any error specified for `fwrite`. + * + * @since Always. */ int vfprintf(FILE* restrict, const char* restrict, va_list) __GCC_ONLY(__attribute__((__nonnull__(1, 2)))); @@ -403,6 +427,8 @@ int vfprintf(FILE* restrict, const char* restrict, va_list) * * @throws EINVAL `format` contained unsupported formatting codes. * @throws Any error specified for `fwrite_unlocked`. + * + * @since Always. */ int vfprintf_unlocked(FILE* restrict, const char* restrict, va_list) __GCC_ONLY(__attribute__((__nonnull__(1, 2)))); @@ -426,6 +452,8 @@ int vfprintf_unlocked(FILE* restrict, const char* restrict, va_list) * * @throws EINVAL `format` contained unsupported formatting codes. * @throws Any error specified for `write`. + * + * @since Always. */ int vdprintf(int, const char* restrict, va_list) __GCC_ONLY(__attribute__((__nonnull__(2)))); @@ -438,7 +466,7 @@ int vdprintf(int, const char* restrict, va_list) * This is a slibc extension added for completeness. * * @param fd The file descriptor. - * @parma flags Flags to pass to `send`, see `send` + * @param flags Flags to pass to `send`, see `send` * for more information. * @param format The formatting-string. * @param args The formatting-arguments. @@ -453,6 +481,8 @@ int vdprintf(int, const char* restrict, va_list) * * @throws EINVAL `format` contained unsupported formatting codes. * @throws Any error specified for `write`. + * + * @since Always. */ int vsockprintf(int, int, const char* restrict, va_list) __GCC_ONLY(__attribute__((__nonnull__(3), __format__(__slibc_printf__, 3, 4)))); @@ -475,6 +505,8 @@ int vsockprintf(int, int, const char* restrict, va_list) * use "%zn" to find the actual length. * * @throws EINVAL `format` contained unsupported formatting codes. + * + * @since Always. */ int vsprintf(char* restrict, const char* restrict, va_list) __GCC_ONLY(__attribute__((__nonnull__(1, 2)))); @@ -499,6 +531,8 @@ int vsprintf(char* restrict, const char* restrict, va_list) * actual length. * * @throws EINVAL `format` contained unsupported formatting codes. + * + * @since Always. */ int vsnprintf(char* restrict, size_t, const char* restrict, va_list) __GCC_ONLY(__attribute__((__nonnull__(3)))); @@ -532,6 +566,8 @@ int vsnprintf(char* restrict, size_t, const char* restrict, va_list) * @throws EINVAL `format` contained unsupported formatting codes. * @throws ENOMEM The process cannot allocation the * sufficient amount of memory. + * + * @since Always. */ int vasprintf(char** restrict, const char* restrict, va_list) __GCC_ONLY(__attribute__((__nonnull__(1, 2), __warn_unused_result__))); @@ -578,6 +614,8 @@ int vasprintf(char** restrict, const char* restrict, va_list) * @throws EINVAL `format` contained unsupported formatting codes. * @throws ENOMEM The process cannot allocation the * sufficient amount of memory. + * + * @since Always. */ int vbprintf(char** restrict, size_t* restrict, size_t, int, const char* restrict, va_list) __GCC_ONLY(__attribute__((__nonnull__(1, 2, 5), __warn_unused_result__))); @@ -602,6 +640,8 @@ int vbprintf(char** restrict, size_t* restrict, size_t, int, const char* restric * * @throws EINVAL `format` contained unsupported formatting codes. * @throws Any error specified for `fwrite`. + * + * @since Always. */ int wprintf(const wchar_t* restrict, ...) __GCC_ONLY(__attribute__((__nonnull__(1)))); @@ -624,6 +664,8 @@ int wprintf(const wchar_t* restrict, ...) * * @throws EINVAL `format` contained unsupported formatting codes. * @throws Any error specified for `fwrite`. + * + * @since Always. */ int fwprintf(FILE* restrict, const wchar_t* restrict, ...) __GCC_ONLY(__attribute__((__nonnull__(1, 2)))); @@ -649,6 +691,8 @@ int fwprintf(FILE* restrict, const wchar_t* restrict, ...) * * @throws EINVAL `format` contained unsupported formatting codes. * @throws Any error specified for `fwrite_unlocked`. + * + * @since Always. */ int fwprintf_unlocked(FILE* restrict, const wchar_t* restrict, ...) __GCC_ONLY(__attribute__((__nonnull__(1, 2)))); @@ -673,6 +717,8 @@ int fwprintf_unlocked(FILE* restrict, const wchar_t* restrict, ...) * * @throws EINVAL `format` contained unsupported formatting codes. * @throws Any error specified for `write`. + * + * @since Always. */ int dwprintf(int, const wchar_t* restrict, ...) __GCC_ONLY(__attribute__((__nonnull__(2)))); @@ -684,7 +730,7 @@ int dwprintf(int, const wchar_t* restrict, ...) * This is a slibc extension added for completeness. * * @param fd The file descriptor. - * @parma flags Flags to pass to `send`, see `send` + * @param flags Flags to pass to `send`, see `send` * for more information. * @param format The formatting-string. * @param ... The formatting-arguments. @@ -699,6 +745,8 @@ int dwprintf(int, const wchar_t* restrict, ...) * * @throws EINVAL `format` contained unsupported formatting codes. * @throws Any error specified for `write`. + * + * @since Always. */ int sockwprintf(int, int, const wchar_t* restrict, ...) __GCC_ONLY(__attribute__((__nonnull__(3)))); @@ -724,6 +772,8 @@ int sockwprintf(int, int, const wchar_t* restrict, ...) * actual length. * * @throws EINVAL `format` contained unsupported formatting codes. + * + * @since Always. */ int swprintf(wchar_t* restrict, size_t, const wchar_t* restrict, ...) __GCC_ONLY(__attribute__((__nonnull__(3)))); @@ -758,6 +808,8 @@ int swprintf(wchar_t* restrict, size_t, const wchar_t* restrict, ...) * @throws EINVAL `format` contained unsupported formatting codes. * @throws ENOMEM The process cannot allocation the * sufficient amount of memory. + * + * @since Always. */ int aswprintf(wchar_t** restrict, const wchar_t* restrict, ...) __GCC_ONLY(__attribute__((__nonnull__(1, 2), __warn_unused_result__))); @@ -793,6 +845,8 @@ int aswprintf(wchar_t** restrict, const wchar_t* restrict, ...) * use "%zn" to find the actual length. * * @throws EINVAL `format` contained unsupported formatting codes. + * + * @since Always. */ #define aswprintfa(buffer, format, ...) \ ({ \ @@ -847,6 +901,8 @@ int aswprintf(wchar_t** restrict, const wchar_t* restrict, ...) * @throws EINVAL `format` contained unsupported formatting codes. * @throws ENOMEM The process cannot allocation the * sufficient amount of memory. + * + * @since Always. */ int bwprintf(wchar_t** restrict, size_t* restrict, size_t, int, const wchar_t* restrict, ...) __GCC_ONLY(__attribute__((__nonnull__(1, 2, 5), __warn_unused_result__))); @@ -870,6 +926,8 @@ int bwprintf(wchar_t** restrict, size_t* restrict, size_t, int, const wchar_t* r * * @throws EINVAL `format` contained unsupported formatting codes. * @throws Any error specified for `fwrite`. + * + * @since Always. */ int vwprintf(const wchar_t* restrict, va_list) __GCC_ONLY(__attribute__((__nonnull__(1)))); @@ -892,6 +950,8 @@ int vwprintf(const wchar_t* restrict, va_list) * * @throws EINVAL `format` contained unsupported formatting codes. * @throws Any error specified for `fwrite`. + * + * @since Always. */ int vfwprintf(FILE* restrict, const wchar_t* restrict, va_list) __GCC_ONLY(__attribute__((__nonnull__(1, 2)))); @@ -917,6 +977,8 @@ int vfwprintf(FILE* restrict, const wchar_t* restrict, va_list) * * @throws EINVAL `format` contained unsupported formatting codes. * @throws Any error specified for `fwrite_unlocked`. + * + * @since Always. */ int vfwprintf_unlocked(FILE* restrict, const wchar_t* restrict, va_list) __GCC_ONLY(__attribute__((__nonnull__(1, 2)))); @@ -941,6 +1003,8 @@ int vfwprintf_unlocked(FILE* restrict, const wchar_t* restrict, va_list) * * @throws EINVAL `format` contained unsupported formatting codes. * @throws Any error specified for `write`. + * + * @since Always. */ int vdwprintf(int, const wchar_t* restrict, va_list) __GCC_ONLY(__attribute__((__nonnull__(2)))); @@ -952,7 +1016,7 @@ int vdwprintf(int, const wchar_t* restrict, va_list) * This is a slibc extension added for completeness. * * @param fd The file descriptor. - * @parma flags Flags to pass to `send`, see `send` + * @param flags Flags to pass to `send`, see `send` * for more information. * @param format The formatting-string. * @param args The formatting-arguments. @@ -967,6 +1031,8 @@ int vdwprintf(int, const wchar_t* restrict, va_list) * * @throws EINVAL `format` contained unsupported formatting codes. * @throws Any error specified for `write`. + * + * @since Always. */ int vsockwprintf(int, int, const wchar_t* restrict, va_list) __GCC_ONLY(__attribute__((__nonnull__(3)))); @@ -992,6 +1058,8 @@ int vsockwprintf(int, int, const wchar_t* restrict, va_list) * actual length. * * @throws EINVAL `format` contained unsupported formatting codes. + * + * @since Always. */ int vswprintf(wchar_t* restrict, size_t, const wchar_t* restrict, va_list) __GCC_ONLY(__attribute__((__nonnull__(3)))); @@ -1026,6 +1094,8 @@ int vswprintf(wchar_t* restrict, size_t, const wchar_t* restrict, va_list) * @throws EINVAL `format` contained unsupported formatting codes. * @throws ENOMEM The process cannot allocation the * sufficient amount of memory. + * + * @since Always. */ int vaswprintf(wchar_t** restrict, const wchar_t* restrict, va_list) __GCC_ONLY(__attribute__((__nonnull__(1, 2), __warn_unused_result__))); @@ -1073,6 +1143,8 @@ int vaswprintf(wchar_t** restrict, const wchar_t* restrict, va_list) * @throws EINVAL `format` contained unsupported formatting codes. * @throws ENOMEM The process cannot allocation the * sufficient amount of memory. + * + * @since Always. */ int vbwprintf(wchar_t** restrict, size_t* restrict, size_t, int, const wchar_t* restrict, va_list) __GCC_ONLY(__attribute__((__nonnull__(1, 2, 5), __warn_unused_result__))); @@ -1092,6 +1164,8 @@ int vbwprintf(wchar_t** restrict, size_t* restrict, size_t, int, const wchar_t* * if the end of the input is reached before the * first argument is successfully converted, or * on error. + * + * @since Always. */ int scanf(const char* restrict, ...) __GCC_ONLY(__attribute__((__warn_unused_result__, __nonnull__(1), __format__(__slibc_scanf__, 1, 2)))); @@ -1109,6 +1183,8 @@ int scanf(const char* restrict, ...) * if the end of the input is reached before the * first argument is successfully converted, or * on error. + * + * @since Always. */ int fscanf(FILE* restrict, const char* restrict, ...) __GCC_ONLY(__attribute__((__warn_unused_result__, __nonnull__(1, 2), __format__(__slibc_scanf__, 2, 3)))); @@ -1126,6 +1202,8 @@ int fscanf(FILE* restrict, const char* restrict, ...) * if the end of the input is reached before the * first argument is successfully converted, or * on error. + * + * @since Always. */ int sscanf(const char* restrict, const char* restrict, ...) __GCC_ONLY(__attribute__((__warn_unused_result__, __nonnull__(1, 2), __format__(__slibc_scanf__, 2, 3)))); @@ -1145,6 +1223,8 @@ int sscanf(const char* restrict, const char* restrict, ...) * if the end of the input is reached before the * first argument is successfully converted, or * on error. + * + * @since Always. */ int fscanf_unlocked(FILE* restrict, const char* restrict, ...) __GCC_ONLY(__attribute__((__warn_unused_result__, __nonnull__(1, 2), __format__(__slibc_scanf__, 2, 3)))); @@ -1166,6 +1246,8 @@ int fscanf_unlocked(FILE* restrict, const char* restrict, ...) * if the end of the input is reached before the * first argument is successfully converted, or * on error. + * + * @since Always. */ int snscanf(const char* restrict, size_t, const char* restrict, ...) __GCC_ONLY(__attribute__((__warn_unused_result__, __nonnull__(3), __format__(__slibc_scanf__, 3, 4)))); @@ -1186,6 +1268,8 @@ int snscanf(const char* restrict, size_t, const char* restrict, ...) * if the end of the input is reached before the * first argument is successfully converted, or * on error. + * + * @since Always. */ int dscanf(int, const char* restrict, ...) __GCC_ONLY(__attribute__((__warn_unused_result__, __nonnull__(2), __format__(__slibc_scanf__, 2, 3)))); @@ -1203,6 +1287,8 @@ int dscanf(int, const char* restrict, ...) * if the end of the input is reached before the * first argument is successfully converted, or * on error. + * + * @since Always. */ int vscanf(const char* restrict, va_list) __GCC_ONLY(__attribute__((__warn_unused_result__, __nonnull__(1)))); @@ -1219,6 +1305,8 @@ int vscanf(const char* restrict, va_list) * if the end of the input is reached before the * first argument is successfully converted, or * on error. + * + * @since Always. */ int vfscanf(FILE* restrict, const char* restrict, va_list) __GCC_ONLY(__attribute__((__warn_unused_result__, __nonnull__(1, 2)))); @@ -1235,6 +1323,8 @@ int vfscanf(FILE* restrict, const char* restrict, va_list) * if the end of the input is reached before the * first argument is successfully converted, or * on error. + * + * @since Always. */ int vsscanf(const char* restrict, const char* restrict, va_list) __GCC_ONLY(__attribute__((__warn_unused_result__, __nonnull__(1, 2)))); @@ -1254,6 +1344,8 @@ int vsscanf(const char* restrict, const char* restrict, va_list) * if the end of the input is reached before the * first argument is successfully converted, or * on error. + * + * @since Always. */ int vfscanf_unlocked(FILE* restrict, const char* restrict, va_list) __GCC_ONLY(__attribute__((__warn_unused_result__, __nonnull__(1, 2)))); @@ -1273,6 +1365,8 @@ int vfscanf_unlocked(FILE* restrict, const char* restrict, va_list) * if the end of the input is reached before the * first argument is successfully converted, or * on error. + * + * @since Always. */ int vsnscanf(const char* restrict, size_t, const char* restrict, va_list) __GCC_ONLY(__attribute__((__warn_unused_result__, __nonnull__(3)))); @@ -1291,6 +1385,8 @@ int vsnscanf(const char* restrict, size_t, const char* restrict, va_list) * if the end of the input is reached before the * first argument is successfully converted, or * on error. + * + * @since Always. */ int vdscanf(int, const char* restrict, va_list) __GCC_ONLY(__attribute__((__warn_unused_result__, __nonnull__(2)))); @@ -1308,6 +1404,8 @@ int vdscanf(int, const char* restrict, va_list) * if the end of the input is reached before the * first argument is successfully converted, or * on error. + * + * @since Always. */ int wscanf(const wchar_t* restrict, ...) __GCC_ONLY(__attribute__((__warn_unused_result__, __nonnull__(1)))); @@ -1324,6 +1422,8 @@ int wscanf(const wchar_t* restrict, ...) * if the end of the input is reached before the * first argument is successfully converted, or * on error. + * + * @since Always. */ int fwscanf(FILE* restrict, const wchar_t* restrict, ...) __GCC_ONLY(__attribute__((__warn_unused_result__, __nonnull__(1, 2)))); @@ -1340,6 +1440,8 @@ int fwscanf(FILE* restrict, const wchar_t* restrict, ...) * if the end of the input is reached before the * first argument is successfully converted, or * on error. + * + * @since Always. */ int swscanf(const wchar_t* restrict, const wchar_t* restrict, ...) __GCC_ONLY(__attribute__((__warn_unused_result__, __nonnull__(1, 2)))); @@ -1359,6 +1461,8 @@ int swscanf(const wchar_t* restrict, const wchar_t* restrict, ...) * if the end of the input is reached before the * first argument is successfully converted, or * on error. + * + * @since Always. */ int fwscanf_unlocked(FILE* restrict, const wchar_t* restrict, ...) __GCC_ONLY(__attribute__((__warn_unused_result__, __nonnull__(1, 2)))); @@ -1378,6 +1482,8 @@ int fwscanf_unlocked(FILE* restrict, const wchar_t* restrict, ...) * if the end of the input is reached before the * first argument is successfully converted, or * on error. + * + * @since Always. */ int snwscanf(const wchar_t* restrict, size_t, const wchar_t* restrict, ...) __GCC_ONLY(__attribute__((__warn_unused_result__, __nonnull__(3)))); @@ -1396,6 +1502,8 @@ int snwscanf(const wchar_t* restrict, size_t, const wchar_t* restrict, ...) * if the end of the input is reached before the * first argument is successfully converted, or * on error. + * + * @since Always. */ int dwscanf(int, const wchar_t* restrict, ...) __GCC_ONLY(__attribute__((__warn_unused_result__, __nonnull__(2)))); @@ -1413,6 +1521,8 @@ int dwscanf(int, const wchar_t* restrict, ...) * if the end of the input is reached before the * first argument is successfully converted, or * on error. + * + * @since Always. */ int vwscanf(const wchar_t* restrict, va_list) __GCC_ONLY(__attribute__((__warn_unused_result__, __nonnull__(1)))); @@ -1429,6 +1539,8 @@ int vwscanf(const wchar_t* restrict, va_list) * if the end of the input is reached before the * first argument is successfully converted, or * on error. + * + * @since Always. */ int vfwscanf(FILE* restrict, const wchar_t* restrict, va_list) __GCC_ONLY(__attribute__((__warn_unused_result__, __nonnull__(1, 2)))); @@ -1445,6 +1557,8 @@ int vfwscanf(FILE* restrict, const wchar_t* restrict, va_list) * if the end of the input is reached before the * first argument is successfully converted, or * on error. + * + * @since Always. */ int vswscanf(const wchar_t* restrict, const wchar_t* restrict, va_list) __GCC_ONLY(__attribute__((__warn_unused_result__, __nonnull__(1, 2)))); @@ -1464,6 +1578,8 @@ int vswscanf(const wchar_t* restrict, const wchar_t* restrict, va_list) * if the end of the input is reached before the * first argument is successfully converted, or * on error. + * + * @since Always. */ int vfwscanf_unlocked(FILE* restrict, const wchar_t* restrict, va_list) __GCC_ONLY(__attribute__((__warn_unused_result__, __nonnull__(1, 2)))); @@ -1483,6 +1599,8 @@ int vfwscanf_unlocked(FILE* restrict, const wchar_t* restrict, va_list) * if the end of the input is reached before the * first argument is successfully converted, or * on error. + * + * @since Always. */ int vsnwscanf(const wchar_t* restrict, size_t, const wchar_t* restrict, va_list) __GCC_ONLY(__attribute__((__warn_unused_result__, __nonnull__(3)))); @@ -1501,6 +1619,8 @@ int vsnwscanf(const wchar_t* restrict, size_t, const wchar_t* restrict, va_list) * if the end of the input is reached before the * first argument is successfully converted, or * on error. + * + * @since Always. */ int vdwscanf(int, const wchar_t* restrict, va_list) __GCC_ONLY(__attribute__((__warn_unused_result__, __nonnull__(2)))); @@ -1511,6 +1631,8 @@ int vdwscanf(int, const wchar_t* restrict, va_list) #if !defined(__PORTABLE) /** * This function is identical to `scanf`. + * + * @since Always. */ int __isoc99_scanf(const char* restrict, ...) __deprecated("Use 'scanf' instead.") @@ -1518,6 +1640,8 @@ int __isoc99_scanf(const char* restrict, ...) /** * This function is identical to `fscanf`. + * + * @since Always. */ int __isoc99_fscanf(FILE* restrict, const char* restrict, ...) __deprecated("Use 'fscanf' instead.") @@ -1525,6 +1649,8 @@ int __isoc99_fscanf(FILE* restrict, const char* restrict, ...) /** * This function is identical to `sscanf`. + * + * @since Always. */ int __isoc99_sscanf(const char* restrict, const char* restrict, ...) __deprecated("Use 'sscanf' instead.") @@ -1533,6 +1659,8 @@ int __isoc99_sscanf(const char* restrict, const char* restrict, ...) /** * This function is identical to `vscanf`. + * + * @since Always. */ int __isoc99_vscanf(const char* restrict, va_list) __deprecated("Use 'vscanf' instead.") @@ -1540,6 +1668,8 @@ int __isoc99_vscanf(const char* restrict, va_list) /** * This function is identical to `vfscanf`. + * + * @since Always. */ int __isoc99_vfscanf(FILE* restrict, const char* restrict, va_list) __deprecated("Use 'vfscanf' instead.") @@ -1547,6 +1677,8 @@ int __isoc99_vfscanf(FILE* restrict, const char* restrict, va_list) /** * This function is identical to `vsscanf`. + * + * @since Always. */ int __isoc99_vsscanf(const char* restrict, const char* restrict, va_list) __deprecated("Use 'vsscanf' instead.") @@ -1555,6 +1687,8 @@ int __isoc99_vsscanf(const char* restrict, const char* restrict, va_list) /** * This function is identical to `wscanf`. + * + * @since Always. */ int __isoc99_wscanf(const wchar_t* restrict, ...) __deprecated("Use 'wscanf' instead.") @@ -1562,6 +1696,8 @@ int __isoc99_wscanf(const wchar_t* restrict, ...) /** * This function is identical to `fwscanf`. + * + * @since Always. */ int __isoc99_fwscanf(FILE* restrict, const wchar_t* restrict, ...) __deprecated("Use 'fwscanf' instead.") @@ -1569,6 +1705,8 @@ int __isoc99_fwscanf(FILE* restrict, const wchar_t* restrict, ...) /** * This function is identical to `swscanf`. + * + * @since Always. */ int __isoc99_swscanf(const wchar_t* restrict, const wchar_t* restrict, ...) __deprecated("Use 'swscanf' instead.") @@ -1577,6 +1715,8 @@ int __isoc99_swscanf(const wchar_t* restrict, const wchar_t* restrict, ...) /** * This function is identical to `vwscanf`. + * + * @since Always. */ int __isoc99_vwscanf(const wchar_t* restrict, va_list) __deprecated("Use 'vwscanf' instead.") @@ -1584,6 +1724,8 @@ int __isoc99_vwscanf(const wchar_t* restrict, va_list) /** * This function is identical to `vfwscanf`. + * + * @since Always. */ int __isoc99_vfwscanf(FILE* restrict, const wchar_t* restrict, va_list) __deprecated("Use 'vfwscanf' instead.") @@ -1591,6 +1733,8 @@ int __isoc99_vfwscanf(FILE* restrict, const wchar_t* restrict, va_list) /** * This function is identical to `vswscanf`. + * + * @since Always. */ int __isoc99_vswscanf(const wchar_t* restrict, const wchar_t* restrict, va_list) __deprecated("Use 'vswscanf' instead.") diff --git a/include/stdlib.h b/include/stdlib.h index 075d3a4..3229384 100644 --- a/include/stdlib.h +++ b/include/stdlib.h @@ -45,12 +45,16 @@ /** * The value a process shall exit with upon * success completion. + * + * @since Always. */ #define EXIT_SUCCESS 0 /** * A standard value a process can exit with * if it terminates because of failure. + * + * @since Always. */ #define EXIT_FAILURE 1 @@ -65,6 +69,8 @@ * the process will be killed by SIGFPE. * @return The quotient in `.quot`, and * the remainder in `.rem`. + * + * @since Always. */ div_t div(int, int) __GCC_ONLY(__attribute__((__const__))); @@ -78,6 +84,8 @@ div_t div(int, int) * the process will be killed by SIGFPE. * @return The quotient in `.quot`, and * the remainder in `.rem`. + * + * @since Always. */ ldiv_t ldiv(long, long) __GCC_ONLY(__attribute__((__const__))); @@ -91,6 +99,8 @@ ldiv_t ldiv(long, long) * the process will be killed by SIGFPE. * @return The quotient in `.quot`, and * the remainder in `.rem`. + * + * @since Always. */ lldiv_t lldiv(long long, long long) __GCC_ONLY(__attribute__((__const__))); @@ -106,6 +116,8 @@ lldiv_t lldiv(long long, long long) * * @param value The integer. * @return The absolute value of the integer. + * + * @since Always. */ int (abs)(int) __GCC_ONLY(__attribute__((__const__))); @@ -121,6 +133,8 @@ int (abs)(int) * * @param value The integer. * @return The absolute value of the integer. + * + * @since Always. */ long int (labs)(long int) __GCC_ONLY(__attribute__((__const__))); @@ -136,6 +150,8 @@ long int (labs)(long int) * * @param value The integer. * @return The absolute value of the integer. + * + * @since Always. */ long long int (llabs)(long long int) __GCC_ONLY(__attribute__((__const__))); @@ -157,6 +173,8 @@ long long int (llabs)(long long int) * if `file` does. (Or if `ref` does but file is empty.) * * @throws ENOMEM The process cannot allocate more memory. + * + * @since Always. */ char* abspath(const char*, const char*) __GCC_ONLY(__attribute__((__warn_unused_result__, __nonnull__(1), __malloc__))); @@ -176,6 +194,8 @@ char* abspath(const char*, const char*) * point to `file`. * * @throws ENOMEM The process cannot allocate more memory. + * + * @since Always. */ char* relpath(const char*, const char*) __GCC_ONLY(__attribute__((__warn_unused_result__, __nonnull__(1), __malloc__))); @@ -194,6 +214,8 @@ char* relpath(const char*, const char*) * * @param string The string to convert. * @return The number encoded by the string. + * + * @since Always. */ double atof(const char*) __GCC_ONLY(__attribute__((__warn_unused_result__, __nonnull__, __pure__))); @@ -210,6 +232,8 @@ double atof(const char*) * * @param string The string to convert. * @return The integer encoded by the string. + * + * @since Always. */ int atoi(const char*) __GCC_ONLY(__attribute__((__warn_unused_result__, __nonnull__, __pure__))); @@ -226,6 +250,8 @@ int atoi(const char*) * * @param string The string to convert. * @return The integer encoded by the string. + * + * @since Always. */ long int atol(const char*) __GCC_ONLY(__attribute__((__warn_unused_result__, __nonnull__, __pure__))); @@ -242,6 +268,8 @@ long int atol(const char*) * * @param string The string to convert. * @return The integer encoded by the string. + * + * @since Always. */ long long int atoll(const char*) __GCC_ONLY(__attribute__((__warn_unused_result__, __nonnull__, __pure__))); @@ -251,6 +279,8 @@ long long int atoll(const char*) * This function is identical to `atoll`. * * This is a Linux libc extension. + * + * @since Always. */ long long int atoq(const char*) __deprecated("'atoq' is obsolete and not portable, use 'atoll' instead.") diff --git a/include/stdnoreturn.h b/include/stdnoreturn.h index 2aad0c4..1a88f1a 100644 --- a/include/stdnoreturn.h +++ b/include/stdnoreturn.h @@ -34,6 +34,8 @@ * Specifies that a function never returns, that is, * the process exits or changes process image before * the function returns. + * + * @since Always. */ # if !defined(__C11__) && defined(__GNUC__) # define _Noreturn __attribute__((__noreturn__)) diff --git a/include/string.h b/include/string.h index ea3a4de..8369f30 100644 --- a/include/string.h +++ b/include/string.h @@ -59,6 +59,8 @@ * * @param errnum The error code. * @return A description of the error. + * + * @since Always. */ char* strerror(int) __GCC_ONLY(__attribute__((__returns_nonnull__, __warn_unused_result__))); @@ -80,6 +82,8 @@ char* strerror(int) * @param locale The locale, must be a valid locale and not * `LC_GLOBAL_LOCALE`, lest the behaviour is undefined. * @return A description of the error. + * + * @since Always. */ char* strerror_l(int, locale_t) __GCC_ONLY(__attribute__((__warn_unused_result__))); /* TODO attributes */ @@ -102,6 +106,8 @@ char* strerror_l(int, locale_t) * @return Zero on success, value for `errno` on error * * @throws ERANGE `buf` was too small to store the description. + * + * @since Always. */ int __xsi_strerror_r(int, char*, size_t); /* XSI-compliant strerror_r */ @@ -121,6 +127,8 @@ int __xsi_strerror_r(int, char*, size_t); /* XSI-compliant strerror_r */ * is set to indicate the error. * * @throws ERANGE `buf` was too small to store the description. + * + * @since Always. */ char* __gnu_strerror_r(int, char*, size_t); /* GNU-specific strerror_r */ @@ -139,6 +147,8 @@ char* __gnu_strerror_r(int, char*, size_t); /* GNU-specific strerror_r */ * * @param str The string. * @return The number of bytes before the first NUL byte. + * + * @since Always. */ size_t strlen(const char*) __GCC_ONLY(__attribute__((__nonnull__, __warn_unused_result__, __pure__))); @@ -154,6 +164,8 @@ size_t strlen(const char*) * @param maxlen The number of bytes to inspect, at most. * @return The number of bytes before, the first NUL byte. * `maxlen` if no NUL byte was found. + * + * @since Always. */ size_t strnlen(const char*, size_t) __GCC_ONLY(__attribute__((__warn_unused_result__, __pure__))); @@ -168,6 +180,8 @@ size_t strnlen(const char*, size_t) * @param c The character (8 bits wide.) * @param size The size of the memory segment. * @return `segment` is returned. + * + * @since Always. */ void* memset(void*, int, size_t); @@ -178,6 +192,8 @@ void* memset(void*, int, size_t); * @param whence The source memory segment. * @param size The number of bytes to copy. * @return `whither` is returned. + * + * @since Always. */ void* memcpy(void* restrict, const void* restrict, size_t); @@ -191,6 +207,8 @@ void* memcpy(void* restrict, const void* restrict, size_t); * @param whence The source memory segment. * @param size The number of bytes to copy. * @return `whither + size` is returned. + * + * @since Always. */ void* mempcpy(void* restrict, const void* restrict, size_t); #endif @@ -202,6 +220,8 @@ void* mempcpy(void* restrict, const void* restrict, size_t); * @param whence The source memory segment. * @param size The number of bytes to copy. * @return `whither` is returned. + * + * @since Always. */ void* memmove(void*, const void*, size_t); @@ -216,6 +236,8 @@ void* memmove(void*, const void*, size_t); * @param whence The source memory segment. * @param size The number of bytes to copy. * @return `whither + size` is returned. + * + * @since Always. */ void* mempmove(void*, const void*, size_t); #endif @@ -233,6 +255,8 @@ void* mempmove(void*, const void*, size_t); * that is, the address of `whither` plus the * number of copied characters; the address of * one character passed the last written character. + * + * @since Always. */ void* memccpy(void* restrict, const void* restrict, int, size_t); @@ -252,6 +276,8 @@ void* memccpy(void* restrict, const void* restrict, int, size_t); * that is, the address of `whither` plus the * number of copied characters; the address of * one character passed the last written character. + * + * @since Always. */ void* memcmove(void*, const void*, int, size_t); @@ -264,6 +290,8 @@ void* memcmove(void*, const void*, int, size_t); * @param str The beginning of the memory segment. * @param c The character (8 bits wide.) * @return `str` is returned. + * + * @since Always. */ char* strset(char* str, int c); __GCC_ONLY(__attribute__((__returns_nonnull__, __nonnull__))); @@ -276,6 +304,8 @@ char* strset(char* str, int c); * @param whither The destination memory segment. * @param whence The source memory segment. * @return `whither` is returned. + * + * @since Always. */ char* strcpy(char* restrict, const char* restrict) __GCC_ONLY(__attribute__((__returns_nonnull__, __nonnull__))); @@ -287,6 +317,8 @@ char* strcpy(char* restrict, const char* restrict) * @param whither The destination memory segment. * @param whence The source memory segment. * @return `whither + strlen(whence)` is returned. + * + * @since Always. */ char* stpcpy(char* restrict, const char* restrict) __GCC_ONLY(__attribute__((__returns_nonnull__, __nonnull__))); @@ -307,6 +339,8 @@ char* stpcpy(char* restrict, const char* restrict) * number of copied characters; the address of * one character passed the last written non-NUL * character. + * + * @since Always. */ char* strccpy(char* restrict, const char* restrict, int) __GCC_ONLY(__attribute__((__nonnull__))); @@ -326,6 +360,8 @@ char* strccpy(char* restrict, const char* restrict, int) * number of copied characters; the address of * one character passed the last written non-NUL * character. + * + * @since Always. */ char* strstrcpy(char* restrict, const char* restrict, const char* restrict) __GCC_ONLY(__attribute__((__nonnull__(1, 2)))); @@ -344,6 +380,8 @@ char* strstrcpy(char* restrict, const char* restrict, const char* restrict) * shorter, `whither` will be filled with NUL bytes * until this amount of bytes have been written. * @return `whither` is returned. + * + * @since Always. */ char* strncpy(char* restrict, const char* restrict, size_t) __GCC_ONLY(__attribute__((__returns_nonnull__, __nonnull__))); @@ -365,6 +403,8 @@ char* strncpy(char* restrict, const char* restrict, size_t) * until this amount of bytes have been written. * @return `whither` plus the number of written bytes, * excluding NUL bytes, is returned. + * + * @since Always. */ char* stpncpy(char* restrict, const char* restrict, size_t) __GCC_ONLY(__attribute__((__returns_nonnull__, __nonnull__))); @@ -392,6 +432,8 @@ char* stpncpy(char* restrict, const char* restrict, size_t) * number of copied characters; the address of * one character passed the last written non-NUL * character. + * + * @since Always. */ char* strcncpy(char* restrict, const char* restrict, int, size_t) __GCC_ONLY(__attribute__((__nonnull__))); @@ -418,6 +460,8 @@ char* strcncpy(char* restrict, const char* restrict, int, size_t) * number of copied characters; the address of * one character passed the last written non-NUL * character. + * + * @since Always. */ char* strstrncpy(char* restrict, const char* restrict, const char* restrict, size_t) __GCC_ONLY(__attribute__((__nonnull__(1, 2)))); @@ -434,6 +478,8 @@ char* strstrncpy(char* restrict, const char* restrict, const char* restrict, siz * @param whither The destination memory segment. * @param whence The source memory segment. * @return `whither` is returned. + * + * @since Always. */ char* strmove(char*, const char*) __GCC_ONLY(__attribute__((__returns_nonnull__, __nonnull__))); @@ -447,6 +493,8 @@ char* strmove(char*, const char*) * @param whither The destination memory segment. * @param whence The source memory segment. * @return `whither + strlen(whence)` is returned. + * + * @since Always. */ char* stpmove(char*, const char*) __GCC_ONLY(__attribute__((__returns_nonnull__, __nonnull__))); @@ -466,6 +514,8 @@ char* stpmove(char*, const char*) * number of copied characters; the address of * one character passed the last written non-NUL * character. + * + * @since Always. */ char* strcmove(char*, const char*, int) __GCC_ONLY(__attribute__((__nonnull__))); @@ -485,6 +535,8 @@ char* strcmove(char*, const char*, int) * number of copied characters; the address of * one character passed the last written non-NUL * character. + * + * @since Always. */ char* strstrmove(char*, const char*, const char* restrict) __GCC_ONLY(__attribute__((__nonnull__(1, 2)))); @@ -504,6 +556,8 @@ char* strstrmove(char*, const char*, const char* restrict) * shorter, `whither` will be filled with NUL bytes * until this amount of bytes have been written. * @return `whither` is returned. + * + * @since Always. */ char* strnmove(char*, const char*, size_t) __GCC_ONLY(__attribute__((__returns_nonnull__, __nonnull__))); @@ -526,6 +580,8 @@ char* strnmove(char*, const char*, size_t) * until this amount of bytes have been written. * @return `whither` plus the number of written bytes, * excluding NUL bytes, is returned. + * + * @since Always. */ char* stpnmove(char*, const char*, size_t) __GCC_ONLY(__attribute__((__returns_nonnull__, __nonnull__))); @@ -552,6 +608,8 @@ char* stpnmove(char*, const char*, size_t) * number of copied characters; the address of * one character passed the last written non-NUL * character. + * + * @since Always. */ char* strcnmove(char*, const char*, int, size_t) __GCC_ONLY(__attribute__((__nonnull__))); @@ -578,6 +636,8 @@ char* strcnmove(char*, const char*, int, size_t) * number of copied characters; the address of * one character passed the last written non-NUL * character. + * + * @since Always. */ char* strstrnmove(char*, const char*, const char* restrict, size_t) __GCC_ONLY(__attribute__((__nonnull__(1, 2)))); @@ -593,6 +653,8 @@ char* strstrnmove(char*, const char*, const char* restrict, size_t) * @param whither The string to extend. * @param whence The string to append. * @return `whither` is returned. + * + * @since Always. */ char* strcat(char* restrict, const char* restrict) __GCC_ONLY(__attribute__((__nonnull__))); @@ -614,6 +676,8 @@ char* strcat(char* restrict, const char* restrict) * shorter, `whither` will be filled with NUL bytes * until this amount of bytes have been written. * @return `whither` is returned. + * + * @since Always. */ char* strncat(char* restrict, const char* restrict, size_t) __GCC_ONLY(__attribute__((__nonnull__))); @@ -629,6 +693,8 @@ char* strncat(char* restrict, const char* restrict, size_t) * and `errno` is set to indicate the error. * * @throws ENOMEM The process could not allocate sufficient amount of memory. + * + * @since Always. */ char* strdup(const char*) __GCC_ONLY(__attribute__((__malloc__, __nonnull__, __warn_unused_result__))); @@ -647,6 +713,8 @@ char* strdup(const char*) * and `errno` is set to indicate the error. * * @throws ENOMEM The process could not allocate sufficient amount of memory. + * + * @since Always. */ char* strndup(const char*, size_t) __GCC_ONLY(__attribute__((__malloc__, __nonnull__, __warn_unused_result__))); @@ -664,6 +732,8 @@ char* strndup(const char*, size_t) * and `errno` is set to indicate the error. * * @throws ENOMEM The process could not allocate sufficient amount of memory. + * + * @since Always. */ void* memdup(const void*, size_t) __GCC_ONLY(__attribute__((__malloc__, __nonnull__, __warn_unused_result__))); @@ -680,6 +750,8 @@ void* memdup(const void*, size_t) * @param string:const char* The string to duplicate. * @return :size_t The new string. There is no way to * detect whether the allocation failed. + * + * @since Always. */ # define strdupa(string) \ ({ \ @@ -702,6 +774,8 @@ void* memdup(const void*, size_t) * A NUL byte is guaranteed to always be written. * @return :size_t The new string. There is no way to * detect whether the allocation failed. + * + * @since Always. */ # define strndupa(string, maxlen) \ ({ \ @@ -723,6 +797,8 @@ void* memdup(const void*, size_t) * @param size:size_t The size of the memory segment. * @return :size_t The new segment. There is no way to * detect whether the allocation failed. + * + * @since Always. */ # define memdupa(segment, size) \ ({ \ @@ -743,6 +819,8 @@ void* memdup(const void*, size_t) * @param size The size of the segments. * @return Zero is returned if `a` and `b` are equal, otherwise, * see the specifications for `a` and `b`. + * + * @since Always. */ int memcmp(const void*, const void*, size_t) __GCC_ONLY(__attribute__((__warn_unused_result__, __pure__))); @@ -759,6 +837,8 @@ int memcmp(const void*, const void*, size_t) * @param size The size of the segments. * @return Zero is returned if `a` and `b` are equal, otherwise, * see the specifications for `a` and `b`. + * + * @since Always. */ int memcasecmp(const void*, const void*, size_t) __GCC_ONLY(__attribute__((__warn_unused_result__, __pure__))); @@ -771,6 +851,8 @@ int memcasecmp(const void*, const void*, size_t) * @param b A positive value is returned if this is the lesser. * @return Zero is returned if `a` and `b` are equal, otherwise, * see the specifications for `a` and `b`. + * + * @since Always. */ int strcmp(const char*, const char*) __GCC_ONLY(__attribute__((__warn_unused_result__, __nonnull__, __pure__))); @@ -783,6 +865,8 @@ int strcmp(const char*, const char*) * @param length The maximum number of characters to compare. * @return Zero is returned if `a` and `b` are equal, otherwise, * see the specifications for `a` and `b`. + * + * @since Always. */ int strncmp(const char*, const char*, size_t) __GCC_ONLY(__attribute__((__warn_unused_result__, __nonnull__, __pure__))); @@ -803,6 +887,8 @@ int strverscmp(const char*, const char*) * @param size The size of the memory segment. * @return Pointer to the first occurrence of `c`, * `NULL` if none were found. + * + * @since Always. */ void* memchr(const void*, int, size_t) __GCC_ONLY(__attribute__((__warn_unused_result__, __pure__))); @@ -821,6 +907,8 @@ void* memchr(const void*, int, size_t) * @param segment The memory segment to search. * @param c The sought after character. * @return Pointer to the first occurrence of `c`. + * + * @since Always. */ void* rawmemchr(const void*, int) __GCC_ONLY(__attribute__((__warn_unused_result__, __returns_nonnull__, __nonnull__, __pure__))); @@ -841,6 +929,8 @@ void* rawmemchr(const void*, int) * @param size The size of the memory segment. * @return Pointer to the last occurrence of `c`, * `NULL` if none were found. + * + * @since Always. */ void* memrchr(const void*, int, size_t) __GCC_ONLY(__attribute__((__warn_unused_result__, __pure__))); @@ -860,6 +950,8 @@ void* memrchr(const void*, int, size_t) * @param c The sought after character. * @return Pointer to the first occurrence of `c`, * `NULL` if none were found. + * + * @since Always. */ char* strchr(const char*, int) __GCC_ONLY(__attribute__((__warn_unused_result__, __nonnull__, __pure__))); @@ -881,6 +973,8 @@ char* strchr(const char*, int) * @return Pointer to the first occurrence of `c`, * Pointer to the terminating NUL character * if none were found. + * + * @since Always. */ char* strchrnul(const char*, int) __GCC_ONLY(__attribute__((__warn_unused_result__, __returns_nonnull__, __nonnull__, __pure__))); @@ -902,6 +996,8 @@ char* strchrnul(const char*, int) * @param c The sought after character. * @return Pointer to the last occurrence of `c`, * `NULL` if none were found. + * + * @since Always. */ char* strrchr(const char*, int) __GCC_ONLY(__attribute__((__warn_unused_result__, __nonnull__, __pure__))); @@ -918,6 +1014,8 @@ char* strrchr(const char*, int) * @param needle The sought after substring. * @return Pointer to the first occurrence of the * substring, `NULL` if not found. + * + * @since Always. */ char* strstr(const char*, const char*) __GCC_ONLY(__attribute__((__warn_unused_result__, __nonnull__, __pure__))); @@ -933,6 +1031,8 @@ char* strstr(const char*, const char*) * @param needle The sought after substring. * @return Pointer to the first occurrence of the * substring, `NULL` if not found. + * + * @since Always. */ char* strcasestr(const char*, const char*) __GCC_ONLY(__attribute__((__warn_unused_result__, __nonnull__, __pure__))); @@ -953,6 +1053,8 @@ char* strcasestr(const char*, const char*) * @param maxlen The maximum number of character to search. * @return Pointer to the first occurrence of the * substring, `NULL` if not found. + * + * @since Always. */ char* strnstr(const char*, const char*, size_t) __GCC_ONLY(__attribute__((__warn_unused_result__, __nonnull__, __pure__))); @@ -971,6 +1073,8 @@ char* strnstr(const char*, const char*, size_t) * @param maxlen The maximum number of character to search. * @return Pointer to the first occurrence of the * substring, `NULL` if not found. + * + * @since Always. */ char* strncasestr(const char*, const char*, size_t) __GCC_ONLY(__attribute__((__warn_unused_result__, __nonnull__, __pure__))); @@ -988,6 +1092,8 @@ char* strncasestr(const char*, const char*, size_t) * @param haystack The string to search. * @param needle The sought after substring. * @return Pointer to the first occurrence of the substring. + * + * @since Always. */ char* rawstrstr(const char*, const char*) __GCC_ONLY(__attribute__((__warn_unused_result__, __nonnull__, __returns_nonnull__, __pure__))); @@ -1005,6 +1111,8 @@ char* rawstrstr(const char*, const char*) * @param haystack The string to search. * @param needle The sought after substring. * @return Pointer to the first occurrence of the substring. + * + * @since Always. */ char* rawstrcasestr(const char*, const char*) __GCC_ONLY(__attribute__((__warn_unused_result__, __nonnull__, __returns_nonnull__, __pure__))); @@ -1025,6 +1133,8 @@ char* rawstrcasestr(const char*, const char*) * @param needle_length The length of `needle`. * @return Pointer to the first occurrence of * the substring, `NULL` if not found. + * + * @since Always. */ void* memcasemem(const void*, size_t, const void*, size_t) __GCC_ONLY(__attribute__((__warn_unused_result__, __pure__))); @@ -1042,6 +1152,8 @@ void* memcasemem(const void*, size_t, const void*, size_t) * @param desired The desired beginning of the string. * @return `string` if `string` begins with * `desired`, `NULL` otherwise. + * + * @since Always. */ char* strstarts(const char*, const char*) __GCC_ONLY(__attribute__((__warn_unused_result__, __nonnull__, __pure__))); @@ -1059,6 +1171,8 @@ char* strstarts(const char*, const char*) * @param desired The desired ending of the string. * @return The `string`, where `desired` beings if * `string` ends with `desired`, `NULL` otherwise. + * + * @since Always. */ char* strends(const char*, const char*) __GCC_ONLY(__attribute__((__warn_unused_result__, __nonnull__, __pure__))); @@ -1076,6 +1190,8 @@ char* strends(const char*, const char*) * @param desired The desired beginning of the string. * @return `string` if `string` begins with * `desired`, `NULL` otherwise. + * + * @since Always. */ char* strcasestarts(const char*, const char*) __GCC_ONLY(__attribute__((__warn_unused_result__, __nonnull__, __pure__))); @@ -1093,6 +1209,8 @@ char* strcasestarts(const char*, const char*) * @param desired The desired ending of the string. * @return The `string`, where `desired` beings if * `string` ends with `desired`, `NULL` otherwise. + * + * @since Always. */ char* strcaseends(const char*, const char*) __GCC_ONLY(__attribute__((__warn_unused_result__, __nonnull__, __pure__))); @@ -1115,6 +1233,8 @@ char* strcaseends(const char*, const char*) * @param needle_length The length of `needle`. * @return Pointer to the first occurrence of * the substring, `NULL` if not found. + * + * @since Always. */ void* memmem(const void*, size_t, const void*, size_t) __GCC_ONLY(__attribute__((__warn_unused_result__, __pure__))); @@ -1135,6 +1255,8 @@ void* memmem(const void*, size_t, const void*, size_t) * @param string The string. * @param skipset Bytes allowed in the substring. * @return The length of the substring. + * + * @since Always. */ size_t strspn(const char*, const char*) __GCC_ONLY(__attribute__((__warn_unused_result__, __nonnull__, __pure__))); @@ -1147,6 +1269,8 @@ size_t strspn(const char*, const char*) * @param string The string. * @param stopset Bytes disallowed in the substring. * @return The length of the substring. + * + * @since Always. */ size_t strcspn(const char*, const char*) __GCC_ONLY(__attribute__((__warn_unused_result__, __nonnull__, __pure__))); @@ -1162,6 +1286,8 @@ size_t strcspn(const char*, const char*) * @return A pointer to the first occurrence in * `string` of a byte found in `stopset`. * `NULL` is returned if none is found. + * + * @since Always. */ char* strpbrk(const char*, const char*) __GCC_ONLY(__attribute__((__warn_unused_result__, __nonnull__, __pure__))); @@ -1184,6 +1310,8 @@ char* strpbrk(const char*, const char*) * `NULL` is returned the search as reached * the end of the string, and there therefore * are no more tokens. + * + * @since Always. */ char* strtok(char* restrict, const char* restrict) __GCC_ONLY(__attribute__((__warn_unused_result__, __nonnull__(2)))); @@ -1206,6 +1334,8 @@ char* strtok(char* restrict, const char* restrict) * `NULL` is returned the search as reached * the end of the string, and there therefore * are no more tokens. + * + * @since Always. */ char* strtok_r(char* restrict, const char* restrict, char** restrict) __GCC_ONLY(__attribute__((__warn_unused_result__, __nonnull__(2, 3)))); @@ -1224,6 +1354,8 @@ char* strtok_r(char* restrict, const char* restrict, char** restrict) * `NULL` is returned the search as reached * the end of the string, and there therefore * are no more tokens. + * + * @since Always. */ char* strsep(char** restrict, const char* restrict) __GCC_ONLY(__attribute__((__warn_unused_result__, __nonnull__))); @@ -1241,6 +1373,8 @@ char* strsep(char** restrict, const char* restrict) * of `filename` or, if `filename` is `NULL` * or is empty, a statically allocationed string, * so it must not freed or edited. + * + * @since Always. */ char* __gnu_basename(const char*) __GCC_ONLY(__attribute__((__warn_unused_result__, __pure__))); @@ -1257,6 +1391,8 @@ char* __gnu_basename(const char*) * * @param anagram An anagram of the output, will be modified. * @retrun The string, which will `== anagram`. + * + * @since Always. */ char* strfry(char*); @@ -1269,6 +1405,8 @@ char* strfry(char*); * @param segment The memory segment. * @param size The size of the memory segment. * @return `segment` is returned + * + * @since Always. */ char* memfrob(char*, size_t); #endif diff --git a/include/strings.h b/include/strings.h index adb8e97..31bb5a7 100644 --- a/include/strings.h +++ b/include/strings.h @@ -35,6 +35,8 @@ * * @param segment The memory segment to override. * @param size The size of the memory segment. + * + * @since Always. */ void bzero(void*, size_t) __deprecated("Use 'memset', 'explicit_bzero' or 'secure_free' instead."); @@ -50,6 +52,8 @@ void bzero(void*, size_t) * * @param segment The memory segment to override. * @param size The size of the memory segment. + * + * @since Always. */ void explicit_bzero(void*, size_t); #endif @@ -62,6 +66,8 @@ void explicit_bzero(void*, size_t); * @param whence The source memory segment. * @param whither The destination memory segment. * @param size The number of bytes to copy. + * + * @since Always. */ void bcopy(const void*, void*, size_t) __deprecated("Use 'memmove', or similar function, instead, but be aware of reordered parameters."); @@ -70,6 +76,8 @@ void bcopy(const void*, void*, size_t) * This function is identical to `memcmp`. * * @etymology (B)uffer: (c)o(mp)are. + * + * @since Always. */ int bcmp(const void*, const void*, size_t) __deprecated("Use 'memcmp' instead.") @@ -87,6 +95,8 @@ int bcmp(const void*, const void*, size_t) * @param b A positive value is returned if this is the lesser. * @return Zero is returned if `a` and `b` are equal, otherwise, * see the specifications for `a` and `b`. + * + * @since Always. */ int strcasecmp(const char*, const char*) __GCC_ONLY(__attribute__((__warn_unused_result__, __nonnull__, __pure__))); @@ -103,6 +113,8 @@ int strcasecmp(const char*, const char*) * @param length The maximum number of characters to compare. * @return Zero is returned if `a` and `b` are equal, otherwise, * see the specifications for `a` and `b`. + * + * @since Always. */ int strncasecmp(const char*, const char*, size_t) __GCC_ONLY(__attribute__((__warn_unused_result__, __nonnull__, __pure__))); @@ -120,6 +132,8 @@ int strncasecmp(const char*, const char*, size_t) * @param locale The locale. * @return Zero is returned if `a` and `b` are equal, otherwise, * see the specifications for `a` and `b`. + * + * @since Always. */ int strcasecmp_l(const char*, const char*, locale_t) /* TODO */ __GCC_ONLY(__attribute__((__warn_unused_result__, __nonnull__, __pure__))); @@ -137,6 +151,8 @@ int strcasecmp_l(const char*, const char*, locale_t) /* TODO */ * @param locale The locale. * @return Zero is returned if `a` and `b` are equal, otherwise, * see the specifications for `a` and `b`. + * + * @since Always. */ int strncasecmp_l(const char*, const char*, size_t, locale_t) /* TODO */ __GCC_ONLY(__attribute__((__warn_unused_result__, __nonnull__, __pure__))); @@ -148,6 +164,8 @@ int strncasecmp_l(const char*, const char*, size_t, locale_t) /* TODO */ * This is a deprecated BSD extension. * * @etymology (Index) of character. + * + * @since Always. */ char* index(const char*, int) __deprecated("Use 'strchr' instead.") @@ -162,6 +180,8 @@ char* index(const char*, int) * This is a deprecated BSD extension. * * @etymology (R)ight-most (index) of character. + * + * @since Always. */ char* rindex(const char*, int) __deprecated("Use 'strrchr' instead.") @@ -178,6 +198,8 @@ char* rindex(const char*, int) * * @param i The integer. * @return The value of the least significant set bit, zero if none. + * + * @since Always. */ int ffs(int) __GCC_ONLY(__attribute__((__warn_unused_result__, __const__))); @@ -189,6 +211,8 @@ int ffs(int) * * @param i The integer. * @return The value of the least significant set bit, zero if none. + * + * @since Always. */ int ffsl(long) __GCC_ONLY(__attribute__((__warn_unused_result__, __const__))); @@ -200,6 +224,8 @@ int ffsl(long) * * @param i The integer. * @return The value of the least significant set bit, zero if none. + * + * @since Always. */ int ffsll(long long) __GCC_ONLY(__attribute__((__warn_unused_result__, __const__))); diff --git a/include/sys/stat.h b/include/sys/stat.h index da67678..58b0514 100644 --- a/include/sys/stat.h +++ b/include/sys/stat.h @@ -23,9 +23,21 @@ #if defined(__SLIBC_SOURCE) +/** + * @since Always. + */ # define S_IRALL (S_IRUSR | S_IRGRP | S_IROTH) +/** + * @since Always. + */ # define S_IWALL (S_IWUSR | S_IWGRP | S_IWOTH) +/** + * @since Always. + */ # define S_IXALL (S_IXUSR | S_IXGRP | S_IXOTH) +/** + * @since Always. + */ # define S_ISALL (S_ISUID | S_ISGID | S_ISVTX) #endif diff --git a/include/unistd.h b/include/unistd.h index 87f2c64..47db049 100644 --- a/include/unistd.h +++ b/include/unistd.h @@ -47,6 +47,8 @@ * The file with input. * * @etymology (St)andar(d) (in)put (file)descriptor (number). + * + * @since Always. */ #define STDIN_FILENO 0 @@ -55,6 +57,8 @@ * The file for output. * * @etymology (St)andar(d) (out)put (file)descriptor (number). + * + * @since Always. */ #define STDOUT_FILENO 1 @@ -63,6 +67,8 @@ * The file for error messages and warnings. * * @etymology (St)andar(d) (err)or output (file)descriptor (number). + * + * @since Always. */ #define STDERR_FILENO 2 @@ -108,6 +114,8 @@ * have been exceeded, RAM and swap memory would * have been exhausted, or the request would cause * the data segment to overlap another segment. + * + * @since Always. */ int brk(void*) /* TODO implement brk */ __GCC_ONLY(__attribute__((__warn_unused_result__))); @@ -145,6 +153,8 @@ int brk(void*) /* TODO implement brk */ * have been exceeded, RAM and swap memory would * have been exhausted, or the request would cause * the data segment to overlap another segment. + * + * @since Always. */ void* sbrk(ptrdiff_t) /* TODO implement sbrk */ __GCC_ONLY(__attribute__((__warn_unused_result__))); @@ -173,6 +183,8 @@ int isatty(int); * set to describe the error. * * @throws Any error specified for execve(2). + * + * @since Always. */ int execl(const char*, ... /*, NULL */) __GCC_ONLY(__attribute__((__sentinel__(0), __nonnull__(1)))); @@ -194,6 +206,8 @@ int execl(const char*, ... /*, NULL */) * set to describe the error. * * @throws Any error specified for execve(2). + * + * @since Always. */ int execlp(const char*, ... /*, NULL */) __GCC_ONLY(__attribute__((__sentinel__(0), __nonnull__(1)))); @@ -215,6 +229,8 @@ int execlp(const char*, ... /*, NULL */) * set to describe the error. * * @throws Any error specified for execve(2). + * + * @since Always. */ int execle(const char*, ... /*, NULL, char* const[] */) __GCC_ONLY(__attribute__((__sentinel__(1), __nonnull__(1)))); @@ -243,6 +259,8 @@ int execle(const char*, ... /*, NULL, char* const[] */) * set to describe the error. * * @throws Any error specified for execve(2). + * + * @since Always. */ int execlpe(const char*, ... /*, NULL, char* const[] */) __GCC_ONLY(__attribute__((__sentinel__(1), __nonnull__(1)))); @@ -265,6 +283,8 @@ int execlpe(const char*, ... /*, NULL, char* const[] */) * set to describe the error. * * @throws Any error specified for execve(2). + * + * @since Always. */ int execv(const char*, char* const[]) __GCC_ONLY(__attribute__((__nonnull__(1)))); @@ -290,6 +310,8 @@ int execv(const char*, char* const[]) * set to describe the error. * * @throws Any error specified for execve(2). + * + * @since Always. */ int execvp(const char*, char* const[]) __GCC_ONLY(__attribute__((__nonnull__(1)))); @@ -315,6 +337,8 @@ int execvp(const char*, char* const[]) * set to describe the error. * * @throws Any error specified for execve(2). + * + * @since Always. */ int execve(const char*, char* const[], char* const[]) __GCC_ONLY(__attribute__((__nonnull__(1)))); @@ -347,6 +371,8 @@ int execve(const char*, char* const[], char* const[]) * set to describe the error. * * @throws Any error specified for execve(2). + * + * @since Always. */ int execvpe(const char*, char* const[], char* const[]) __GCC_ONLY(__attribute__((__nonnull__(1)))); @@ -382,6 +408,8 @@ int execvpe(const char*, char* const[], char* const[]) * set to describe the error. * * @throws Any error specified for execveat(2). + * + * @since Always. */ int execlat(int, const char*, ... /*, NULL, int */) __GCC_ONLY(__attribute__((__sentinel__(1), __nonnull__(2)))); @@ -418,6 +446,8 @@ int execlat(int, const char*, ... /*, NULL, int */) * set to describe the error. * * @throws Any error specified for execveat(2). + * + * @since Always. */ int execlpat(int, const char*, ... /*, NULL, int */) __GCC_ONLY(__attribute__((__sentinel__(1), __nonnull__(2)))); @@ -454,6 +484,8 @@ int execlpat(int, const char*, ... /*, NULL, int */) * set to describe the error. * * @throws Any error specified for execveat(2). + * + * @since Always. */ int execleat(int, const char*, ... /*, NULL, char* const[], int */) __GCC_ONLY(__attribute__((__sentinel__(2), __nonnull__(2)))); @@ -494,6 +526,8 @@ int execleat(int, const char*, ... /*, NULL, char* const[], int */) * set to describe the error. * * @throws Any error specified for execveat(2). + * + * @since Always. */ int execlpeat(int, const char*, ... /*, NULL, char* const[], int */) __GCC_ONLY(__attribute__((__sentinel__(2), __nonnull__(2)))); @@ -530,6 +564,8 @@ int execlpeat(int, const char*, ... /*, NULL, char* const[], int */) * set to describe the error. * * @throws Any error specified for execveat(2). + * + * @since Always. */ int execvat(int, const char*, char* const[], int) __GCC_ONLY(__attribute__((__nonnull__(2)))); @@ -570,6 +606,8 @@ int execvat(int, const char*, char* const[], int) * set to describe the error. * * @throws Any error specified for execveat(2). + * + * @since Always. */ int execvpat(int, const char*, char* const[], int) __GCC_ONLY(__attribute__((__nonnull__(2)))); @@ -609,6 +647,8 @@ int execvpat(int, const char*, char* const[], int) * set to describe the error. * * @throws Any error specified for execveat(2). + * + * @since Always. */ int execveat(int, const char*, char* const[], char* const[], int) __GCC_ONLY(__attribute__((__nonnull__(2)))); @@ -654,6 +694,8 @@ int execveat(int, const char*, char* const[], char* const[], int) * set to describe the error. * * @throws Any error specified for execveat(2). + * + * @since Always. */ int execvpeat(int, const char*, char* const[], char* const[], int) __GCC_ONLY(__attribute__((__nonnull__(2)))); @@ -676,6 +718,8 @@ int execvpeat(int, const char*, char* const[], char* const[], int) * set to describe the error. * * @throws Any error specified for execve(2). + * + * @since Always. */ int fexecl(int, ... /*, NULL */) __GCC_ONLY(__attribute__((__sentinel__(0)))); @@ -699,6 +743,8 @@ int fexecl(int, ... /*, NULL */) * set to describe the error. * * @throws Any error specified for execve(2). + * + * @since Always. */ int fexecle(int, ... /*, NULL, char* const[] */) __GCC_ONLY(__attribute__((__sentinel__(1)))); @@ -722,6 +768,8 @@ int fexecle(int, ... /*, NULL, char* const[] */) * set to describe the error. * * @throws Any error specified for execve(2). + * + * @since Always. */ int fexecv(int, char* const[]); #endif @@ -747,6 +795,8 @@ int fexecv(int, char* const[]); * set to describe the error. * * @throws Any error specified for execve(2). + * + * @since Always. */ int fexecve(int, char* const[], char* const[]); diff --git a/include/wchar.h b/include/wchar.h index b705510..5f5d734 100644 --- a/include/wchar.h +++ b/include/wchar.h @@ -62,6 +62,8 @@ * @param str The string. * @return The number of `wchar_t`:s before the * first NUL character. + * + * @since Always. */ size_t wcslen(const wchar_t*) __GCC_ONLY(__attribute__((__nonnull__, __warn_unused_result__, __pure__))); @@ -74,6 +76,8 @@ size_t wcslen(const wchar_t*) * @return The number of `wchar_t`:s before the * first NUL character. `maxlen` if no * NUL character was found. + * + * @since Always. */ size_t wcsnlen(const wchar_t*, size_t) __GCC_ONLY(__attribute__((__warn_unused_result__, __pure__))); @@ -87,6 +91,8 @@ size_t wcsnlen(const wchar_t*, size_t) * @param c The wide character. * @param size The number of wide characters in the memory segment. * @return `segment` is returned. + * + * @since Always. */ wchar_t* wmemset(wchar_t*, wchar_t, size_t); @@ -97,6 +103,8 @@ wchar_t* wmemset(wchar_t*, wchar_t, size_t); * @param whence The source memory segment. * @param size The number of wide characters to copy. * @return `whither` is returned. + * + * @since Always. */ wchar_t* wmemcpy(wchar_t* restrict, const wchar_t* restrict, size_t); @@ -110,6 +118,8 @@ wchar_t* wmemcpy(wchar_t* restrict, const wchar_t* restrict, size_t); * @param whence The source memory segment. * @param size The number of wide characters to copy. * @return `whither + size` is returned. + * + * @since Always. */ wchar_t* wmempcpy(wchar_t* restrict, const wchar_t* restrict, size_t); @@ -122,6 +132,8 @@ wchar_t* wmempcpy(wchar_t* restrict, const wchar_t* restrict, size_t); * @param whence The source memory segment. * @param size The number of wide characters to copy. * @return `whither` is returned. + * + * @since Always. */ wchar_t* wmemmove(wchar_t*, const wchar_t*, size_t); @@ -136,6 +148,8 @@ wchar_t* wmemmove(wchar_t*, const wchar_t*, size_t); * @param whence The source memory segment. * @param size The number of wide characters to copy. * @return `whither + size` is returned. + * + * @since Always. */ wchar_t* wmempmove(wchar_t*, const wchar_t*, size_t); # endif @@ -157,6 +171,8 @@ wchar_t* wmempmove(wchar_t*, const wchar_t*, size_t); * that is, the address of `whither` plus the * number of copied characters; the address of * one character passed the last written character. + * + * @since Always. */ wchar_t* wmemccpy(wchar_t* restrict, const wchar_t* restrict, wchar_t, size_t); @@ -175,6 +191,8 @@ wchar_t* wmemccpy(wchar_t* restrict, const wchar_t* restrict, wchar_t, size_t); * that is, the address of `whither` plus the * number of copied characters; the address of * one character passed the last written character. + * + * @since Always. */ wchar_t* wmemcmove(wchar_t*, const wchar_t*, wchar_t, size_t); @@ -187,6 +205,8 @@ wchar_t* wmemcmove(wchar_t*, const wchar_t*, wchar_t, size_t); * @param str The beginning of the memory segment. * @param c The wide character. * @return `str` is returned. + * + * @since Always. */ wchar_t* wcsset(wchar_t*, wchar_t) __GCC_ONLY(__attribute__((__returns_nonnull__, __nonnull__))); @@ -199,6 +219,8 @@ wchar_t* wcsset(wchar_t*, wchar_t) * @param whither The destination memory segment. * @param whence The source memory segment. * @return `whither` is returned. + * + * @since Always. */ wchar_t* wcscpy(wchar_t* restrict, const wchar_t* restrict) __GCC_ONLY(__attribute__((__returns_nonnull__, __nonnull__))); @@ -213,6 +235,8 @@ wchar_t* wcscpy(wchar_t* restrict, const wchar_t* restrict) * @param whither The destination memory segment. * @param whence The source memory segment. * @return `whither + wcslen(whence)` is returned. + * + * @since Always. */ wchar_t* wcpcpy(wchar_t* restrict, const wchar_t* restrict) __GCC_ONLY(__attribute__((__returns_nonnull__, __nonnull__))); @@ -235,6 +259,8 @@ wchar_t* wcpcpy(wchar_t* restrict, const wchar_t* restrict) * number of copied characters; the address of * one character passed the last written non-NUL * character. + * + * @since Always. */ wchar_t* wcsccpy(wchar_t* restrict, const wchar_t* restrict, wchar_t) __GCC_ONLY(__attribute__((__nonnull__))); @@ -254,6 +280,8 @@ wchar_t* wcsccpy(wchar_t* restrict, const wchar_t* restrict, wchar_t) * number of copied characters; the address of * one character passed the last written non-NUL * character. + * + * @since Always. */ wchar_t* wcsstrcpy(wchar_t* restrict, const wchar_t* restrict, const wchar_t* restrict) __GCC_ONLY(__attribute__((__nonnull__(1, 2)))); @@ -272,6 +300,8 @@ wchar_t* wcsstrcpy(wchar_t* restrict, const wchar_t* restrict, const wchar_t* re * shorter, `whither` will be filled with NUL characters * until this amount of characters have been written. * @return `whither` is returned. + * + * @since Always. */ wchar_t* wcsncpy(wchar_t* restrict, const wchar_t* restrict, size_t) __GCC_ONLY(__attribute__((__returns_nonnull__, __nonnull__))); @@ -293,6 +323,8 @@ wchar_t* wcsncpy(wchar_t* restrict, const wchar_t* restrict, size_t) * until this amount of characters have been written. * @return `whither` plus the number of written characters, * excluding NUL characters, is returned. + * + * @since Always. */ wchar_t* wcpncpy(wchar_t* restrict, const wchar_t* restrict, size_t) __GCC_ONLY(__attribute__((__returns_nonnull__, __nonnull__))); @@ -321,6 +353,8 @@ wchar_t* wcpncpy(wchar_t* restrict, const wchar_t* restrict, size_t) * number of copied characters; the address of * one character passed the last written non-NUL * character. + * + * @since Always. */ wchar_t* wcscncpy(wchar_t* restrict, const wchar_t* restrict, wchar_t, size_t) __GCC_ONLY(__attribute__((__nonnull__))); @@ -347,6 +381,8 @@ wchar_t* wcscncpy(wchar_t* restrict, const wchar_t* restrict, wchar_t, size_t) * number of copied chartacters; the address of * one character passed the last written non-NUL * character. + * + * @since Always. */ wchar_t* wcsstrncpy(wchar_t* restrict, const wchar_t* restrict, const wchar_t* restrict, size_t) __GCC_ONLY(__attribute__((__nonnull__(1, 2)))); @@ -363,6 +399,8 @@ wchar_t* wcsstrncpy(wchar_t* restrict, const wchar_t* restrict, const wchar_t* r * @param whither The destination memory segment. * @param whence The source memory segment. * @return `whither` is returned. + * + * @since Always. */ wchar_t* wcsmove(wchar_t*, const wchar_t*) __GCC_ONLY(__attribute__((__returns_nonnull__, __nonnull__))); @@ -376,6 +414,8 @@ wchar_t* wcsmove(wchar_t*, const wchar_t*) * @param whither The destination memory segment. * @param whence The source memory segment. * @return `whither + wcslen(whence)` is returned. + * + * @since Always. */ wchar_t* wcpmove(wchar_t*, const wchar_t*) __GCC_ONLY(__attribute__((__returns_nonnull__, __nonnull__))); @@ -396,6 +436,8 @@ wchar_t* wcpmove(wchar_t*, const wchar_t*) * number of copied characters; the address of * one character passed the last written non-NUL * character. + * + * @since Always. */ wchar_t* wcscmove(wchar_t*, const wchar_t*, wchar_t) __GCC_ONLY(__attribute__((__nonnull__))); @@ -415,6 +457,8 @@ wchar_t* wcscmove(wchar_t*, const wchar_t*, wchar_t) * number of copied characters; the address of * one character passed the last written non-NUL * character. + * + * @since Always. */ wchar_t* wcsstrmove(wchar_t*, const wchar_t*, const wchar_t* restrict) __GCC_ONLY(__attribute__((__nonnull__(1, 2)))); @@ -434,6 +478,8 @@ wchar_t* wcsstrmove(wchar_t*, const wchar_t*, const wchar_t* restrict) * shorter, `whither` will be filled with NUL characters * until this amount of characters have been written. * @return `whither` is returned. + * + * @since Always. */ wchar_t* wcsnmove(wchar_t*, const wchar_t*, size_t) __GCC_ONLY(__attribute__((__returns_nonnull__, __nonnull__))); @@ -456,6 +502,8 @@ wchar_t* wcsnmove(wchar_t*, const wchar_t*, size_t) * until this amount of characters have been written. * @return `whither` plus the number of written characters, * excluding NUL characters, is returned. + * + * @since Always. */ wchar_t* wcpnmove(wchar_t*, const wchar_t*, size_t) __GCC_ONLY(__attribute__((__returns_nonnull__, __nonnull__))); @@ -483,6 +531,8 @@ wchar_t* wcpnmove(wchar_t*, const wchar_t*, size_t) * number of copied characters; the address of * one character passed the last written non-NUL * character. + * + * @since Always. */ wchar_t* wcscnmove(wchar_t*, const wchar_t*, wchar_t, size_t) __GCC_ONLY(__attribute__((__nonnull__))); @@ -509,6 +559,8 @@ wchar_t* wcscnmove(wchar_t*, const wchar_t*, wchar_t, size_t) * number of copied chartacters; the address of * one character passed the last written non-NUL * character. + * + * @since Always. */ wchar_t* wcsstrnmove(wchar_t*, const wchar_t*, const wchar_t* restrict, size_t) __GCC_ONLY(__attribute__((__nonnull__(1, 2)))); @@ -524,6 +576,8 @@ wchar_t* wcsstrnmove(wchar_t*, const wchar_t*, const wchar_t* restrict, size_t) * @param whither The string to extend. * @param whence The string to append. * @return `whither` is returned. + * + * @since Always. */ wchar_t* wcscat(wchar_t* restrict whither, const wchar_t* restrict whence) __GCC_ONLY(__attribute__((__nonnull__))); @@ -545,6 +599,8 @@ wchar_t* wcscat(wchar_t* restrict whither, const wchar_t* restrict whence) * shorter, `whither` will be filled with NUL characters * until this amount of characters have been written. * @return `whither` is returned. + * + * @since Always. */ wchar_t* wcsncat(wchar_t* restrict whither, const wchar_t* restrict whence, size_t maxlen) __GCC_ONLY(__attribute__((__nonnull__))); @@ -563,6 +619,8 @@ wchar_t* wcsncat(wchar_t* restrict whither, const wchar_t* restrict whence, size * and `errno` is set to indicate the error. * * @throws ENOMEM The process could not allocate sufficient amount of memory. + * + * @since Always. */ wchar_t* wcsdup(const wchar_t*) __GCC_ONLY(__attribute__((__malloc__, __nonnull__, __warn_unused_result__))); @@ -584,6 +642,8 @@ wchar_t* wcsdup(const wchar_t*) * and `errno` is set to indicate the error. * * @throws ENOMEM The process could not allocate sufficient amount of memory. + * + * @since Always. */ wchar_t* wcsndup(const wchar_t*, size_t) __GCC_ONLY(__attribute__((__malloc__, __nonnull__, __warn_unused_result__))); @@ -600,6 +660,8 @@ wchar_t* wcsndup(const wchar_t*, size_t) * and `errno` is set to indicate the error. * * @throws ENOMEM The process could not allocate sufficient amount of memory. + * + * @since Always. */ wchar_t* wmemdup(const wchar_t*, size_t) __GCC_ONLY(__attribute__((__malloc__, __nonnull__, __warn_unused_result__))); @@ -616,6 +678,8 @@ wchar_t* wmemdup(const wchar_t*, size_t) * @param string:const wchar_t* The string to duplicate. * @return :size_t The new string. There is no way to * detect whether the allocation failed. + * + * @since Always. */ # define wcsdupa(string) \ ({ \ @@ -637,6 +701,8 @@ wchar_t* wmemdup(const wchar_t*, size_t) * A NUL byte is guaranteed to always be written. * @return :size_t The new string. There is no way to * detect whether the allocation failed. + * + * @since Always. */ # define wstrndupa(string, maxlen) \ ({ \ @@ -657,6 +723,8 @@ wchar_t* wmemdup(const wchar_t*, size_t) * @param size:size_t The size of the memory segment. * @return :size_t The new segment. There is no way to * detect whether the allocation failed. + * + * @since Always. */ # define wmemdupa(segment, size) \ ({ \ @@ -677,6 +745,8 @@ wchar_t* wmemdup(const wchar_t*, size_t) * @param size The size of the segments. * @return Zero is returned if `a` and `b` are equal, otherwise, * see the specifications for `a` and `b`. + * + * @since Always. */ int wmemcmp(const wchar_t*, const wchar_t*, size_t) __GCC_ONLY(__attribute__((__warn_unused_result__, __pure__))); @@ -693,6 +763,8 @@ int wmemcmp(const wchar_t*, const wchar_t*, size_t) * @param size The size of the segments. * @return Zero is returned if `a` and `b` are equal, otherwise, * see the specifications for `a` and `b`. + * + * @since Always. */ int wmemcasecmp(const wchar_t*, const wchar_t*, size_t) __GCC_ONLY(__attribute__((__warn_unused_result__, __pure__))); @@ -705,6 +777,8 @@ int wmemcasecmp(const wchar_t*, const wchar_t*, size_t) * @param b A positive value is returned if this is the lesser. * @return Zero is returned if `a` and `b` are equal, otherwise, * see the specifications for `a` and `b`. + * + * @since Always. */ int wcscmp(const wchar_t*, const wchar_t*) __GCC_ONLY(__attribute__((__warn_unused_result__, __nonnull__, __pure__))); @@ -721,6 +795,8 @@ int wcscmp(const wchar_t*, const wchar_t*) * @param b A positive value is returned if this is the lesser. * @return Zero is returned if `a` and `b` are equal, otherwise, * see the specifications for `a` and `b`. + * + * @since Always. */ int wcscasecmp(const wchar_t*, const wchar_t*) __GCC_ONLY(__attribute__((__warn_unused_result__, __nonnull__, __pure__))); @@ -735,6 +811,8 @@ int wcscasecmp(const wchar_t*, const wchar_t*) * @param length The maximum number of characters to compare. * @return Zero is returned if `a` and `b` are equal, otherwise, * see the specifications for `a` and `b`. + * + * @since Always. */ int wcsncmp(const wchar_t*, const wchar_t*, size_t) __GCC_ONLY(__attribute__((__warn_unused_result__, __nonnull__, __pure__))); @@ -751,6 +829,8 @@ int wcsncmp(const wchar_t*, const wchar_t*, size_t) * @param length The maximum number of characters to compare. * @return Zero is returned if `a` and `b` are equal, otherwise, * see the specifications for `a` and `b`. + * + * @since Always. */ int wcsncasecmp(const wchar_t*, const wchar_t*, size_t) __GCC_ONLY(__attribute__((__warn_unused_result__, __nonnull__, __pure__))); @@ -766,6 +846,8 @@ int wcsncasecmp(const wchar_t*, const wchar_t*, size_t) * @param size The size of the memory segment. * @return Pointer to the first occurrence of `c`, * `NULL` if none were found. + * + * @since Always. */ wchar_t* wmemchr(const wchar_t*, wchar_t, size_t) __GCC_ONLY(__attribute__((__warn_unused_result__, __pure__))); @@ -784,6 +866,8 @@ wchar_t* wmemchr(const wchar_t*, wchar_t, size_t) * @param segment The memory segment to search. * @param c The sought after character. * @return Pointer to the first occurrence of `c`. + * + * @since Always. */ wchar_t* rawwmemchr(const wchar_t*, wchar_t) __GCC_ONLY(__attribute__((__warn_unused_result__, __returns_nonnull__, __nonnull__, __pure__))); @@ -806,6 +890,8 @@ wchar_t* rawwmemchr(const wchar_t*, wchar_t) * @param size The size of the memory segment. * @return Pointer to the last occurrence of `c`, * `NULL` if none were found. + * + * @since Always. */ wchar_t* wmemrchr(const wchar_t*, wchar_t, size_t) __GCC_ONLY(__attribute__((__warn_unused_result__, __pure__))); @@ -823,6 +909,8 @@ wchar_t* wmemrchr(const wchar_t*, wchar_t, size_t) * @param c The sought after character. * @return Pointer to the first occurrence of `c`, * `NULL` if none were found. + * + * @since Always. */ wchar_t* wcschr(const wchar_t*, wchar_t) __GCC_ONLY(__attribute__((__warn_unused_result__, __nonnull__, __pure__))); @@ -845,6 +933,8 @@ wchar_t* wcschr(const wchar_t*, wchar_t) * @return Pointer to the first occurrence of `c`, * Pointer to the terminating NUL character * if none were found. + * + * @since Always. */ wchar_t* wcschrnul(const wchar_t*, wchar_t) __GCC_ONLY(__attribute__((__warn_unused_result__, __returns_nonnull__, __nonnull__, __pure__))); @@ -866,6 +956,8 @@ wchar_t* wcschrnul(const wchar_t*, wchar_t) * @param c The sought after character. * @return Pointer to the last occurrence of `c`, * `NULL` if none were found. + * + * @since Always. */ wchar_t* wcsrchr(const wchar_t*, wchar_t) __GCC_ONLY(__attribute__((__warn_unused_result__, __nonnull__, __pure__))); @@ -876,6 +968,8 @@ wchar_t* wcsrchr(const wchar_t*, wchar_t) /** * This function is identical to `wcsstr`. + * + * @since Always. */ wchar_t* wcswcs(const wchar_t*, const wchar_t*) __GCC_ONLY(__attribute__((__warn_unused_result__, __nonnull__, __pure__))) @@ -892,6 +986,8 @@ wchar_t* wcswcs(const wchar_t*, const wchar_t*) * @param needle The sought after substring. * @return Pointer to the first occurrence of the * substring, `NULL` if not found. + * + * @since Always. */ wchar_t* wcsstr(const wchar_t*, const wchar_t*) __GCC_ONLY(__attribute__((__warn_unused_result__, __nonnull__, __pure__))); @@ -910,6 +1006,8 @@ wchar_t* wcsstr(const wchar_t*, const wchar_t*) * @param needle The sought after substring. * @return Pointer to the first occurrence of the * substring, `NULL` if not found. + * + * @since Always. */ wchar_t* wcscasestr(const wchar_t*, const wchar_t*) __GCC_ONLY(__attribute__((__warn_unused_result__, __nonnull__, __pure__))); @@ -929,6 +1027,8 @@ wchar_t* wcscasestr(const wchar_t*, const wchar_t*) * @param maxlen The maximum number of character to search. * @return Pointer to the first occurrence of the * substring, `NULL` if not found. + * + * @since Always. */ wchar_t* wcsnstr(const wchar_t*, const wchar_t*, size_t) __GCC_ONLY(__attribute__((__warn_unused_result__, __nonnull__, __pure__))); @@ -947,6 +1047,8 @@ wchar_t* wcsnstr(const wchar_t*, const wchar_t*, size_t) * @param maxlen The maximum number of character to search. * @return Pointer to the first occurrence of the * substring, `NULL` if not found. + * + * @since Always. */ wchar_t* wcsncasestr(const wchar_t*, const wchar_t*, size_t) __GCC_ONLY(__attribute__((__warn_unused_result__, __nonnull__, __pure__))); @@ -964,6 +1066,8 @@ wchar_t* wcsncasestr(const wchar_t*, const wchar_t*, size_t) * @param haystack The string to search. * @param needle The sought after substring. * @return Pointer to the first occurrence of the substring. + * + * @since Always. */ wchar_t* rawwcsstr(const wchar_t*, const wchar_t*) __GCC_ONLY(__attribute__((__warn_unused_result__, __nonnull__, __returns_nonnull__, __pure__))); @@ -981,6 +1085,8 @@ wchar_t* rawwcsstr(const wchar_t*, const wchar_t*) * @param haystack The string to search. * @param needle The sought after substring. * @return Pointer to the first occurrence of the substring. + * + * @since Always. */ wchar_t* rawwcscasestr(const wchar_t*, const wchar_t*) __GCC_ONLY(__attribute__((__warn_unused_result__, __nonnull__, __returns_nonnull__, __pure__))); @@ -1001,6 +1107,8 @@ wchar_t* rawwcscasestr(const wchar_t*, const wchar_t*) * @param needle_length The length of `needle`. * @return Pointer to the first occurrence of * the substring, `NULL` if not found. + * + * @since Always. */ wchar_t* wmemcasemem(const wchar_t*, size_t, const wchar_t*, size_t) __GCC_ONLY(__attribute__((__warn_unused_result__, __pure__))); @@ -1018,6 +1126,8 @@ wchar_t* wmemcasemem(const wchar_t*, size_t, const wchar_t*, size_t) * @param desired The desired beginning of the string. * @return `string` if `string` begins with * `desired`, `NULL` otherwise. + * + * @since Always. */ wchar_t* wcsstarts(const wchar_t*, const wchar_t*) __GCC_ONLY(__attribute__((__warn_unused_result__, __nonnull__, __pure__))); @@ -1035,6 +1145,8 @@ wchar_t* wcsstarts(const wchar_t*, const wchar_t*) * @param desired The desired ending of the string. * @return The `string`, where `desired` beings if * `string` ends with `desired`, `NULL` otherwise. + * + * @since Always. */ wchar_t* wcsends(const wchar_t*, const wchar_t*) __GCC_ONLY(__attribute__((__warn_unused_result__, __nonnull__, __pure__))); @@ -1052,6 +1164,8 @@ wchar_t* wcsends(const wchar_t*, const wchar_t*) * @param desired The desired beginning of the string. * @return `string` if `string` begins with * `desired`, `NULL` otherwise. + * + * @since Always. */ wchar_t* wcscasestarts(const wchar_t*, const wchar_t*) __GCC_ONLY(__attribute__((__warn_unused_result__, __nonnull__, __pure__))); @@ -1069,6 +1183,8 @@ wchar_t* wcscasestarts(const wchar_t*, const wchar_t*) * @param desired The desired ending of the string. * @return The `string`, where `desired` beings if * `string` ends with `desired`, `NULL` otherwise. + * + * @since Always. */ wchar_t* wcscaseends(const wchar_t*, const wchar_t*) __GCC_ONLY(__attribute__((__warn_unused_result__, __nonnull__, __pure__))); @@ -1092,6 +1208,8 @@ wchar_t* wcscaseends(const wchar_t*, const wchar_t*) * @param needle_length The length of `needle`. * @return Pointer to the first occurrence of * the substring, `NULL` if not found. + * + * @since Always. */ wchar_t* wmemmem(const wchar_t*, size_t, const wchar_t*, size_t) __GCC_ONLY(__attribute__((__warn_unused_result__, __pure__))); @@ -1112,6 +1230,8 @@ wchar_t* wmemmem(const wchar_t*, size_t, const wchar_t*, size_t) * @param string The string. * @param skipset Characters allowed in the substring. * @return The length of the substring. + * + * @since Always. */ size_t wcsspn(const wchar_t*, const wchar_t*) __GCC_ONLY(__attribute__((__warn_unused_result__, __nonnull__, __pure__))); @@ -1124,6 +1244,8 @@ size_t wcsspn(const wchar_t*, const wchar_t*) * @param string The string. * @param stopset Characters disallowed in the substring. * @return The length of the substring. + * + * @since Always. */ size_t wcscspn(const wchar_t*, const wchar_t*) __GCC_ONLY(__attribute__((__warn_unused_result__, __nonnull__, __pure__))); @@ -1139,6 +1261,8 @@ size_t wcscspn(const wchar_t*, const wchar_t*) * @return A pointer to the first occurrence in * `string` of a character found in `stopset`. * `NULL` is returned if none is found. + * + * @since Always. */ wchar_t* wcspbrk(const wchar_t*, const wchar_t*) __GCC_ONLY(__attribute__((__warn_unused_result__, __nonnull__, __pure__))); @@ -1165,6 +1289,8 @@ wchar_t* wcspbrk(const wchar_t*, const wchar_t*) * `NULL` is returned the search as reached * the end of the string, and there therefore * are no more tokens. + * + * @since Always. */ wchar_t* wcstok(wchar_t* restrict, const wchar_t* restrict, wchar_t** restrict) __GCC_ONLY(__attribute__((__warn_unused_result__, __nonnull__(2, 3)))); @@ -1186,6 +1312,8 @@ wchar_t* wcstok(wchar_t* restrict, const wchar_t* restrict, wchar_t** restrict) * `NULL` is returned the search as reached * the end of the string, and there therefore * are no more tokens. + * + * @since Always. */ wchar_t* wcssep(wchar_t** restrict, const wchar_t* restrict) __GCC_ONLY(__attribute__((__warn_unused_result__, __nonnull__))); -- cgit v1.2.3-70-g09d2