luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-07-24 10:57:53 +02:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch '3658-file-info-docs' into 'main'

Browse Source 
gfile: Expand documentation around file info for inaccessible files

See merge request GNOME/glib!4585
This commit is contained in:
Philip Withnall
2025-04-08 16:19:34 +00:00
parent 2cd78508cc a33df3d81e
commit 551cdd98dc
1 changed files with 32 additions and 21 deletions
Download Patch File Download Diff File Expand all files Collapse all files

53
gio/gfile.c
View File

@@ -1288,46 +1288,57 @@ g_file_query_file_type (GFile *file,
/**
* g_file_query_info:
* @file: input #GFile
* @file: input file
* @attributes: an attribute query string
* @flags: a set of #GFileQueryInfoFlags
* @cancellable: (nullable): optional #GCancellable object,
* %NULL to ignore
* @error: a #GError
* @flags: flags to affect the query operation
* @cancellable: (nullable): optional cancellable object
* @error: return location for an error
*
* Gets the requested information about specified @file.
* The result is a #GFileInfo object that contains key-value
*
* The result is a [class@Gio.FileInfo] object that contains key-value
* attributes (such as the type or size of the file).
*
* The @attributes value is a string that specifies the file
* attributes that should be gathered. It is not an error if
* it's not possible to read a particular requested attribute
* from a file - it just won't be set. @attributes should be a
* comma-separated list of attributes or attribute wildcards.
* The wildcard "*" means all attributes, and a wildcard like
* "standard::*" means all attributes in the standard namespace.
* An example attribute query be "standard::*,owner::user".
* The standard attributes are available as defines, like
* %G_FILE_ATTRIBUTE_STANDARD_NAME.
* it’s not possible to read a particular requested attribute
* from a file — it just won't be set. In particular this means that if a file
* is inaccessible (due to being in a folder with restrictive permissions), for
* example, you can expect the returned [class@Gio.FileInfo] to have very few
* attributes set. You should check whether an attribute is set using
* [method@Gio.FileInfo.has_attribute] before trying to retrieve its value.
*
* If @cancellable is not %NULL, then the operation can be cancelled
* It is guaranteed that if any of the following attributes are listed in
* @attributes, they will always be set in the returned [class@Gio.FileInfo],
* even if the user doesn’t have permissions to access the file:
*
* - [const@Gio.FILE_ATTRIBUTE_STANDARD_NAME]
* - [const@Gio.FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME]
*
* @attributes should be a comma-separated list of attributes or attribute
* wildcards. The wildcard `"*"` means all attributes, and a wildcard like
* `"standard::*"` means all attributes in the standard namespace.
* An example attribute query might be `"standard::*,owner::user"`.
* The standard attributes are available as defines, like
* [const@Gio.FILE_ATTRIBUTE_STANDARD_NAME].
*
* If @cancellable is not `NULL`, then the operation can be cancelled
* by triggering the cancellable object from another thread. If the
* operation was cancelled, the error %G_IO_ERROR_CANCELLED will be
* operation was cancelled, the error [error@Gio.IOErrorEnum.CANCELLED] will be
* returned.
*
* For symlinks, normally the information about the target of the
* symlink is returned, rather than information about the symlink
* itself. However if you pass %G_FILE_QUERY_INFO_NOFOLLOW_SYMLINKS
* itself. However if you pass [flags@Gio.FileQueryInfoFlags.NOFOLLOW_SYMLINKS]
* in @flags the information about the symlink itself will be returned.
* Also, for symlinks that point to non-existing files the information
* about the symlink itself will be returned.
*
* If the file does not exist, the %G_IO_ERROR_NOT_FOUND error will be
* If the file does not exist, the [error@Gio.IOErrorEnum.NOT_FOUND] error will be
* returned. Other errors are possible too, and depend on what kind of
* filesystem the file is on.
* file system the file is on.
*
* Returns: (transfer full): a #GFileInfo for the given @file, or %NULL
* on error. Free the returned object with g_object_unref().
* Returns: (transfer full): a [class@Gio.FileInfo] for the given @file
*/
GFileInfo *
g_file_query_info (GFile *file,