Paul Eggert <egg...@cs.ucla.edu> writes:
> * doc/gnulib-readme.texi (Other portability assumptions):
> Mention the C23 function memalignment.
> * doc/posix-functions/memalignment.texi: New file.
> * doc/gnulib.texi (Functions in <stdlib.h>): Include it.
Thanks.
I noticed C23 added two other functions that weren't a part of previous
standards, being free_sized and free_aligned_sized.
They were added as an extension to the regular free function for
implementations who can optimize deallocations given the extra
information. The original proposal links to interesting research using
Google's TCMalloc and Facebook with jemalloc [1].
Though it appears no system actually supports these yet. FreeBSD uses
jemalloc but it seems it doesn't make them available.
Documented them with the attached patch.
Collin
[1] https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2699.htm
>From d4fa8756f0deda30f77a1779e4d0da3c2b8f688b Mon Sep 17 00:00:00 2001
From: Collin Funk <collin.fu...@gmail.com>
Date: Sat, 8 Feb 2025 17:40:48 -0800
Subject: [PATCH] doc: Document free_aligned_sized and free_sized added in C23.
* doc/posix-functions/free_aligned_sized.texi: New file.
* doc/posix-functions/free_sized.texi: New file.
* doc/gnulib.texi (Functions in <stdlib.h>): Include them.
---
ChangeLog | 7 +++++++
doc/gnulib.texi | 4 ++++
doc/posix-functions/free_aligned_sized.texi | 18 ++++++++++++++++++
doc/posix-functions/free_sized.texi | 18 ++++++++++++++++++
4 files changed, 47 insertions(+)
create mode 100644 doc/posix-functions/free_aligned_sized.texi
create mode 100644 doc/posix-functions/free_sized.texi
diff --git a/ChangeLog b/ChangeLog
index 7e0b8163a5..11912cd67a 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+2025-02-08 Collin Funk <collin.fu...@gmail.com>
+
+ doc: Document free_aligned_sized and free_sized added in C23.
+ * doc/posix-functions/free_aligned_sized.texi: New file.
+ * doc/posix-functions/free_sized.texi: New file.
+ * doc/gnulib.texi (Functions in <stdlib.h>): Include them.
+
2025-02-08 Paul Eggert <egg...@cs.ucla.edu>
memalignment: document
diff --git a/doc/gnulib.texi b/doc/gnulib.texi
index 4d0cfd26d5..31a206f8fb 100644
--- a/doc/gnulib.texi
+++ b/doc/gnulib.texi
@@ -3585,6 +3585,8 @@ @node Functions in <stdlib.h>
* erand48::
* exit::
* free::
+* free_aligned_sized::
+* free_sized::
* getenv::
* getsubopt::
* grantpt::
@@ -3664,6 +3666,8 @@ @node Functions in <stdlib.h>
@include posix-functions/erand48.texi
@include posix-functions/exit.texi
@include posix-functions/free.texi
+@include posix-functions/free_aligned_sized.texi
+@include posix-functions/free_sized.texi
@include posix-functions/getenv.texi
@include posix-functions/getsubopt.texi
@include posix-functions/grantpt.texi
diff --git a/doc/posix-functions/free_aligned_sized.texi b/doc/posix-functions/free_aligned_sized.texi
new file mode 100644
index 0000000000..9074692a74
--- /dev/null
+++ b/doc/posix-functions/free_aligned_sized.texi
@@ -0,0 +1,18 @@
+@node free_aligned_sized
+@subsection @code{free_aligned_sized}
+@findex free_aligned_sized
+
+ISO C23 specification:@* @url{https://www.open-std.org/jtc1/sc22/wg14/www/docs/n3220.pdf} section 7.24.3.5
+
+Gnulib module: ---
+
+Portability problems fixed by Gnulib:
+@itemize
+@end itemize
+
+Portability problems not fixed by Gnulib:
+@itemize
+@item
+This function is missing on most non-C23 platforms:
+glibc 2.41, macOS 14, FreeBSD 14.0, NetBSD 10.0, OpenBSD 7.5, Minix 3.3.0, AIX 7.3.1, HP-UX 11.31, Solaris 11.4, Cygwin 3.5.3, mingw, MSVC 14, Android 9.0.
+@end itemize
diff --git a/doc/posix-functions/free_sized.texi b/doc/posix-functions/free_sized.texi
new file mode 100644
index 0000000000..f6d750c644
--- /dev/null
+++ b/doc/posix-functions/free_sized.texi
@@ -0,0 +1,18 @@
+@node free_sized
+@subsection @code{free_sized}
+@findex free_sized
+
+ISO C23 specification:@* @url{https://www.open-std.org/jtc1/sc22/wg14/www/docs/n3220.pdf} section 7.24.3.4
+
+Gnulib module: ---
+
+Portability problems fixed by Gnulib:
+@itemize
+@end itemize
+
+Portability problems not fixed by Gnulib:
+@itemize
+@item
+This function is missing on most non-C23 platforms:
+glibc 2.41, macOS 14, FreeBSD 14.0, NetBSD 10.0, OpenBSD 7.5, Minix 3.3.0, AIX 7.3.1, HP-UX 11.31, Solaris 11.4, Cygwin 3.5.3, mingw, MSVC 14, Android 9.0.
+@end itemize
--
2.48.1
