aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--doc/info/chap/error-reporting.texinfo6
-rw-r--r--doc/info/chap/language-facilities.texinfo67
-rw-r--r--doc/info/chap/memory-allocation.texinfo181
-rw-r--r--include/malloc.h24
-rw-r--r--include/slibc-alloc.h32
-rw-r--r--include/slibc-error.h2
-rw-r--r--include/slibc-human.h16
-rw-r--r--include/slibc-print.h18
-rw-r--r--include/stdalign.h4
-rw-r--r--include/stdarg.h10
-rw-r--r--include/stdbool.h2
-rw-r--r--include/stddef.h4
-rw-r--r--include/strings.h32
-rw-r--r--include/unistd.h10
-rw-r--r--src/malloc.c24
-rw-r--r--src/string/str/strcasecmp.c2
-rw-r--r--src/string/strn/strncasecmp.c2
-rw-r--r--src/strings/bcmp.c2
-rw-r--r--src/strings/bcopy.c2
-rw-r--r--src/strings/bzero.c2
-rw-r--r--src/strings/explicit_bzero.c2
-rw-r--r--src/strings/ffs.c4
-rw-r--r--src/strings/ffsl.c5
-rw-r--r--src/strings/ffsll.c4
-rw-r--r--src/strings/index.c2
-rw-r--r--src/strings/rindex.c2
26 files changed, 453 insertions, 8 deletions
diff --git a/doc/info/chap/error-reporting.texinfo b/doc/info/chap/error-reporting.texinfo
index ef7e81b..070e1bc 100644
--- a/doc/info/chap/error-reporting.texinfo
+++ b/doc/info/chap/error-reporting.texinfo
@@ -880,5 +880,11 @@ than the location and @code{error_string} should
be printed. It is followed by the formatting-arguments.
@end table
+@ifnottex
+Etymology: (@command{slibc})-enhancement of (@code{perror}).
+@end ifnottex
+@iftex
+Etymology: @b{slibc}-enhancement of @b{perror}.
+@end iftex
@end table
diff --git a/doc/info/chap/language-facilities.texinfo b/doc/info/chap/language-facilities.texinfo
index fe27446..61e74eb 100644
--- a/doc/info/chap/language-facilities.texinfo
+++ b/doc/info/chap/language-facilities.texinfo
@@ -112,6 +112,13 @@ is stored as 1, to avoid integer overflows,
that may occur when using @code{int}, and
not using @code{!!} when casting to @code{int}.
+@ifnottex
+Etymology: (Bool)ean.
+@end ifnottex
+@iftex
+Etymology: @b{Bool}ean.
+@end iftex
+
@item true
Has the value 1, and represents a true value.
@@ -197,6 +204,17 @@ should have the alignment of the type @code{TYPE}@.
The function call @code{alignof(TYPE)}, returns
the alignment of the type @code{TYPE}@.
+@ifnottex
+Etymology of @code{alignas}: (Align as) type.
+
+Etymology of @code{alignof}: (Align)ment (of) type.
+@end ifnottex
+@iftex
+Etymology of @code{alignas}: @b{Align as} type.
+
+Etymology of @code{alignof}: @b{Align}ment @b{of} type.
+@end iftex
+
@node Member offsets
@@ -233,6 +251,13 @@ structure has offset 0 and size 16. 0 + 16 = 16.
@code{offsetof} is also known to be problematic in C++,
because C++ supports redefining operators.
+@ifnottex
+Etymology: Address-(offset of) member.
+@end ifnottex
+@iftex
+Etymology: Address-@b{offset of} member.
+@end iftex
+
@node Variadic functions
@@ -256,16 +281,37 @@ data type and the three macro functions.
Data type that is used to traverse the non-fixed
arguments in a variadic function.
+@ifnottex
+Etymology: (V)ariadic (a)rguments-subsystem: argument-(list).
+@end ifnottex
+@iftex
+Etymology: @b{V}ariadic @b{a}rguments-subsystem: argument-@b{list}.
+@end iftex
+
@item void va_start(va_list @i{list}, @i{last})
Initialises a @code{va_list}, specified by the
first argument. The second argument must be the
last fixed argument.
+@ifnottex
+Etymology: (V)ariadic (a)rguments-subsystem: (start) of use.
+@end ifnottex
+@iftex
+Etymology: @b{V}ariadic @b{a}rguments-subsystem: @b{start} of use.
+@end iftex
+
@item void va_end(va_list @i{list})
Deallocates resources that was allocated by
@code{va_start}. The specified list, must not
be used after calling this macro.
+@ifnottex
+Etymology: (V)ariadic (a)rguments-subsystem: (end) of use.
+@end ifnottex
+@iftex
+Etymology: @b{V}ariadic @b{a}rguments-subsystem: @b{end} of use.
+@end iftex
+
@item @i{type} va_arg(va_list @i{list}, @i{type})
Returns the next argument, the specified type
must have the same width the argument hade in
@@ -276,6 +322,13 @@ or @code{short int} (or variant thereof), the
corresponding call to @code{va_arg} shall
specify @code{int} or a variant thereof (with
the same width as @code{int}.)
+
+@ifnottex
+Etymology: (V)ariadic (a)rguments-subsystem: get (arg)ument.
+@end ifnottex
+@iftex
+Etymology: @b{V}ariadic @b{a}rguments-subsystem: get @b{arg}ument.
+@end iftex
@end table
@fnindex va_copy
@@ -299,6 +352,13 @@ void fun(int arg, ...)
@}
@end example
+@ifnottex
+Etymology: (V)ariadic (a)rguments-subsystem: (copy) list.
+@end ifnottex
+@iftex
+Etymology: @b{V}ariadic @b{a}rguments-subsystem: @b{copy} list.
+@end iftex
+
Some systems define @code{va_start} and @code{va_end}
with a @code{@{} in @code{va_start} and a @code{@}}
in @code{va_end}. Therefore, they are declared this
@@ -454,3 +514,10 @@ Note that @code{NULL} is genuinely harmful in C++,
but excessive use of C++, and especially it
features, is harmful too.
+@ifnottex
+Etymology: Pointer with numerical value (0).
+@end ifnottex
+@iftex
+Etymology: Pointer with numerical value @b{0}.
+@end iftex
+
diff --git a/doc/info/chap/memory-allocation.texinfo b/doc/info/chap/memory-allocation.texinfo
index 1b7c778..eddefd0 100644
--- a/doc/info/chap/memory-allocation.texinfo
+++ b/doc/info/chap/memory-allocation.texinfo
@@ -410,6 +410,13 @@ for the aligment of all pointers it returns.
you want the pointer to be unaligned, call
@code{memalign(1, n)}.
+@ifnottex
+Etymology: (M)emory (alloc)ation.
+@end ifnottex
+@iftex
+Etymology: @b{M}emory @b{alloc}ation.
+@end iftex
+
@item void* calloc(size_t count, size_t size)
@fnindex calloc
@cpindex Memory allocation without uninitialisation
@@ -427,6 +434,13 @@ p = malloc(a * b);
memset(p, 0, a * b);
@end example
+@ifnottex
+Etymology: (C)leared memory (alloc)ation.
+@end ifnottex
+@iftex
+Etymology: @b{C}leared memory @b{alloc}ation.
+@end iftex
+
@item void free(void* ptr)
@fnindex free
@cpindex Deallocate memory
@@ -459,6 +473,13 @@ statically allocated arrays, which must not
be deallocated, or dynamically allocated
memory, which should be deallocated to avoid
memory leaks.
+
+@ifnottex
+Etymology: (Free) allocated memory.
+@end ifnottex
+@iftex
+Etymology: @b{Free} allocated memory.
+@end iftex
@end table
@file{<malloc.h>} also includes four unportable
@@ -473,6 +494,13 @@ does not overflow, @code{calloc(a, b)} is identical
to @code{zalloc(a * b)}. @code{zalloc} is a
@command{klibc} extension.
+@ifnottex
+Etymology: (Z)eroed memory (alloc)ation.
+@end ifnottex
+@iftex
+Etymology: @b{Z}eroed memory @b{alloc}ation.
+@end iftex
+
@item void* mallocz(size_t size, int clear)
@fnindex mallocz
This function is similar to @code{malloc}. However,
@@ -485,6 +513,13 @@ is non-zero, the allocated memory will be initialised.
This function is a Plan 9 from Bell Labs extension
and requires @code{_PLAN9_SOURCE}.
+@ifnottex
+Etymology: (M)emory (alloc)ation with potential (z)eroing.
+@end ifnottex
+@iftex
+Etymology: @b{M}emory @b{alloc}ation with potential @b{z}eroing.
+@end iftex
+
@item void cfree(void* ptr, ...)
@fnindex cfree
This function is an obsolete function provided
@@ -512,6 +547,13 @@ function @code{free}.
This function is a @sc{GNU} extension and requires
@code{_GNU_SOURCE}.
+
+@ifnottex
+Etymology: (@code{malloc})-subsystem: user-(usable size) of allocation.
+@end ifnottex
+@iftex
+Etymology: @b{malloc}-subsystem: user-@b{usable size} of allocation.
+@end iftex
@end table
@hfindex slibc-alloc.h
@@ -533,6 +575,13 @@ is guaranteed not to clear the memory. However,
the operating system kernel may still clear the
memory.
+@ifnottex
+Etymology: (Fast) variant of (@code{free}).
+@end ifnottex
+@iftex
+Etymology: @b{Fast} variant of @b{free}.
+@end iftex
+
@item void secure_free(void* ptr)
@fnindex secure_free
@cpindex Deallocate memory
@@ -540,6 +589,13 @@ memory.
This function is similar to @code{free}, but it
is guaranteed that the memory is clear.
+@ifnottex
+Etymology: (Secure) variant of (@code{free}).
+@end ifnottex
+@iftex
+Etymology: @b{Secure} variant of @b{free}.
+@end iftex
+
@item void FAST_FREE(void* ptr)
@fnindex FAST_FREE
@cpindex Deallocate memory
@@ -548,6 +604,13 @@ This clears deallocates a pointer with
@code{fast_free}, and sets @code{ptr} to
@code{NULL}.
+@ifnottex
+Etymology: Macro version of (@code{fast_free}).
+@end ifnottex
+@iftex
+Etymology: Macro version of @b{fast_free}.
+@end iftex
+
@item void SECURE_FREE(void* ptr)
@fnindex SECURE_FREE
@cpindex Deallocate memory
@@ -556,6 +619,13 @@ This clears deallocates a pointer with
@code{secure_free}, and sets @code{ptr} to
@code{NULL}.
+@ifnottex
+Etymology: Macro version of (@code{secure_free}).
+@end ifnottex
+@iftex
+Etymology: Macro version of @b{secure_free}.
+@end iftex
+
@item size_t allocsize(void* ptr)
@fnindex allocsize
@cpindex Retrieve allocation size
@@ -567,6 +637,13 @@ function @code{free}.
@code{allocsize(malloc(n))} returns @code{n}
(and allocates memory in the process.)
+
+@ifnottex
+Etymology: Memory (alloc)ation (size).
+@end ifnottex
+@iftex
+Etymology: Memory @b{alloc}ation @b{size}.
+@end iftex
@end table
@@ -615,6 +692,13 @@ In @code{slibc}, the alignment may be lost.
This behaviour has been chosen because aligned
memory allocation is uncommon in practice.
+@ifnottex
+Etymology: (Mem)ory (align)ment.
+@end ifnottex
+@iftex
+Etymology: @b{Mem}ory @b{align}ment.
+@end iftex
+
@item int posix_memalign(void** ptrptr, size_t boundary, size_t size)
@fnindex posix_memalign
This function is similar to @code{malloc},
@@ -668,6 +752,13 @@ memory allocation is uncommon in practice.
is not a multiple of @code{sizeof(void*)}, and
@code{errno} is unspecified.
+@ifnottex
+Etymology: (@sc{POSIX})-extension: (mem)ory alignment.
+@end ifnottex
+@iftex
+Etymology: @b{POSIX}-extension: @b{mem}ory alignment.
+@end iftex
+
@item void* valloc(size_t size)
@fnindex valloc
This function is similar to @code{memalign}.
@@ -699,6 +790,13 @@ In @code{slibc}, the alignment may be lost.
This behaviour has been chosen because aligned
memory allocation is uncommon in practice.
+@ifnottex
+Etymology: Whole-(v)irtual-memory-page aligned memory (alloc)ation.
+@end ifnottex
+@iftex
+Etymology: Whole-@b{v}irtual-memory-page aligned memory @b{alloc}ation.
+@end iftex
+
@item void* pvalloc(size_t size)
@fnindex pvalloc
This function is almost identical to
@@ -732,6 +830,13 @@ In @code{slibc}, the alignment may be lost.
This behaviour has been chosen because aligned
memory allocation is uncommon in practice.
+@ifnottex
+Etymology: Whole-(p)age-allocation variant of (@code{valloc}).
+@end ifnottex
+@iftex
+Etymology: Whole-@b{p}age-allocation variant of @b{valloc}.
+@end iftex
+
@item void* aligned_alloc(size_t boundary, size_t size)
@fnindex aligned_alloc
This function is identical to @code{memalign},
@@ -752,6 +857,13 @@ A recommended practice, to align pointers is:
@example
p = aligned_alloc(sizeof(*p), n)
@end example
+
+@ifnottex
+Etymology: (Align)ed memory (alloc)ation.
+@end ifnottex
+@iftex
+Etymology: @b{Align}ed memory @b{alloc}ation.
+@end iftex
@end table
@@ -811,6 +923,13 @@ or @code{REMEMALIGN_MEMCPY}, the function fails with
Upon successful completion, @code{errno} is set to zero
if @code{NULL} is returned.
+@ifnottex
+Etymology: (Re)allocate (mem)ory and (align).
+@end ifnottex
+@iftex
+Etymology: @b{Re}allocate @b{mem}ory and @b{align}.
+@end iftex
+
@item void* naive_realloc(void* ptr, size_t boundary, size_t size)
This function is discussed in @ref{Resizing memory allocations}.
@@ -891,6 +1010,13 @@ size_t psize, new_size;
psize = new_size;
@}
@end example
+
+@ifnottex
+Etymology: Memory (realloc)ation.
+@end ifnottex
+@iftex
+Etymology: Memory @b{realloc}ation.
+@end iftex
@end table
Note that if @code{ptr == NULL && size == 0},
@@ -922,6 +1048,13 @@ allocation is created, and zero-initialises the
newly available memory when the allocation has
grown.
+@ifnottex
+Etymology: (C)lear and (realloc)ate memory.
+@end ifnottex
+@iftex
+Etymology: @b{C}lear and @b{realloc}ate memory.
+@end iftex
+
@item void* fast_realloc(void* ptr, size_t size)
@fnindex fast_realloc
This function is similar to @code{realloc},
@@ -933,6 +1066,12 @@ memory when the allocation has grown. The
operating system kernel may still clear the
disowned memory area or the old allocation.
+@ifnottex
+Etymology: (Fast) variant of (@code{realloc}).
+@end ifnottex
+@iftex
+Etymology: @b{Fast} variant of @b{realloc}.
+@end iftex
@item void* secure_realloc(void* ptr, size_t size)
@fnindex secure_realloc
@@ -943,6 +1082,13 @@ allocation is created, but does not zero-initialise
the newly available memory when the allocation has
grown.
+@ifnottex
+Etymology: (Secure) variant of (@code{realloc}).
+@end ifnottex
+@iftex
+Etymology: @b{Secure} variant of @b{realloc}.
+@end iftex
+
@item void* custom_realloc(void* ptr, size_t size, int clear_old, int clear_new, int clear_free)
@fnindex custom_realloc
This function is similar to @code{realloc}, but
@@ -964,6 +1110,13 @@ disowned memory area or the old allocation, if
the parameters specifies that the memory should
not be cleared.
+@ifnottex
+Etymology: (Custom)isable variant of (@code{realloc}).
+@end ifnottex
+@iftex
+Etymology: @b{Custom}isable variant of @b{realloc}.
+@end iftex
+
@item void* extalloc(void* ptr, size_t size, enum extalloc_mode mode)
@fnindex extalloc
@tpindex extalloc_mode
@@ -981,6 +1134,13 @@ old memory --- disowned, or the old allocation --- if
@code{mode & EXTALLOC_CLEAR}. @code{EXTALLOC_MALLOC}
and @code{EXTALLOC_CLEAR} can be combined freely.
+@ifnottex
+Etymology: (Ext)end memory (alloc)ation.
+@end ifnottex
+@iftex
+Etymology: @b{Ext}end memory @b{alloc}ation.
+@end iftex
+
@item void* naive_realloc(void* ptr, size_t boundary, size_t size)
@fnindex naive_realloc
This is a naïve bare-bones version of @code{realloc},
@@ -1003,6 +1163,13 @@ If and only if, a new allocation is created, the
returned pointer's alignment will be @code{boundary}.
@end itemize
+@ifnottex
+Etymology: (Naïve) variant of (@code{realloc}).
+@end ifnottex
+@iftex
+Etymology: @b{Naïve} variant of @b{realloc}.
+@end iftex
+
@item void* naive_extalloc(void* ptr, size_t size)
@fnindex naive_extalloc
This is a naïve bare-bones version of @code{extalloc},
@@ -1012,6 +1179,13 @@ except it will return @code{NULL} with @code{errno} set to
zero, if it is not possible to perform the shrink or grow
without creating new pointer.
+@ifnottex
+Etymology: (Naïve) variant of (@code{extalloc}).
+@end ifnottex
+@iftex
+Etymology: @b{Naïve} variant of @b{extalloc}.
+@end iftex
+
@item void* falloc(void* ptr, size_t* ptrshift, size_t boundary, size_t old_size, size_t new_size, enum falloc_mode mode)
@fnindex falloc
@tpindex falloc_mode
@@ -1114,6 +1288,13 @@ is only copied over to the new allocation if
@code{mode & FALLOC_MEMCPY}. If
@code{(mode & FALLOC_INIT) && !(mode & FALLOC_MEMCPY)},
the entire allocation will be cleared.
+
+@ifnottex
+Etymology: (F)ast memory (alloc)ation.
+@end ifnottex
+@iftex
+Etymology: @b{F}ast memory @b{alloc}ation.
+@end iftex
@end table
diff --git a/include/malloc.h b/include/malloc.h
index 2b2748b..6410ad0 100644
--- a/include/malloc.h
+++ b/include/malloc.h
@@ -40,6 +40,8 @@
* The returned pointer has an alignment usable
* for any compiler-independent intrinsic data type.
*
+ * @etymology (M)emory (alloc)ation.
+ *
* @param size The size of the allocation.
* @return Pointer to the beginning of the new allocation.
* If `size` is zero, this function will either return
@@ -59,6 +61,8 @@ void* malloc(size_t)
* `p = calloc(n, m)` is equivalent to
* `(p = malloc(n * m), p ? (explicit_bzero(p, n * m), p) : NULL)`
*
+ * @etymology (C)leared memory (alloc)ation.
+ *
* @param elem_count The number of elements to allocate.
* @param elem_size The size of each element.
* @return Pointer to the beginning of the new allocation.
@@ -83,6 +87,8 @@ void* calloc(size_t, size_t)
*
* This is a Plan 9 from Bell Labs extension.
*
+ * @etymology (M)emory (alloc)ation with potential (z)eroing.
+ *
* @param size The size of the allocation.
* @param clear Clear the allocation unless this value is zero.
* @return Pointer to the beginning of the new allocation.
@@ -108,6 +114,8 @@ void* mallocz(size_t, int)
*
* This is a klibc extension.
*
+ * @etymology (Z)eroed memory (alloc)ation.
+ *
* @param size The size of the allocation.
* @return Pointer to the beginning of the new allocation.
* If `size` is zero, this function will either return
@@ -132,6 +140,8 @@ void* zalloc(size_t)
*
* On error, `ptr` is not freed.
*
+ * @etymology Memory (realloc)ation.
+ *
* @param ptr Pointer to the beginning of the old memory allocation.
* The process may crash if it does not point to the
* beginning of a memory allocation on the heap.
@@ -152,6 +162,8 @@ void* realloc(void*, size_t)
/**
* Free a memory allocation.
*
+ * @etymology (Free) allocated memory.
+ *
* @param ptr Pointer to the beginning of the memory allocation.
* The process may crash if it does not point to the
* beginning of a memory allocation on the heap.
@@ -189,6 +201,8 @@ void cfree(void*, ...)
* As a GNU-compliant slibc extension, memory allocated
* with this function can be freed with `free`.
*
+ * @etymology (Mem)ory (align)ment.
+ *
* @param boundary The alignment.
* @param size The number of bytes to allocated.
* @return Pointer to the beginning of the new allocation.
@@ -217,6 +231,8 @@ void* memalign(size_t, size_t)
* As a GNU-compliant slibc extension, memory allocated
* with this function can be freed with `free`.
*
+ * @etymology (POSIX)-extension: (mem)ory alignment.
+ *
* @param ptrptr Output parameter for the allocated memory.
* @param boundary The alignment.
* @param size The number of bytes to allocated.
@@ -236,6 +252,8 @@ int posix_memalign(void**, size_t, size_t)
* As a GNU-compliant slibc extension, memory allocated
* with this function can be freed with `free`.
*
+ * @etymology Whole-(v)irtual-memory-page aligned memory (alloc)ation.
+ *
* @param size The number of bytes to allocated.
* @return Pointer to the beginning of the new allocation.
* If `size` is zero, this function will either return
@@ -256,6 +274,8 @@ void* valloc(size_t)
* including auxiliary space, is rounded up to the next multiple
* of the page size.
*
+ * @etymology Whole-(p)age-allocation variant of (`valloc`).
+ *
* @param size The number of bytes to allocated.
* @return Pointer to the beginning of the new allocation.
* If `size` is zero, this function will either return
@@ -282,6 +302,8 @@ void* pvalloc(size_t)
* will allocate a bit of extra memory and shift the returned
* pointer so that it is aligned.
*
+ * @etymology (Align)ed memory (alloc)ation.
+ *
* @param boundary The alignment.
* @param size The number of bytes to allocated.
* @return Pointer to the beginning of the new allocation.
@@ -306,6 +328,8 @@ void* aligned_alloc(size_t, size_t)
*
* `p = malloc(n), malloc_usable_size(p)` will return `n`.
*
+ * @etymology (`malloc`)-subsystem: user-(usable size) of allocation.
+ *
* @param segment The memory segment.
* @return The size of the memory segment, 0 if `segment` is `NULL`.
*/
diff --git a/include/slibc-alloc.h b/include/slibc-alloc.h
index ccf7c86..7a697d1 100644
--- a/include/slibc-alloc.h
+++ b/include/slibc-alloc.h
@@ -106,6 +106,8 @@ enum falloc_mode
* This function is identical to `free`, except it is guaranteed not to
* override the memory segment with zeroes before freeing the allocation.
*
+ * @etymology (Fast) variant of (`free`).
+ *
* @param segment The memory segment to free.
*/
void fast_free(void*);
@@ -114,6 +116,8 @@ void fast_free(void*);
* This function is identical to `free`, except it is guaranteed to
* override the memory segment with zeroes before freeing the allocation.
*
+ * @etymology (Secure) variant of (`free`).
+ *
* @param segment The memory segment to free.
*/
void secure_free(void*);
@@ -129,6 +133,8 @@ void secure_free(void*);
*
* `p = malloc(n), allocsize(p)` will return `n`.
*
+ * @etymology Memory (alloc)ation (size).
+ *
* @param segment The memory segment.
* @return The size of the memory segment, 0 on error.
*
@@ -148,6 +154,8 @@ size_t allocsize(void*)
* with zeroes, including the old allocation if it creates a
* new allocation.
*
+ * @etymology (C)lear and (realloc)ate memory.
+ *
* @param ptr The old allocation, see `realloc` for more details.
* @param size The new allocation size, see `realloc` for more details.
* @return The new allocation, see `realloc` for more details.
@@ -161,6 +169,8 @@ void* crealloc(void*, size_t)
* This function behaves exactly like `realloc`, except it is
* guaranteed to never initialise or errors data.
*
+ * @etymology (Fast) variant of (`realloc`).
+ *
* @param ptr The old allocation, see `realloc` for more details.
* @param size The new allocation size, see `realloc` for more details.
* @return The new allocation, see `realloc` for more details.
@@ -174,6 +184,8 @@ void* fast_realloc(void*, size_t)
* This function behaves exactly like `crealloc`, except it
* does not initialise newly allocated size.
*
+ * @etymology (Secure) variant of (`realloc`).
+ *
* @param ptr The old allocation, see `realloc` for more details.
* @param size The new allocation size, see `realloc` for more details.
* @return The new allocation, see `realloc` for more details.
@@ -196,6 +208,8 @@ void* secure_realloc(void*, size_t)
* `secure_realloc(p, n)` is equivalent to (but slightly fast than)
* `custom_realloc(p, n, 1, 0, 1)`.
*
+ * @etymology (Custom)isable variant of (`realloc`).
+ *
* @param ptr The old allocation, see `realloc` for more details.
* @param size The new allocation size, see `realloc` for more details.
* @param clear_old Whether the disowned area is cleared, even if `ptr` is returned.
@@ -221,6 +235,8 @@ void* custom_realloc(void*, size_t, int, int, int)
* The behaviour is undefined if `mode` does not
* contain a valid flag-combination.
*
+ * @etymology (Ext)end memory (alloc)ation.
+ *
* @param ptr The old allocation, see `realloc` for more details.
* @param size The new allocation size, see `realloc` for more details.
* @param mode `EXTALLOC_CLEAR` or `EXTALLOC_MALLOC`, or both or neither.
@@ -238,6 +254,8 @@ void* extalloc(void*, size_t, enum extalloc_mode)
* This function is similar to `realloc`, however its
* behaviour and pointer alignment can be tuned.
*
+ * @etymology (Re)allocate (mem)ory and (align).
+ *
* @param ptr The old allocation, see `realloc` for more details.
* @param boundary The alignment, not checked before necessary.
* @param size The new allocation size, see `realloc` for more details.
@@ -264,6 +282,8 @@ void* rememalign(void*, size_t, size_t, enum rememalign_mode)
* the aligment is applied when it is necessary to
* create a new allocation.
*
+ * @etymology (Naïve) variant of (`realloc`).
+ *
* @param ptr The old allocation, see `realloc` for more details.
* @param boundary The alignment, not checked before necessary.
* @param size The new allocation size, see `realloc` for more details.
@@ -280,6 +300,8 @@ void* naive_realloc(void*, size_t, size_t) /* sic! we limit ourself to ASCII */
* not possible to perform the shrink or grow without creating
* new pointer.
*
+ * @etymology (Naïve) variant of (`extalloc`).
+ *
* @param ptr The old allocation, see `realloc` for more details.
* @param size The new allocation size, see `realloc` for more details.
* @return `ptr` on success or `NULL` on error or if `malloc` is needed.
@@ -322,6 +344,8 @@ void* naive_extalloc(void*, size_t) /* sic! we limit ourself to ASCII */
* `(mode & FALLOC_INIT) && !(mode & FALLOC_MEMCPY)`, the
* entire allocation will be cleared.
*
+ * @etymology (F)ast memory (alloc)ation.
+ *
* @param ptr The old pointer, `NULL` if a new shall be created.
* @param ptrshift Pointer that is used to keep track of the pointer's
* shift for alignment. `NULL` if the shift shall not
@@ -349,14 +373,18 @@ void* falloc(void*, size_t*, size_t, size_t, size_t, enum falloc_mode);
/**
* This macro calls `fast_free` and then sets the pointer to `NULL`,
* so that another attempt to free the segment will not crash the process.
+ *
+ * @etymology Macro version of (`fast_free`).
*/
-#define FAST_FREE(segment) (fast_free(segment), (void)((segment) = NULL));
+#define FAST_FREE(segment) (fast_free(segment), (void)((segment) = NULL));
/**
* This macro calls `secure_free` and then sets the pointer to `NULL`,
* so that another attempt to free the segment will not crash the process.
+ *
+ * @etymology Macro version of (`secure_free`).
*/
-#define SECURE_FREE(segment) (secure_free(segment), (void)((segment) = NULL));
+#define SECURE_FREE(segment) (secure_free(segment), (void)((segment) = NULL));
diff --git a/include/slibc-error.h b/include/slibc-error.h
index 9c8a895..66d1e50 100644
--- a/include/slibc-error.h
+++ b/include/slibc-error.h
@@ -210,6 +210,8 @@ int* __slibc_error_line(void) __GCC_ONLY(__attribute__((__const__))); /* TODO no
*
* This is a slibc extension.
*
+ * @etymology (slibc)-enhancement of (`perror`).
+ *
* @param progname The name of the program, `NULL` or empty to use `program_invocation_name`.
* @param filename The source code file where the error occurred.
* @param linenum The line in the source code where the error occurred.
diff --git a/include/slibc-human.h b/include/slibc-human.h
index 1cc071f..9a4e5dc 100644
--- a/include/slibc-human.h
+++ b/include/slibc-human.h
@@ -200,6 +200,8 @@ enum unescape_mode
/**
* Convert file permission from machine representation to human representation.
*
+ * @etymology Convert to (human)-representation: `(mode)_t`.
+ *
* @param buffer Sufficiently large buffer for the output, or `NULL`.
* 18 characters is always sufficient, regardless of `mode`.
* @param perm Machine representation of the permissions, will be masked with 07777.
@@ -221,6 +223,8 @@ char* humanmode(char* restrict, mode_t, enum humanmode_mode);
* `value & ~*mask | *mode`. The new mode (includes file type) should
* be `value & ~*mask | *mode & 07777`.
*
+ * @etymology Convert to (machine)-representation: `(mode)_t`.
+ *
* @param mode Output parameter for the bits to set, may be `NULL`.
* @param mask Output parameter for the bits to update, may be `NULL`.
* @param str The file permission to parse, must not include file type or be `NULL`.
@@ -235,6 +239,8 @@ int machinemode(mode_t* restrict, mode_t* restrict, const char* restrict)
/**
* Convert a file size of file offset from machine representation to human representation.
*
+ * @etymology Convert to (human)-representation: `(size)_t`.
+ *
* @param buffer A buffer than shall be used if it is sufficiently large.
* @param bufsize The allocation size of `buffer`.
* Must be 0 if and only if `buffer` is `NULL`.
@@ -262,21 +268,25 @@ char* humansize(char*, size_t, size_t, enum humansize_mode, int, const char* res
__GCC_ONLY(__attribute__((__warn_unused_result__)));
/* TODO machinesize */
+/* @etymology Convert to (machine)-representation: `(size)_t`. */
int machinesize(size_t* restrict size, const char* restrict str, enum machinesize_mode mode,
const char* restrict space, const char* restrict point);
#ifdef __C99__
/* TODO humandur */
+/* @etymology Convert to (human)-representation: (dur)ation. */
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. */
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. */
char* machineint(intmax_t* restrict r, const char* restrict str)
__GCC_ONLY(__attribute__((__warn_unused_result__)));
# ifdef __CONST_CORRECT
@@ -284,6 +294,7 @@ char* machineint(intmax_t* restrict r, const char* restrict str)
# endif
/* TODO machineuint */
+/* @etymology Convert to (machine)-representation: (u)nsigned (int)eger. */
char* machineuint(uintmax_t* restrict r, const char* restrict str)
__GCC_ONLY(__attribute__((__warn_unused_result__)));
# ifdef __CONST_CORRECT
@@ -292,6 +303,7 @@ char* machineuint(uintmax_t* restrict r, const char* restrict str)
#endif
/* TODO machinefloat */
+/* @etymology Convert to (machine)-representation: (float)ing-point number. */
int machinefloat(long double* restrict r, const char* restrict str,
const char* restrict space, const char* restrict comma);
#ifdef __CONST_CORRECT
@@ -314,6 +326,8 @@ int machinefloat(long double* restrict r, const char* restrict str,
* Unsupported escapes:
* \N{character name}
*
+ * @etymology (Unescape) escaped string.
+ *
* @param str The escaped string, may be edited, may be `NULL`.
* Must not be reused on error.
* @param mode How unrecognised escapes should be handled,
@@ -330,6 +344,8 @@ char* unescape(char*, enum unescape_mode);
/**
* Escapes a string.
*
+ * @etymology (Escape) string.
+ *
* @param str The unescaped string, may be `NULL`.
* @param quote The queue character, must be either ', "
* or a NUL-character (for no surrounding quotes).
diff --git a/include/slibc-print.h b/include/slibc-print.h
index 9cb57da..1ef8922 100644
--- a/include/slibc-print.h
+++ b/include/slibc-print.h
@@ -44,6 +44,8 @@
* Structure used by extensions to `generic_printf`-function
* to request that additionally arguments be added before the
* function is called again.
+ *
+ * @etymology (`generic_printf`)-subsystem: (ext)ension (queue).
*/
struct generic_printf_ext_queue
{
@@ -75,6 +77,8 @@ struct generic_printf_ext_queue
* Function-type used by `generic_printf` and `vgeneric_wprintf`
* to write a string.
*
+ * @etymology (`generic_printf`)-subsystem: (write-func)tion, `(t)ypedef`.
+ *
* @param text The text segment to print, it will only contain
* a NUL byte if that NUL byte shall be printed.
* @param length The length of `text`.
@@ -88,6 +92,8 @@ typedef int (* generic_printf_write_func_t)(const char*, size_t, void*);
/**
* Variant of `generic_printf_write_func_t` used for
* `generic_wprintf` and `vgeneric_wprintf`.
+ *
+ * @etymology (`generic_wprintf`)-subsystem: (write-func)tion, `(t)ypedef`.
*/
typedef int (* generic_wprintf_write_func_t)(const wchar_t*, size_t, void*);
@@ -95,6 +101,8 @@ typedef int (* generic_wprintf_write_func_t)(const wchar_t*, size_t, void*);
* Function-type used by `generic_printf` and `vgeneric_wprintf`
* to write a string if a custom formatting code was encountered.
*
+ * @etymology (`generic_printf`)-subsystem: (ext)ension(-func)tion, `(t)ypedef`.
+ *
* @param code The %-code, excluding the %.
* @param args Formatting arguments cased to `intmax`.
* @param argn The number of formatting arguments in `args`.
@@ -116,6 +124,8 @@ typedef ssize_t (* generic_printf_ext_func_t)(const char*, intmax_t*, size_t, in
/**
* Variant of `generic_printf_ext_func_t` used for
* `generic_wprintf` and `vgeneric_wprintf`.
+ *
+ * @etymology (`generic_wprintf`)-subsystem: (ext)ension(-func)tion, `(t)ypedef`.
*/
typedef ssize_t (* generic_wprintf_ext_func_t)(const wchar_t*, intmax_t*, size_t, int, void*,
struct generic_printf_ext_queue*);
@@ -124,6 +134,8 @@ typedef ssize_t (* generic_wprintf_ext_func_t)(const wchar_t*, intmax_t*, size_t
/**
* An almost fully generic `printf`-function.
*
+ * @etymology (Generic) (`wprintf`)-function.
+ *
* @param write_function Function used to write the string. `NULL` if
* it shall not be printed but only measured.
* @param extension_function Function used to extend the functions formatting codes.
@@ -155,6 +167,8 @@ int generic_printf(generic_printf_write_func_t, generic_printf_ext_func_t,
* Variant of `generic_printf` that uses `va_list`
* instead of variadic arguments.
*
+ * @etymology (V)ariadic version of (`generic_printf`).
+ *
* @param write_function Function used to write the string. `NULL` if
* it shall not be printed but only measured.
* @param extension_function Function used to extend the functions formatting codes.
@@ -185,6 +199,8 @@ int vgeneric_printf(generic_printf_write_func_t, generic_printf_ext_func_t,
/**
* Variant of `generic_printf` uses `wchar_t` instead of `char`;
*
+ * @etymology (Generic) (`printf`)-function.
+ *
* @param write_function Function used to write the string. `NULL` if
* it shall not be printed but only measured.
* @param extension_function Function used to extend the functions formatting codes.
@@ -217,6 +233,8 @@ int generic_wprintf(generic_wprintf_write_func_t, generic_wprintf_ext_func_t,
* Variant of `generic_wprintf` that uses `va_list`
* instead of variadic arguments.
*
+ * @etymology (V)ariadic version of (`generic_wprintf`).
+ *
* @param write_function Function used to write the string. `NULL` if
* it shall not be printed but only measured.
* @param extension_function Function used to extend the functions formatting codes.
diff --git a/include/stdalign.h b/include/stdalign.h
index 89aca73..e322a50 100644
--- a/include/stdalign.h
+++ b/include/stdalign.h
@@ -29,6 +29,8 @@
/**
* Specify the alignment of a variable.
*
+ * @etymology (Align as) type.
+ *
* @param type The type whose alignment shall be used.
*/
#if !defined(__C11__) && defined(__GNUC__)
@@ -40,6 +42,8 @@
/**
* Get the alignment of a type.
*
+ * @etymology (Align)ment (of) type.
+ *
* @param type The type.
* @return The alignment of the type.
*/
diff --git a/include/stdarg.h b/include/stdarg.h
index 9a8fb99..9012fb6 100644
--- a/include/stdarg.h
+++ b/include/stdarg.h
@@ -41,6 +41,8 @@
/**
* State of variadic argument-reading.
+ *
+ * @etymology (V)ariadic (a)rguments-subsystem: argument-(list).
*/
#ifndef __DEFINED_va_list
# define __DEFINED_va_list
@@ -56,6 +58,8 @@ typedef __builtin_va_list va_list;
/**
* Prologue to using a variadic arguments.
*
+ * @etymology (V)ariadic (a)rguments-subsystem: (start) of use.
+ *
* @param state:va_list The state of the variadic argument-reading.
* @param last:identifier The the last non-variadic argument.
*/
@@ -70,6 +74,8 @@ typedef __builtin_va_list va_list;
/**
* Epilogue to using a variadic arguments.
*
+ * @etymology (V)ariadic (a)rguments-subsystem: (end) of use.
+ *
* @param state:va_list The state of the variadic argument-reading.
*/
#ifndef va_end
@@ -83,6 +89,8 @@ typedef __builtin_va_list va_list;
/**
* Get the next variadic argument.
*
+ * @etymology (V)ariadic (a)rguments-subsystem: get (arg)ument.
+ *
* @param state:va_list The state of the variadic argument-reading.
* @param type:identifier The data type used in the called to the function,
* must match exactly. Arguments smaller than `int`
@@ -97,6 +105,8 @@ typedef __builtin_va_list va_list;
/**
* Copy a state of variadic argument-reading.
*
+ * @etymology (V)ariadic (a)rguments-subsystem: (copy) list.
+ *
* @param destination:va_list The copy if `source`.
* @param source:va_list The state of the variadic argument-reading.
*/
diff --git a/include/stdbool.h b/include/stdbool.h
index d68b829..95f6f2c 100644
--- a/include/stdbool.h
+++ b/include/stdbool.h
@@ -34,6 +34,8 @@
* is converted to 1 (just like prefixing with `!!`). This
* assures that overflow during cast does not cause a non-zero
* value to be converted to zero.
+ *
+ * @etymology (Bool)ean.
*/
#define bool _Bool
diff --git a/include/stddef.h b/include/stddef.h
index 50e9ba1..0f45c6a 100644
--- a/include/stddef.h
+++ b/include/stddef.h
@@ -41,6 +41,8 @@
* Note that `NULL` is genuinely harmful in C++,
* but excessive use of C++, and especially it
* features, is harmful too.
+ *
+ * @etymology Pointer with numerical value (0).
*/
#ifndef NULL
# define NULL ((void*)0)
@@ -64,6 +66,8 @@
* 16 because the member above it in the structure
* has offset 0 and size 16. 0 + 16 = 16.
*
+ * @etymology Address-(offset of) member.
+ *
* @param type:identifier The identifier for a structure.
* @param member:identifier The identifier for a member, direct or indirect,
* of the structure.
diff --git a/include/strings.h b/include/strings.h
index 23d0a46..adb8e97 100644
--- a/include/strings.h
+++ b/include/strings.h
@@ -31,6 +31,8 @@
/**
* Override a memory segment with zeroes.
*
+ * @etymology (B)uffer: (zero) out.
+ *
* @param segment The memory segment to override.
* @param size The size of the memory segment.
*/
@@ -44,6 +46,8 @@ void bzero(void*, size_t)
* Unlike `bzero` and `memset`, calls to this function
* cannot be removed, as an optimisation, by the compiler.
*
+ * @etymology (Explicit) version of (`bzero`).
+ *
* @param segment The memory segment to override.
* @param size The size of the memory segment.
*/
@@ -53,6 +57,8 @@ void explicit_bzero(void*, size_t);
/**
* Copy a memory segment to another, possibly overlapping, segment.
*
+ * @etymology (B)uffer: (copy).
+ *
* @param whence The source memory segment.
* @param whither The destination memory segment.
* @param size The number of bytes to copy.
@@ -62,6 +68,8 @@ void bcopy(const void*, void*, size_t)
/**
* This function is identical to `memcmp`.
+ *
+ * @etymology (B)uffer: (c)o(mp)are.
*/
int bcmp(const void*, const void*, size_t)
__deprecated("Use 'memcmp' instead.")
@@ -73,6 +81,8 @@ int bcmp(const void*, const void*, size_t)
* Be aware, only ASCII characters are case insensitive, non-ASCII
* characters are case sensitive.
*
+ * @etymology (Str)ing-function: (case) insensitive (c)o(mp)arison.
+ *
* @param a A negative value is returned if this is the lesser.
* @param b A positive value is returned if this is the lesser.
* @return Zero is returned if `a` and `b` are equal, otherwise,
@@ -86,6 +96,8 @@ int strcasecmp(const char*, const char*)
* Be aware, only ASCII characters are case insensitive, non-ASCII
* characters are case sensitive.
*
+ * @etymology (Str)ing-function: (n)-bytes, (case) insensitive (c)o(mp)arison.
+ *
* @param a A negative value is returned if this is the lesser.
* @param b A positive value is returned if this is the lesser.
* @param length The maximum number of characters to compare.
@@ -101,6 +113,8 @@ int strncasecmp(const char*, const char*, size_t)
* Be aware, only ASCII characters are case insensitive, non-ASCII
* characters are case sensitive.
*
+ * @etymology (`strcasecmp`) variant with (l)ocale-consideration.
+ *
* @param a A negative value is returned if this is the lesser.
* @param b A positive value is returned if this is the lesser.
* @param locale The locale.
@@ -115,6 +129,8 @@ int strcasecmp_l(const char*, const char*, locale_t) /* TODO */
* Be aware, only ASCII characters are case insensitive, non-ASCII
* characters are case sensitive.
*
+ * @etymology (`strncasecmp`) variant with (l)ocale-consideration.
+ *
* @param a A negative value is returned if this is the lesser.
* @param b A positive value is returned if this is the lesser.
* @param length The maximum number of characters to compare.
@@ -130,6 +146,8 @@ int strncasecmp_l(const char*, const char*, size_t, locale_t) /* TODO */
* This function is identical to `strchr`.
*
* This is a deprecated BSD extension.
+ *
+ * @etymology (Index) of character.
*/
char* index(const char*, int)
__deprecated("Use 'strchr' instead.")
@@ -142,6 +160,8 @@ char* index(const char*, int)
* This function is identical to `strrchr`.
*
* This is a deprecated BSD extension.
+ *
+ * @etymology (R)ight-most (index) of character.
*/
char* rindex(const char*, int)
__deprecated("Use 'strrchr' instead.")
@@ -154,7 +174,9 @@ char* rindex(const char*, int)
/**
* Find the first set bit in an integer.
*
- * @param i The integer
+ * @etymology (F)ind (f)irst (s)et bit on `int`.
+ *
+ * @param i The integer.
* @return The value of the least significant set bit, zero if none.
*/
int ffs(int)
@@ -163,7 +185,9 @@ int ffs(int)
/**
* Find the first set bit in an integer.
*
- * @param i The integer
+ * @etymology (F)ind (f)irst (s)et bit on `(l)ong int`.
+ *
+ * @param i The integer.
* @return The value of the least significant set bit, zero if none.
*/
int ffsl(long)
@@ -172,7 +196,9 @@ int ffsl(long)
/**
* Find the first set bit in an integer.
*
- * @param i The integer
+ * @etymology (F)ind (f)irst (s)et bit on `(l)ong (l)ong int`.
+ *
+ * @param i The integer.
* @return The value of the least significant set bit, zero if none.
*/
int ffsll(long long)
diff --git a/include/unistd.h b/include/unistd.h
index f259d5f..87f2c64 100644
--- a/include/unistd.h
+++ b/include/unistd.h
@@ -45,18 +45,24 @@
/**
* The file descriptor for stdin.
* The file with input.
+ *
+ * @etymology (St)andar(d) (in)put (file)descriptor (number).
*/
#define STDIN_FILENO 0
/**
* The file descriptor for stdout.
* The file for output.
+ *
+ * @etymology (St)andar(d) (out)put (file)descriptor (number).
*/
#define STDOUT_FILENO 1
/**
* The file descriptor for stderr.
* The file for error messages and warnings.
+ *
+ * @etymology (St)andar(d) (err)or output (file)descriptor (number).
*/
#define STDERR_FILENO 2
@@ -88,6 +94,8 @@
* POSIX.1-2001. It is however fundamental in
* implementing a fast `malloc`-implementation.
*
+ * @etymology Set (br)ea(k).
+ *
* @param address The process's new high end of its data segment.
* If lower than the current low end, nothing will
* happen and the function will return with a success
@@ -123,6 +131,8 @@ int brk(void*) /* TODO implement brk */
* POSIX.1-2001. It is however fundamental in
* implementing a fast `malloc`-implementation.
*
+ * @etymology Shift (br)ea(k).
+ *
* @param delta The incremant of the size of the data segment,
* zero means that the high end shall not be moved
* (thus the current high end is returned,) a
diff --git a/src/malloc.c b/src/malloc.c
index 61ef244..a66c062 100644
--- a/src/malloc.c
+++ b/src/malloc.c
@@ -80,6 +80,8 @@ static void* unaligned_malloc(size_t size)
* The returned pointer has an alignment usable
* for any compiler-independent intrinsic data type.
*
+ * @etymology (M)emory (alloc)ation.
+ *
* @param size The size of the allocation.
* @return Pointer to the beginning of the new allocation.
* If `size` is zero, this function will either return
@@ -102,6 +104,8 @@ void* malloc(size_t size)
* `p = calloc(n, m)` is equivalent to
* `(p = malloc(n * m), p ? (explicit_bzero(p, n * m), p) : NULL)`
*
+ * @etymology (C)leared memory (alloc)ation.
+ *
* @param elem_count The number of elements to allocate.
* @param elem_size The size of each element.
* @return Pointer to the beginning of the new allocation.
@@ -136,6 +140,8 @@ void* calloc(size_t elem_count, size_t elem_size)
*
* This is a Plan 9 from Bell Labs extension.
*
+ * @etymology (M)emory (alloc)ation with potential (z)eroing.
+ *
* @param size The size of the allocation.
* @param clear Clear the allocation unless this value is zero.
* @return Pointer to the beginning of the new allocation.
@@ -165,6 +171,8 @@ void* mallocz(size_t size, int clear)
*
* This is a klibc extension.
*
+ * @etymology (Z)eroed memory (alloc)ation.
+ *
* @param size The size of the allocation.
* @return Pointer to the beginning of the new allocation.
* If `size` is zero, this function will either return
@@ -193,6 +201,8 @@ void* zalloc(size_t size)
*
* On error, `ptr` is not freed.
*
+ * @etymology Memory (realloc)ation.
+ *
* @param ptr Pointer to the beginning of the old memory allocation.
* The process may crash if it does not point to the
* beginning of a memory allocation on the heap.
@@ -215,6 +225,8 @@ void* realloc(void* ptr, size_t size)
/**
* Free a memory allocation.
*
+ * @etymology (Free) allocated memory.
+ *
* @param ptr Pointer to the beginning of the memory allocation.
* The process may crash if it does not point to the
* beginning of a memory allocation on the heap.
@@ -255,6 +267,8 @@ void cfree(void* ptr, ...)
* As a GNU-compliant slibc extension, memory allocated
* with this function can be freed with `free`.
*
+ * @etymology (Mem)ory alignment.
+ *
* @param boundary The alignment.
* @param size The number of bytes to allocated.
* @return Pointer to the beginning of the new allocation.
@@ -304,6 +318,8 @@ void* memalign(size_t boundary, size_t size)
* As a GNU-compliant slibc extension, memory allocated
* with this function can be freed with `free`.
*
+ * @etymology (POSIX)-extension: (mem)ory alignment.
+ *
* @param ptrptr Output parameter for the allocated memory.
* @param boundary The alignment.
* @param size The number of bytes to allocated.
@@ -327,6 +343,8 @@ int posix_memalign(void** ptrptr, size_t boundary, size_t size)
* As a GNU-compliant slibc extension, memory allocated
* with this function can be freed with `free`.
*
+ * @etymology Whole-(v)irtual-memory-page aligned memory (alloc)ation.
+ *
* @param size The number of bytes to allocated.
* @return Pointer to the beginning of the new allocation.
* If `size` is zero, this function will either return
@@ -348,6 +366,8 @@ void* valloc(size_t size)
* including auxiliary space, is rounded up to the next multiple
* of the page size.
*
+ * @etymology Whole-(p)age-allocation variant of (`valloc`).
+ *
* @param size The number of bytes to allocated.
* @return Pointer to the beginning of the new allocation.
* If `size` is zero, this function will either return
@@ -383,6 +403,8 @@ void* pvalloc(size_t size)
* will allocate a bit of extra memory and shift the returned
* pointer so that it is aligned.
*
+ * @etymology (Alig)ned memory (alloc)ation.
+ *
* @param boundary The alignment.
* @param size The number of bytes to allocated.
* @return Pointer to the beginning of the new allocation.
@@ -407,6 +429,8 @@ void* aligned_alloc(size_t boundary, size_t size)
*
* `p = malloc(n), malloc_usable_size(p)` will return `n`.
*
+ * @etymology (`malloc`)-subsystem: user-(usable size) of allocation.
+ *
* @param segment The memory segment.
* @return The size of the memory segment, 0 if `segment` is `NULL`.
*/
diff --git a/src/string/str/strcasecmp.c b/src/string/str/strcasecmp.c
index eb02084..c4b9175 100644
--- a/src/string/str/strcasecmp.c
+++ b/src/string/str/strcasecmp.c
@@ -25,6 +25,8 @@
* Be aware, only ASCII characters are case insensitive, non-ASCII
* characters are case sensitive.
*
+ * @etymology (Str)ing-function: (case) insensitive (c)o(mp)arison.
+ *
* @param a A negative value is returned if this is the lesser.
* @param b A positive value is returned if this is the lesser.
* @return Zero is returned if `a` and `b` are equal, otherwise,
diff --git a/src/string/strn/strncasecmp.c b/src/string/strn/strncasecmp.c
index 919ff36..da9a1ba 100644
--- a/src/string/strn/strncasecmp.c
+++ b/src/string/strn/strncasecmp.c
@@ -25,6 +25,8 @@
* Be aware, only ASCII characters are case insensitive, non-ASCII
* characters are case sensitive.
*
+ * @etymology (Str)ing-function: (n)-bytes, (case) insensitive (c)o(mp)arison.
+ *
* @param a A negative value is returned if this is the lesser.
* @param b A positive value is returned if this is the lesser.
* @param length The maximum number of characters to compare.
diff --git a/src/strings/bcmp.c b/src/strings/bcmp.c
index 3693354..23e6126 100644
--- a/src/strings/bcmp.c
+++ b/src/strings/bcmp.c
@@ -22,6 +22,8 @@
/**
* This function is identical to `memcmp`.
+ *
+ * @etymology (B)uffer: (c)o(mp)are.
*/
int bcmp(const void* a, const void* b, size_t size)
{
diff --git a/src/strings/bcopy.c b/src/strings/bcopy.c
index 47bbc1c..1abeb7c 100644
--- a/src/strings/bcopy.c
+++ b/src/strings/bcopy.c
@@ -23,6 +23,8 @@
/**
* Copy a memory segment to another, possibly overlapping, segment.
*
+ * @etymology (B)uffer: (copy).
+ *
* @param whence The source memory segment.
* @param whither The destination memory segment.
* @param size The number of bytes to copy.
diff --git a/src/strings/bzero.c b/src/strings/bzero.c
index a3cb557..e581b94 100644
--- a/src/strings/bzero.c
+++ b/src/strings/bzero.c
@@ -23,6 +23,8 @@
/**
* Override a memory segment with zeroes.
*
+ * @etymology (B)uffer: (zero) out.
+ *
* @param segment The memory segment to override.
* @param size The size of the memory segment.
*/
diff --git a/src/strings/explicit_bzero.c b/src/strings/explicit_bzero.c
index 00fe4ab..387c666 100644
--- a/src/strings/explicit_bzero.c
+++ b/src/strings/explicit_bzero.c
@@ -33,6 +33,8 @@ void* (*volatile __slibc_explicit_memset)(void*, int, size_t) = memset;
* Unlike `bzero` and `memset`, calls to this function
* cannot be removed, as an optimisation, by the compiler.
*
+ * @etymology (Explicit) version of (`bzero`).
+ *
* @param segment The memory segment to override.
* @param size The size of the memory segment.
*/
diff --git a/src/strings/ffs.c b/src/strings/ffs.c
index 7de35a4..46ad612 100644
--- a/src/strings/ffs.c
+++ b/src/strings/ffs.c
@@ -22,7 +22,9 @@
/**
* Find the first set bit in an integer.
*
- * @param i The integer
+ * @etymology (F)ind (f)irst (s)et bit on `int`.
+ *
+ * @param i The integer.
* @return The value of the least significant set bit, zero if none.
*/
int ffs(int i)
diff --git a/src/strings/ffsl.c b/src/strings/ffsl.c
index 6657769..3116723 100644
--- a/src/strings/ffsl.c
+++ b/src/strings/ffsl.c
@@ -18,10 +18,13 @@
#include <strings.h>
+
/**
* Find the first set bit in an integer.
*
- * @param i The integer
+ * @etymology (F)ind (f)irst (s)et bit on `(l)ong int`.
+ *
+ * @param i The integer.
* @return The value of the least significant set bit, zero if none.
*/
int ffsl(long i)
diff --git a/src/strings/ffsll.c b/src/strings/ffsll.c
index c053fb6..13d4c14 100644
--- a/src/strings/ffsll.c
+++ b/src/strings/ffsll.c
@@ -22,7 +22,9 @@
/**
* Find the first set bit in an integer.
*
- * @param i The integer
+ * @etymology (F)ind (f)irst (s)et bit on `(l)ong (l)ong int`.
+ *
+ * @param i The integer.
* @return The value of the least significant set bit, zero if none.
*/
int ffsll(long long i)
diff --git a/src/strings/index.c b/src/strings/index.c
index 2f46d30..332811d 100644
--- a/src/strings/index.c
+++ b/src/strings/index.c
@@ -24,6 +24,8 @@
* This function is identical to `strchr`.
*
* This is a deprecated BSD extension.
+ *
+ * @etymology (Index) of character.
*/
char* (index)(const char* string, int c)
{
diff --git a/src/strings/rindex.c b/src/strings/rindex.c
index 0ab4ed1..3e39a9e 100644
--- a/src/strings/rindex.c
+++ b/src/strings/rindex.c
@@ -24,6 +24,8 @@
* This function is identical to `strrchr`.
*
* This is a deprecated BSD extension.
+ *
+ * @etymology (R)ight-most (index) of character.
*/
char* (rindex)(const char* string, int c)
{
generated by cgit v1.2.3-70-g09d2 (git 2.46.0) at 2024-10-19 21:36:43 +0000