From 64945e6386aeaec96d93057ff26a6e5a91377269 Mon Sep 17 00:00:00 2001 From: Simon McVittie Date: Fri, 21 Oct 2022 14:32:19 +0100 Subject: [PATCH] docs: Stop claiming that gsize is wide enough to hold a pointer Standard C specifically does not guarantee this, and it's untrue on CHERI architectures (which have 128-bit pointers into a 64-bit address space, with the remaining bits used for a capability-like mechanism). Signed-off-by: Simon McVittie --- glib/docs.c | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/glib/docs.c b/glib/docs.c index f93ce8048..e578f315b 100644 --- a/glib/docs.c +++ b/glib/docs.c @@ -515,13 +515,22 @@ /** * gsize: * - * An unsigned integer type of the result of the sizeof operator, - * corresponding to the size_t type defined in C99. - * This type is wide enough to hold the numeric value of a pointer, - * so it is usually 32 bit wide on a 32-bit platform and 64 bit wide + * An unsigned integer type of the result of the `sizeof` operator, + * corresponding to the `size_t` type defined in C99. + * + * It is usually 32 bit wide on a 32-bit platform and 64 bit wide * on a 64-bit platform. Values of this type can range from 0 to * %G_MAXSIZE. * + * This type is wide enough to hold the size of the largest possible + * memory allocation, but is not guaranteed to be wide enough to hold + * the numeric value of a pointer: on platforms that use tagged pointers, + * such as [CHERI](https://cheri-cpu.org/), pointers can be numerically + * larger than the size of the address space. + * If the numeric value of a pointer needs to be stored in an integer + * without information loss, use the standard C types `intptr_t` or + * `uintptr_t`, or the similar GLib types #gintptr or #guintptr. + * * To print or scan values of this type, use * %G_GSIZE_MODIFIER and/or %G_GSIZE_FORMAT. */