From b961111c97523496ead03da0e84fad4201c6bd2c Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Wed, 17 Sep 2025 09:31:44 +0100 Subject: [PATCH] gfile: Expand documentation around file equality Prompted by https://discourse.gnome.org/t/help-on-g-file-equal-and-g-file-attribute-id-file/31268/5. Signed-off-by: Philip Withnall --- gio/gfile.c | 10 +++++++++- gio/gfileinfo.h | 7 +++++++ 2 files changed, 16 insertions(+), 1 deletion(-) diff --git a/gio/gfile.c b/gio/gfile.c index 442e9f6f1..38b1931ac 100644 --- a/gio/gfile.c +++ b/gio/gfile.c @@ -783,9 +783,17 @@ g_file_hash (gconstpointer file) * * Checks if the two given #GFiles refer to the same file. * + * This function can be used with [method@Gio.File.hash] to insert + * [iface@Gio.File]s efficiently in a hash table. + * * Note that two #GFiles that differ can still refer to the same * file on the filesystem due to various forms of filename - * aliasing. + * aliasing. For local files, this function essentially compares the file paths, + * so two [iface@Gio.File]s which point to different hard or soft links will not + * be considered equal, despite pointing to the same content. + * + * For determining whether two files are hardlinked, see + * [const@Gio.FILE_ATTRIBUTE_ID_FILE]. * * This call does no blocking I/O. * diff --git a/gio/gfileinfo.h b/gio/gfileinfo.h index 6e4f02dce..30c49f99b 100644 --- a/gio/gfileinfo.h +++ b/gio/gfileinfo.h @@ -311,6 +311,13 @@ typedef struct _GFileInfoClass GFileInfoClass; * * An example use would be during listing files, to avoid recursive * directory scanning. + * + * For local files on Linux, this is a combination of the file’s device number + * and inode, so is invariant with respect to hard linking. The format used by + * other VFS implementations may vary, and some VFS backends may not set it. + * + * For simply seeing if two [iface@Gio.File] instances refer to the same path + * on disk, see [method@Gio.File.equal]. **/ #define G_FILE_ATTRIBUTE_ID_FILE "id::file" /* string */