summaryrefslogtreecommitdiff
path: root/gir
diff options
context:
space:
mode:
authorSebastian Dröge <sebastian@centricular.com>2022-11-03 14:35:24 +0200
committerSebastian Dröge <sebastian@centricular.com>2022-11-03 14:35:42 +0200
commite95e19b55db856c23fea6a3e4002b4025e9d77fa (patch)
tree8ccc3b66dcd052665d43c12e3e6691b83664c101 /gir
parent0a8367524cec8d4d0dec1b3f05eeb2f8d1b6aedd (diff)
downloadgobject-introspection-e95e19b55db856c23fea6a3e4002b4025e9d77fa.tar.gz
Update glib introspection data
This is based on 201c920cbd0b816f4e19b52c1b28746935fdcb00.
Diffstat (limited to 'gir')
-rw-r--r--gir/gio-2.0.c16
-rw-r--r--gir/glib-2.0.c576
-rw-r--r--gir/gmodule-2.0.c59
3 files changed, 596 insertions, 55 deletions
diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c
index 23112b3d..8192554c 100644
--- a/gir/gio-2.0.c
+++ b/gir/gio-2.0.c
@@ -39548,7 +39548,8 @@
* callback to @callback, with @task as the callback's `user_data`.
*
* It will set the @source’s name to the task’s name (as set with
- * g_task_set_name()), if one has been set.
+ * g_task_set_name()), if one has been set on the task and the source doesn’t
+ * yet have a name.
*
* This takes a reference on @task until @source is destroyed.
*
@@ -40161,6 +40162,19 @@
/**
+ * g_task_set_static_name:
+ * @task: a #GTask
+ * @name: (nullable): a human readable name for the task. Must be a string literal
+ *
+ * Sets @task’s name, used in debugging and profiling.
+ *
+ * This is a variant of g_task_set_name() that avoids copying @name.
+ *
+ * Since: 2.76
+ */
+
+
+/**
* g_task_set_task_data:
* @task: the #GTask
* @task_data: (nullable): task-specific data
diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c
index 4532a38d..2e972a1f 100644
--- a/gir/glib-2.0.c
+++ b/gir/glib-2.0.c
@@ -3150,6 +3150,10 @@
* sscanf ("42", "%" G_GINT16_FORMAT, &in)
* out = in * 1000;
* g_print ("%" G_GINT32_FORMAT, out);
+ *
+ * This is not necessarily the correct format for printing and scanning
+ * `int16_t` values, even though the in-memory representation is the same.
+ * Standard C macros like `PRId16` and `SCNd16` should be used for `int16_t`.
* ]|
*/
@@ -3169,6 +3173,10 @@
* g_print ("%#" G_GINT16_MODIFIER "x", value);
* ]|
*
+ * This is not necessarily the correct modifier for printing and scanning
+ * `int16_t` values, even though the in-memory representation is the same.
+ * Standard C macros like `PRId16` and `SCNd16` should be used for `int16_t`.
+ *
* Since: 2.4
*/
@@ -3178,6 +3186,10 @@
*
* This is the platform dependent conversion specifier for scanning
* and printing values of type #gint32. See also %G_GINT16_FORMAT.
+ *
+ * This is not necessarily the correct modifier for printing and scanning
+ * `int32_t` values, even though the in-memory representation is the same.
+ * Standard C macros like `PRId32` and `SCNd32` should be used for `int32_t`.
*/
@@ -3188,6 +3200,10 @@
* for scanning and printing values of type #gint32 or #guint32. It
* is a string literal. See also %G_GINT16_MODIFIER.
*
+ * This is not necessarily the correct modifier for printing and scanning
+ * `int32_t` values, even though the in-memory representation is the same.
+ * Standard C macros like `PRId32` and `SCNd32` should be used for `int32_t`.
+ *
* Since: 2.4
*/
@@ -3198,6 +3214,9 @@
*
* This macro is used to insert 64-bit integer literals
* into the source code.
+ *
+ * It is similar to the standard C `INT64_C` macro,
+ * which should be preferred in new code.
*/
@@ -3213,6 +3232,10 @@
* if %G_GINT64_FORMAT is defined. Due to its weak error handling, scanf()
* is not recommended for parsing anyway; consider using g_ascii_strtoull()
* instead.
+ *
+ * This is not necessarily the correct format for printing and scanning
+ * `int64_t` values, even though the in-memory representation is the same.
+ * Standard C macros like `PRId64` and `SCNd64` should be used for `int64_t`.
*/
@@ -3227,6 +3250,10 @@
* though the types are supported. On such platforms %G_GINT64_MODIFIER
* is not defined.
*
+ * This is not necessarily the correct modifier for printing and scanning
+ * `int64_t` values, even though the in-memory representation is the same.
+ * Standard C macros like `PRId64` and `SCNd64` should be used for `int64_t`.
+ *
* Since: 2.4
*/
@@ -3237,6 +3264,12 @@
* This is the platform dependent conversion specifier for scanning
* and printing values of type #gintptr.
*
+ * Note that this is not necessarily the correct format to scan or
+ * print an `intptr_t`, even though the in-memory representation is the
+ * same.
+ * Standard C macros like `PRIdPTR` and `SCNdPTR` should be used for
+ * `intptr_t`.
+ *
* Since: 2.22
*/
@@ -3248,6 +3281,12 @@
* for scanning and printing values of type #gintptr or #guintptr.
* It is a string literal.
*
+ * Note that this is not necessarily the correct modifier to scan or
+ * print an `intptr_t`, even though the in-memory representation is the
+ * same.
+ * Standard C macros like `PRIdPTR` and `SCNdPTR` should be used for
+ * `intptr_t`.
+ *
* Since: 2.22
*/
@@ -3408,6 +3447,9 @@
* This is the platform dependent conversion specifier for scanning
* and printing values of type #goffset. See also %G_GINT64_FORMAT.
*
+ * This format should only be used with #goffset values, and not
+ * with `off_t`, which is not necessarily the same type or even the same size.
+ *
* Since: 2.20
*/
@@ -3419,6 +3461,9 @@
* for scanning and printing values of type #goffset. It is a string
* literal. See also %G_GINT64_MODIFIER.
*
+ * This modifier should only be used with #goffset values, and not
+ * with `off_t`, which is not necessarily the same type or even the same size.
+ *
* Since: 2.20
*/
@@ -3429,6 +3474,11 @@
* This is the platform dependent conversion specifier for scanning
* and printing values of type #gsize. See also %G_GINT16_FORMAT.
*
+ * Note that this is not necessarily the correct format to scan or
+ * print a `size_t`, even though the in-memory representation is the
+ * same. The standard C `"zu"` format should be used for `size_t`,
+ * assuming a C99-compliant `printf` implementation is available.
+ *
* Since: 2.6
*/
@@ -3440,6 +3490,11 @@
* for scanning and printing values of type #gsize. It
* is a string literal.
*
+ * Note that this is not necessarily the correct modifier to scan or
+ * print a `size_t`, even though the in-memory representation is the
+ * same. The Standard C `"z"` modifier should be used for `size_t`,
+ * assuming a C99-compliant `printf` implementation is available.
+ *
* Since: 2.6
*/
@@ -3450,6 +3505,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
*/
@@ -3461,6 +3521,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
*/
@@ -3470,6 +3535,10 @@
*
* This is the platform dependent conversion specifier for scanning
* and printing values of type #guint16. See also %G_GINT16_FORMAT
+ *
+ * This is not necessarily the correct modifier for printing and scanning
+ * `uint16_t` values, even though the in-memory representation is the same.
+ * Standard C macros like `PRIu16` and `SCNu16` should be used for `uint16_t`.
*/
@@ -3478,6 +3547,10 @@
*
* This is the platform dependent conversion specifier for scanning
* and printing values of type #guint32. See also %G_GINT16_FORMAT.
+ *
+ * This is not necessarily the correct modifier for printing and scanning
+ * `uint32_t` values, even though the in-memory representation is the same.
+ * Standard C macros like `PRIu32` and `SCNu32` should be used for `uint32_t`.
*/
@@ -3488,6 +3561,9 @@
* This macro is used to insert 64-bit unsigned integer
* literals into the source code.
*
+ * It is similar to the standard C `UINT64_C` macro,
+ * which should be preferred in new code.
+ *
* Since: 2.10
*/
@@ -3504,6 +3580,10 @@
* if %G_GINT64_FORMAT is defined. Due to its weak error handling, scanf()
* is not recommended for parsing anyway; consider using g_ascii_strtoull()
* instead.
+ *
+ * This is not necessarily the correct modifier for printing and scanning
+ * `uint64_t` values, even though the in-memory representation is the same.
+ * Standard C macros like `PRIu64` and `SCNu64` should be used for `uint64_t`.
*/
@@ -3513,6 +3593,12 @@
* This is the platform dependent conversion specifier
* for scanning and printing values of type #guintptr.
*
+ * Note that this is not necessarily the correct format to scan or
+ * print a `uintptr_t`, even though the in-memory representation is the
+ * same.
+ * Standard C macros like `PRIuPTR` and `SCNuPTR` should be used for
+ * `uintptr_t`.
+ *
* Since: 2.22
*/
@@ -4065,6 +4151,9 @@
* G_MAXDOUBLE:
*
* The maximum value which can be held in a #gdouble.
+ *
+ * This is the same as standard C `DBL_MAX`, which is available since C99
+ * and should be preferred in new code.
*/
@@ -4072,6 +4161,9 @@
* G_MAXFLOAT:
*
* The maximum value which can be held in a #gfloat.
+ *
+ * This is the same as standard C `FLT_MAX`, which is available since C99
+ * and should be preferred in new code.
*/
@@ -4079,6 +4171,9 @@
* G_MAXINT:
*
* The maximum value which can be held in a #gint.
+ *
+ * This is the same as standard C `INT_MAX`, which is available since C99
+ * and should be preferred in new code.
*/
@@ -4087,6 +4182,9 @@
*
* The maximum value which can be held in a #gint16.
*
+ * This is the same as standard C `INT16_MAX`, which should be
+ * preferred in new code.
+ *
* Since: 2.4
*/
@@ -4096,6 +4194,9 @@
*
* The maximum value which can be held in a #gint32.
*
+ * This is the same as standard C `INT32_MAX`, which should be
+ * preferred in new code.
+ *
* Since: 2.4
*/
@@ -4112,6 +4213,9 @@
*
* The maximum value which can be held in a #gint8.
*
+ * This is the same as standard C `INT8_MAX`, which should be
+ * preferred in new code.
+ *
* Since: 2.4
*/
@@ -4120,6 +4224,9 @@
* G_MAXLONG:
*
* The maximum value which can be held in a #glong.
+ *
+ * This is the same as standard C `ULONG_MAX`, which is available since C99
+ * and should be preferred in new code.
*/
@@ -4134,6 +4241,9 @@
* G_MAXSHORT:
*
* The maximum value which can be held in a #gshort.
+ *
+ * This is the same as standard C `SHRT_MAX`, which is available since C99
+ * and should be preferred in new code.
*/
@@ -4142,6 +4252,9 @@
*
* The maximum value which can be held in a #gsize.
*
+ * This is the same as standard C `SIZE_MAX` (available since C99),
+ * which should be preferred in new code.
+ *
* Since: 2.4
*/
@@ -4159,6 +4272,9 @@
* G_MAXUINT:
*
* The maximum value which can be held in a #guint.
+ *
+ * This is the same as standard C `UINT_MAX`, which is available since C99
+ * and should be preferred in new code.
*/
@@ -4167,6 +4283,9 @@
*
* The maximum value which can be held in a #guint16.
*
+ * This is the same as standard C `UINT16_MAX`, which should be
+ * preferred in new code.
+ *
* Since: 2.4
*/
@@ -4176,6 +4295,9 @@
*
* The maximum value which can be held in a #guint32.
*
+ * This is the same as standard C `UINT32_MAX`, which should be
+ * preferred in new code.
+ *
* Since: 2.4
*/
@@ -4184,6 +4306,9 @@
* G_MAXUINT64:
*
* The maximum value which can be held in a #guint64.
+ *
+ * This is the same as standard C `UINT64_MAX`, which should be
+ * preferred in new code.
*/
@@ -4192,6 +4317,9 @@
*
* The maximum value which can be held in a #guint8.
*
+ * This is the same as standard C `UINT8_MAX`, which should be
+ * preferred in new code.
+ *
* Since: 2.4
*/
@@ -4200,6 +4328,9 @@
* G_MAXULONG:
*
* The maximum value which can be held in a #gulong.
+ *
+ * This is the same as standard C `ULONG_MAX`, which is available since C99
+ * and should be preferred in new code.
*/
@@ -4207,6 +4338,9 @@
* G_MAXUSHORT:
*
* The maximum value which can be held in a #gushort.
+ *
+ * This is the same as standard C `USHRT_MAX`, which is available since C99
+ * and should be preferred in new code.
*/
@@ -4217,6 +4351,9 @@
*
* If you are interested in the smallest value which can be held
* in a #gdouble, use -%G_MAXDOUBLE.
+ *
+ * This is the same as standard C `DBL_MIN`, which is available since C99
+ * and should be preferred in new code.
*/
@@ -4227,6 +4364,9 @@
*
* If you are interested in the smallest value which can be held
* in a #gfloat, use -%G_MAXFLOAT.
+ *
+ * This is the same as standard C `FLT_MIN`, which is available since C99
+ * and should be preferred in new code.
*/
@@ -4234,6 +4374,9 @@
* G_MININT:
*
* The minimum value which can be held in a #gint.
+ *
+ * This is the same as standard C `INT_MIN`, which is available since C99
+ * and should be preferred in new code.
*/
@@ -4241,6 +4384,9 @@
* G_MINLONG:
*
* The minimum value which can be held in a #glong.
+ *
+ * This is the same as standard C `LONG_MIN`, which is available since C99
+ * and should be preferred in new code.
*/
@@ -4255,6 +4401,9 @@
* G_MINSHORT:
*
* The minimum value which can be held in a #gshort.
+ *
+ * This is the same as standard C `SHRT_MIN`, which is available since C99
+ * and should be preferred in new code.
*/
@@ -4308,6 +4457,22 @@
*
* This macro is defined only on UNIX. So you can bracket
* UNIX-specific code in "\#ifdef G_OS_UNIX".
+ *
+ * To detect whether to compile features that require a specific kernel
+ * or operating system, check for the appropriate OS-specific predefined
+ * macros instead, for example:
+ *
+ * - Linux kernel (any libc, including glibc, musl or Android): `\#ifdef __linux__`
+ * - Linux kernel and GNU user-space: `\#if defined(__linux__) && defined(__GLIBC__)`
+ * - FreeBSD kernel (any libc, including glibc): `\#ifdef __FreeBSD_kernel__`
+ * - FreeBSD kernel and user-space: `\#ifdef __FreeBSD__`
+ *
+ * See <https://sourceforge.net/p/predef/wiki/OperatingSystems/> for more.
+ *
+ * GLib defines OS-detection macros for some categories of systems
+ * that can be less straightforward to detect, such as %G_OS_DARWIN, but
+ * intentionally does not provide its own equivalents of macros like
+ * `__linux__`.
*/
@@ -4588,7 +4753,12 @@
*
* Returns the offset, in bytes, of a member of a struct.
*
- * Returns: the offset of @member from the start of @struct_type
+ * Consider using standard C `offsetof()`, available since at least C89
+ * and C++98, in new code (but note that `offsetof()` returns a `size_t`
+ * rather than a `long`).
+ *
+ * Returns: the offset of @member from the start of @struct_type,
+ * as a value of type #glong.
*/
@@ -4686,6 +4856,9 @@
*
* Each invocation of `G_VA_COPY (ap1, ap2)` must be matched with a
* corresponding `va_end (ap1)` call in the same function.
+ *
+ * This is equivalent to standard C `va_copy()`, available since C99
+ * and C++11, which should be preferred in new code.
*/
@@ -11765,6 +11938,60 @@
/**
+ * g_autofd: (skip)
+ *
+ * Macro to add an attribute to a file descriptor variable to ensure
+ * automatic cleanup using g_clear_fd().
+ *
+ * This macro behaves like #g_autofree rather than g_autoptr(): it is
+ * an attribute supplied before the type name, rather than wrapping the
+ * type definition.
+ *
+ * Otherwise, this macro has similar constraints as g_autoptr(): it is
+ * only supported on GCC and clang, and the variable must be initialized
+ * (to either a valid file descriptor or a negative number).
+ *
+ * Using this macro is async-signal-safe if the constraints described above
+ * are met, so it can be used in a signal handler or after `fork()`.
+ *
+ * Any error from closing the file descriptor when it goes out of scope
+ * is ignored. Use g_clear_fd() if error-checking is required.
+ *
+ * |[
+ * gboolean
+ * operate_on_fds (GError **error)
+ * {
+ * g_autofd int fd1 = open_a_fd (..., error);
+ * g_autofd int fd2 = -1;
+ *
+ * // it is safe to return early here, nothing will be closed
+ * if (fd1 < 0)
+ * return FALSE;
+ *
+ * fd2 = open_a_fd (..., error);
+ *
+ * // fd1 will be closed automatically if we return here
+ * if (fd2 < 0)
+ * return FALSE;
+ *
+ * // fd1 and fd2 will be closed automatically if we return here
+ * if (!do_something_useful (fd1, fd2, error))
+ * return FALSE;
+ *
+ * // fd2 will be closed automatically if we return here
+ * if (!g_clear_fd (&fd1, error))
+ * return FALSE;
+ *
+ * // fd2 will be automatically closed here if still open
+ * return TRUE;
+ * }
+ * ]|
+ *
+ * Since: 2.76
+ */
+
+
+/**
* g_autofree:
*
* Macro to add an attribute to pointer variable to ensure automatic
@@ -14021,6 +14248,64 @@
/**
+ * g_clear_fd: (skip)
+ * @fd_ptr: (not nullable): a pointer to a file descriptor
+ * @error: Used to return an error on failure
+ *
+ * If @fd_ptr points to a file descriptor, close it and return
+ * whether closing it was successful, like g_close().
+ * If @fd_ptr points to a negative number, return %TRUE without closing
+ * anything.
+ * In both cases, set @fd_ptr to `-1` before returning.
+ *
+ * Like g_close(), if closing the file descriptor fails, the error is
+ * stored in both %errno and @error. If this function succeeds,
+ * %errno is undefined.
+ *
+ * This function is async-signal-safe if @error is %NULL and @fd_ptr
+ * points to either a negative number or a valid file descriptor.
+ *
+ * It is a programming error for @fd_ptr to point to a non-negative
+ * number that is not a valid file descriptor.
+ *
+ * A typical use of this function is to clean up a file descriptor at
+ * the end of its scope, whether it has been set successfully or not:
+ *
+ * |[
+ * gboolean
+ * operate_on_fd (GError **error)
+ * {
+ * gboolean ret = FALSE;
+ * int fd = -1;
+ *
+ * fd = open_a_fd (error);
+ *
+ * if (fd < 0)
+ * goto out;
+ *
+ * if (!do_something (fd, error))
+ * goto out;
+ *
+ * if (!g_clear_fd (&fd, error))
+ * goto out;
+ *
+ * ret = TRUE;
+ *
+ * out:
+ * // OK to call even if fd was never opened or was already closed
+ * g_clear_fd (&fd, NULL);
+ * return ret;
+ * }
+ * ]|
+ *
+ * This function is also useful in conjunction with #g_autofd.
+ *
+ * Returns: %TRUE on success
+ * Since: 2.76
+ */
+
+
+/**
* g_clear_handle_id: (skip)
* @tag_ptr: (not nullable): a pointer to the handler ID
* @clear_func: (not nullable): the function to call to clear the handler
@@ -17208,9 +17493,28 @@
* @error: return location for a #GError
*
* Reads the contents of the symbolic link @filename like the POSIX
- * readlink() function. The returned string is in the encoding used
+ * readlink() function.
+ *
+ * The returned string is in the encoding used
* for filenames. Use g_filename_to_utf8() to convert it to UTF-8.
*
+ * The returned string may also be a relative path. Use g_build_filename() to
+ * convert it to an absolute path:
+ * |[
+ * g_autoptr(GError) local_error = NULL;
+ * g_autofree gchar *link_target = g_file_read_link ("/etc/localtime", &local_error);
+ *
+ * if (local_error != NULL)
+ * g_error ("Error reading link: %s", local_error->message);
+ *
+ * if (!g_path_is_absolute (link_target))
+ * {
+ * g_autofree gchar *absolute_link_target = g_build_filename ("/etc", link_target, NULL);
+ * g_free (link_target);
+ * link_target = g_steal_pointer (&absolute_link_target);
+ * }
+ * ]|
+ *
* Returns: (type filename) (transfer full): A newly-allocated string with
* the contents of the symbolic link, or %NULL if an error occurred.
* Since: 2.4
@@ -39309,6 +39613,7 @@
* bytes and containers containing only these things (recursively).
*
* The returned value is always in normal form and is marked as trusted.
+ * A full, not floating, reference is returned.
*
* Returns: (transfer full): the byteswapped form of @value
* Since: 2.24
@@ -42712,49 +43017,72 @@
/**
* gchar:
*
- * Corresponds to the standard C char type.
+ * Equivalent to the standard C `char` type.
+ *
+ * This type only exists for symmetry with `guchar`.
+ * The standard C `char` type should be preferred in new code.
*/
/**
* gconstpointer:
*
- * An untyped pointer to constant data.
+ * An untyped pointer to constant data, exactly equivalent to `const void *`.
+ *
* The data pointed to should not be changed.
*
* This is typically used in function prototypes to indicate
* that the data pointed to will not be altered by the function.
+ *
+ * The standard C `const void *` type should usually be preferred in
+ * new code, but `gconstpointer` can be used in contexts where a type name
+ * must be a single word.
*/
/**
* gdouble:
*
- * Corresponds to the standard C double type.
- * Values of this type can range from -%G_MAXDOUBLE to %G_MAXDOUBLE.
+ * Equivalent to the standard C `double` type.
+ *
+ * Values of this type can range from `-DBL_MAX` to `DBL_MAX`,
+ * or equivalently from -%G_MAXDOUBLE to %G_MAXDOUBLE.
*/
/**
* gfloat:
*
- * Corresponds to the standard C float type.
- * Values of this type can range from -%G_MAXFLOAT to %G_MAXFLOAT.
+ * Equivalent to the standard C `float` type.
+ *
+ * Values of this type can range from `-FLT_MAX` to `FLT_MAX`,
+ * or equivalently from -%G_MAXFLOAT to %G_MAXFLOAT.
*/
/**
* gint:
*
- * Corresponds to the standard C int type.
- * Values of this type can range from %G_MININT to %G_MAXINT.
+ * Equivalent to the standard C `int` type.
+ *
+ * Values of this type can range from `INT_MIN` to `INT_MAX`,
+ * or equivalently from %G_MININT to %G_MAXINT.
+ *
+ * This type only exists for symmetry with `guint`.
+ * The standard C `int` type should be preferred in new code.
*/
/**
* gint16:
*
- * A signed integer guaranteed to be 16 bits on all platforms.
+ * A signed integer guaranteed to be 16 bits on all platforms,
+ * similar to the standard C `int16_t`.
+ *
+ * The `int16_t` type should be preferred in new code, unless
+ * consistency with pre-existing APIs requires use of `gint16`
+ * (see #gsize for more details).
+ *
* Values of this type can range from %G_MININT16 (= -32,768) to
* %G_MAXINT16 (= 32,767).
*
@@ -42767,31 +43095,64 @@
* gint32:
*
* A signed integer guaranteed to be 32 bits on all platforms.
+ *
+ * The `int32_t` type should be preferred in new code, unless
+ * consistency with pre-existing APIs requires use of `gint16`
+ * (see #gsize for more details).
+ *
* Values of this type can range from %G_MININT32 (= -2,147,483,648)
* to %G_MAXINT32 (= 2,147,483,647).
*
* To print or scan values of this type, use
* %G_GINT32_MODIFIER and/or %G_GINT32_FORMAT.
+ *
+ * Note that on platforms with more than one 32-bit standard integer type,
+ * `gint32` and `int32_t` are not necessarily implemented by the same
+ * 32-bit integer type.
+ * For example, on an ILP32 platform where `int` and `long` are both 32-bit,
+ * it might be the case that one of these types is `int` and the other
+ * is `long`.
+ * See #gsize for more details of what this implies.
*/
/**
* gint64:
*
- * A signed integer guaranteed to be 64 bits on all platforms.
+ * A signed integer guaranteed to be 64 bits on all platforms,
+ * similar to the standard C `int64_t`.
+ *
+ * The `int64_t` type should be preferred in new code, unless
+ * consistency with pre-existing APIs requires use of `gint64`
+ * (see #gsize for more details).
+ *
* Values of this type can range from %G_MININT64
* (= -9,223,372,036,854,775,808) to %G_MAXINT64
* (= 9,223,372,036,854,775,807).
*
* To print or scan values of this type, use
* %G_GINT64_MODIFIER and/or %G_GINT64_FORMAT.
+ *
+ * Note that on platforms with more than one 64-bit standard integer type,
+ * `gint64` and `int64_t` are not necessarily implemented by the same
+ * 64-bit integer type.
+ * For example, on a platform where both `long` and `long long` are 64-bit,
+ * it might be the case that one of those types is used for `gint64`
+ * and the other is used for `int64_t`.
+ * See #gsize for more details of what this implies.
*/
/**
* gint8:
*
- * A signed integer guaranteed to be 8 bits on all platforms.
+ * A signed integer guaranteed to be 8 bits on all platforms,
+ * similar to the standard C `int8_t`.
+ *
+ * The `int8_t` type should be preferred in new code, unless
+ * consistency with pre-existing APIs requires use of `gint8`
+ * (see #gsize for more details).
+ *
* Values of this type can range from %G_MININT8 (= -128) to
* %G_MAXINT8 (= 127).
*/
@@ -42803,6 +43164,14 @@
* Corresponds to the C99 type intptr_t,
* a signed integer type that can hold any pointer.
*
+ * The standard `intptr_t` type should be preferred in new code, unless
+ * consistency with pre-existing APIs requires `gintptr`.
+ * Note that `intptr_t` and `gintptr` might be implemented by different
+ * standard integer types of the same size. See #gsize for more details.
+ *
+ * #gintptr is not guaranteed to be the same type or the same size as #gssize,
+ * even though they are the same on many CPU architectures.
+ *
* To print or scan values of this type, use
* %G_GINTPTR_MODIFIER and/or %G_GINTPTR_FORMAT.
*
@@ -42943,8 +43312,13 @@
/**
* glong:
*
- * Corresponds to the standard C long type.
- * Values of this type can range from %G_MINLONG to %G_MAXLONG.
+ * Equivalent to the standard C `long` type.
+ *
+ * Values of this type can range from `LONG_MIN` to `LONG_MAX`,
+ * or equivalently %G_MINLONG to %G_MAXLONG.
+ *
+ * This type only exists for symmetry with `gulong`.
+ * The standard C `long` type should be preferred in new code.
*/
@@ -42954,13 +43328,18 @@
* A signed integer type that is used for file offsets,
* corresponding to the POSIX type `off_t` as if compiling with
* `_FILE_OFFSET_BITS` set to 64. #goffset is always 64 bits wide, even on
- * 32-bit architectures.
+ * 32-bit architectures, and even if `off_t` is only 32 bits.
* Values of this type can range from %G_MINOFFSET to
* %G_MAXOFFSET.
*
* To print or scan values of this type, use
* %G_GOFFSET_MODIFIER and/or %G_GOFFSET_FORMAT.
*
+ * On platforms with more than one 64-bit standard integer type,
+ * even if `off_t` is also 64 bits in size, `goffset` and `off_t` are not
+ * necessarily implemented by the same 64-bit integer type.
+ * See #gsize for more details of what this implies.
+ *
* Since: 2.14
*/
@@ -42968,8 +43347,13 @@
/**
* gpointer:
*
- * An untyped pointer.
- * #gpointer looks better and is easier to use than void*.
+ * An untyped pointer, exactly equivalent to `void *`.
+ *
+ * The standard C `void *` type should usually be preferred in
+ * new code, but `gpointer` can be used in contexts where a type name
+ * must be a single word, such as in the g_type_name() of %G_TYPE_POINTER
+ * or when generating a family of function names for multiple types
+ * using macros.
*/
@@ -42995,23 +43379,62 @@
/**
* gshort:
*
- * Corresponds to the standard C short type.
- * Values of this type can range from %G_MINSHORT to %G_MAXSHORT.
+ * Equivalent to the standard C `short` type.
+ *
+ * Values of this type can range from `SHRT_MIN` to `SHRT_MAX`,
+ * or equivalently %G_MINSHORT to %G_MAXSHORT.
+ *
+ * This type only exists for symmetry with `gushort`.
+ * The standard C `short` type should be preferred in new code.
*/
/**
* 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.
+ *
+ * The standard `size_t` type should be preferred in new code, unless
+ * consistency with pre-existing APIs requires `gsize`
+ * (see below for more details).
+ *
+ * `gsize` 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.
+ *
+ * Note that on platforms where more than one standard integer type is
+ * the same size, `size_t` and `gsize` are always the same size but are
+ * not necessarily implemented by the same standard integer type.
+ * For example, on an ILP32 platform where `int`, `long` and pointers
+ * are all 32-bit, `size_t` might be `unsigned long` while `gsize`
+ * might be `unsigned int`.
+ * This can result in compiler warnings or unexpected C++ name-mangling
+ * if the two types are used inconsistently.
+ *
+ * As a result, changing a type from `gsize` to `size_t` in existing APIs
+ * might be an incompatible API or ABI change, especially if C++
+ * is involved. The safe option is to leave existing APIs using the same type
+ * that they have historically used, and only use the standard C types in
+ * new APIs.
+ *
+ * Similar considerations apply to all the fixed-size types
+ * (#gint8, #guint8, #gint16, #guint16, #gint32, #guint32, #gint64,
+ * #guint64 and #goffset), as well as #gintptr and #guintptr.
+ * Types that are 32 bits or larger are particularly likely to be
+ * affected by this.
*/
@@ -43019,10 +43442,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.
*/
@@ -43031,22 +43467,42 @@
/**
* guchar:
*
- * Corresponds to the standard C unsigned char type.
+ * Equivalent to the standard C `unsigned char` type.
+ *
+ * The standard C `unsigned char` type should usually be preferred in
+ * new code, but `guchar` can be used in contexts where a type name
+ * must be a single word, such as in the g_type_name() of %G_TYPE_UCHAR
+ * or when generating a family of function names for multiple types
+ * using macros.
*/
/**
* guint:
*
- * Corresponds to the standard C unsigned int type.
- * Values of this type can range from 0 to %G_MAXUINT.
+ * Equivalent to the standard C `unsigned int` type.
+ *
+ * Values of this type can range from 0 to `UINT_MAX`,
+ * or equivalently 0 to %G_MAXUINT.
+ *
+ * The standard C `unsigned int` type should usually be preferred in
+ * new code, but `guint` can be used in contexts where a type name
+ * must be a single word, such as in the g_type_name() of %G_TYPE_UINT
+ * or when generating a family of function names for multiple types
+ * using macros.
*/
/**
* guint16:
*
- * An unsigned integer guaranteed to be 16 bits on all platforms.
+ * An unsigned integer guaranteed to be 16 bits on all platforms,
+ * similar to the standard C `uint16_t`.
+ *
+ * The `uint16_t` type should be preferred in new code, unless
+ * consistency with pre-existing APIs requires use of `guint16`
+ * (see #gsize for more details).
+ *
* Values of this type can range from 0 to %G_MAXUINT16 (= 65,535).
*
* To print or scan values of this type, use
@@ -43057,30 +43513,58 @@
/**
* guint32:
*
- * An unsigned integer guaranteed to be 32 bits on all platforms.
+ * An unsigned integer guaranteed to be 32 bits on all platforms,
+ * similar to the standard C `uint32_t`.
+ *
+ * The `uint32_t` type should be preferred in new code, unless
+ * consistency with pre-existing APIs requires use of `guint32`
+ * (see #gsize for more details).
+ *
* Values of this type can range from 0 to %G_MAXUINT32 (= 4,294,967,295).
*
* To print or scan values of this type, use
* %G_GINT32_MODIFIER and/or %G_GUINT32_FORMAT.
+ *
+ * Note that on platforms with more than one 32-bit standard integer type,
+ * `guint32` and `uint32_t` are not necessarily implemented by the same
+ * 32-bit integer type.
+ * See #gsize for more details of what this implies.
*/
/**
* guint64:
*
- * An unsigned integer guaranteed to be 64-bits on all platforms.
+ * An unsigned integer guaranteed to be 64-bits on all platforms,
+ * similar to the standard C `uint64_t` type.
+ *
+ * The `uint64_t` type should be preferred in new code, unless
+ * consistency with pre-existing APIs requires use of `guint64`
+ * (see #gsize for more details).
+ *
* Values of this type can range from 0 to %G_MAXUINT64
* (= 18,446,744,073,709,551,615).
*
* To print or scan values of this type, use
* %G_GINT64_MODIFIER and/or %G_GUINT64_FORMAT.
+ *
+ * Note that on platforms with more than one 64-bit standard integer type,
+ * `guint64` and `uint64_t` are not necessarily implemented by the same
+ * 64-bit integer type.
+ * See #gsize for more details of what this implies.
*/
/**
* guint8:
*
- * An unsigned integer guaranteed to be 8 bits on all platforms.
+ * An unsigned integer guaranteed to be 8 bits on all platforms,
+ * similar to the standard C `uint8_t`.
+ *
+ * The `uint8_t` type should be preferred in new code, unless
+ * consistency with pre-existing APIs requires use of `guint8`
+ * (see #gsize for more details).
+ *
* Values of this type can range from 0 to %G_MAXUINT8 (= 255).
*/
@@ -43091,6 +43575,14 @@
* Corresponds to the C99 type uintptr_t,
* an unsigned integer type that can hold any pointer.
*
+ * The standard `uintptr_t` type should be preferred in new code, unless
+ * consistency with pre-existing APIs requires `guintptr`.
+ * Note that `uintptr_t` and `guintptr` might be implemented by different
+ * standard integer types of the same size. See #gsize for more details.
+ *
+ * #guintptr is not guaranteed to be the same type or the same size as #gsize,
+ * even though they are the same on many CPU architectures.
+ *
* To print or scan values of this type, use
* %G_GINTPTR_MODIFIER and/or %G_GUINTPTR_FORMAT.
*
@@ -43101,16 +43593,30 @@
/**
* gulong:
*
- * Corresponds to the standard C unsigned long type.
+ * Equivalent to the standard C `unsigned long` type.
+ *
* Values of this type can range from 0 to %G_MAXULONG.
+ *
+ * The standard C `unsigned long` type should usually be preferred in
+ * new code, but `gulong` can be used in contexts where a type name
+ * must be a single word, such as in the g_type_name() of %G_TYPE_ULONG
+ * or when generating a family of function names for multiple types
+ * using macros.
*/
/**
* gushort:
*
- * Corresponds to the standard C unsigned short type.
- * Values of this type can range from 0 to %G_MAXUSHORT.
+ * Equivalent to the standard C `unsigned short` type.
+ *
+ * Values of this type can range from 0 to `USHRT_MAX`,
+ * or equivalently from 0 to %G_MAXUSHORT.
+ *
+ * The standard C `unsigned short` type should usually be preferred in
+ * new code, but `gushort` can be used in contexts where a type name
+ * must be a single word, such as when generating a family of function
+ * names for multiple types using macros.
*/
diff --git a/gir/gmodule-2.0.c b/gir/gmodule-2.0.c
index e07a8823..512fd455 100644
--- a/gir/gmodule-2.0.c
+++ b/gir/gmodule-2.0.c
@@ -75,9 +75,24 @@
/**
* G_MODULE_SUFFIX:
*
- * Expands to the proper shared library suffix for the current platform
- * without the leading dot. For most Unices and Linux this is "so", and
- * for Windows this is "dll".
+ * Expands to a shared library suffix for the current platform without the
+ * leading dot. On Unixes this is "so", and on Windows this is "dll".
+ *
+ * Deprecated: 2.76: Use g_module_open() instead with @module_name as the
+ * basename of the file_name argument. You will get the wrong results using
+ * this macro most of the time:
+ *
+ * 1. The suffix on macOS is usually 'dylib', but it's 'so' when using
+ * Autotools, so there's no way to get the suffix correct using
+ * a pre-processor macro.
+ * 2. Prefixes also vary in a platform-specific way. You may or may not have
+ * a 'lib' prefix for the name on Windows and on Cygwin the prefix is
+ * 'cyg'.
+ * 3. The library name itself can vary per platform. For instance, you may
+ * want to load foo-1.dll on Windows and libfoo.1.dylib on macOS.
+ *
+ * g_module_open() takes care of all this by searching the filesystem for
+ * combinations of possible suffixes and prefixes.
*/
@@ -184,6 +199,8 @@
*
* Returns: the complete path of the module, including the standard library
* prefix and suffix. This should be freed when no longer needed
+ * Deprecated: 2.76: Use g_module_open() instead with @module_name as the
+ * basename of the file_name argument. See %G_MODULE_SUFFIX for why.
*/
@@ -229,8 +246,8 @@
/**
* g_module_open:
- * @file_name: (nullable): the name of the file containing the module, or %NULL
- * to obtain a #GModule representing the main program itself
+ * @file_name: (nullable): the name or path to the file containing the module,
+ * or %NULL to obtain a #GModule representing the main program itself
* @flags: the flags used for opening the module. This can be the
* logical OR of any of the #GModuleFlags.
*
@@ -242,24 +259,28 @@
/**
* g_module_open_full:
- * @file_name: (nullable): the name of the file containing the module, or %NULL
- * to obtain a #GModule representing the main program itself
+ * @file_name: (nullable): the name or path to the file containing the module,
+ * or %NULL to obtain a #GModule representing the main program itself
* @flags: the flags used for opening the module. This can be the
* logical OR of any of the #GModuleFlags
* @error: #GError.
*
- * Opens a module. If the module has already been opened,
- * its reference count is incremented.
- *
- * First of all g_module_open_full() tries to open @file_name as a module.
- * If that fails and @file_name has the ".la"-suffix (and is a libtool
- * archive) it tries to open the corresponding module. If that fails
- * and it doesn't have the proper module suffix for the platform
- * (%G_MODULE_SUFFIX), this suffix will be appended and the corresponding
- * module will be opened. If that fails and @file_name doesn't have the
- * ".la"-suffix, this suffix is appended and g_module_open_full() tries to open
- * the corresponding module. If eventually that fails as well, %NULL is
- * returned.
+ * Opens a module. If the module has already been opened, its reference count
+ * is incremented. If not, the module is searched in the following order:
+ *
+ * 1. If @file_name exists as a regular file, it is used as-is; else
+ * 2. If @file_name doesn't have the correct suffix and/or prefix for the
+ * platform, then possible suffixes and prefixes will be added to the
+ * basename till a file is found and whatever is found will be used; else
+ * 3. If @file_name doesn't have the ".la"-suffix, ".la" is appended. Either
+ * way, if a matching .la file exists (and is a libtool archive) the
+ * libtool archive is parsed to find the actual file name, and that is
+ * used.
+ *
+ * At the end of all this, we would have a file path that we can access on
+ * disk, and it is opened as a module. If not, @file_name is opened as
+ * a module verbatim in the hopes that the system implementation will somehow
+ * be able to access it.
*
* Returns: a #GModule on success, or %NULL on failure
* Since: 2.70