From de2602736d1a0c978e4b5d8b942f6639b2135d6c Mon Sep 17 00:00:00 2001 From: Simon McVittie Date: Fri, 21 Oct 2022 15:19:47 +0100 Subject: [PATCH] docs: Clarify the relationship between gssize, ssize_t and SSIZE_T This is similar to the relationship between gsize and size_t, except that size_t is a Standard C type but ssize_t is platform-specific (specifically, ssize_t is a POSIX type, and on Windows the equivalent is SSIZE_T), making it more awkward to use in portable code. As a result, continuing to use gssize is more useful than continuing to use gsize. Helps: https://gitlab.gnome.org/GNOME/glib/-/issues/1484 Signed-off-by: Simon McVittie --- glib/docs.c | 25 ++++++++++++++++++++++++- 1 file changed, 24 insertions(+), 1 deletion(-) diff --git a/glib/docs.c b/glib/docs.c index 8d573bf0f..54b329166 100644 --- a/glib/docs.c +++ b/glib/docs.c @@ -703,10 +703,23 @@ * gssize: * * A signed variant of #gsize, corresponding to the - * ssize_t defined on most platforms. + * `ssize_t` defined in POSIX or the similar `SSIZE_T` in Windows. + * + * In new platform-specific code, consider using `ssize_t` or `SSIZE_T` + * directly. + * * Values of this type can range from %G_MINSSIZE * to %G_MAXSSIZE. * + * Note that on platforms where `ssize_t` is implemented, `ssize_t` and + * `gssize` might be implemented by different standard integer types + * of the same size. Similarly, on Windows, `SSIZE_T` and `gssize` + * might be implemented by different standard integer types of the same + * size. See #gsize for more details. + * + * This type is also not guaranteed to be the same as standard C + * `ptrdiff_t`, although they are the same on many platforms. + * * To print or scan values of this type, use * %G_GSSIZE_MODIFIER and/or %G_GSSIZE_FORMAT. */ @@ -733,6 +746,11 @@ * This is the platform dependent conversion specifier for scanning * and printing values of type #gssize. See also %G_GINT16_FORMAT. * + * Note that this is not necessarily the correct format to scan or print + * a POSIX `ssize_t` or a Windows `SSIZE_T`, even though the in-memory + * representation is the same. + * On POSIX platforms, the `"zd"` format should be used for `ssize_t`. + * * Since: 2.6 */ @@ -743,6 +761,11 @@ * for scanning and printing values of type #gssize. It * is a string literal. * + * Note that this is not necessarily the correct modifier to scan or print + * a POSIX `ssize_t` or a Windows `SSIZE_T`, even though the in-memory + * representation is the same. + * On POSIX platforms, the `"z"` modifier should be used for `ssize_t`. + * * Since: 2.6 */