luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-11-06 11:08:56 +01: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

51
gio/gfile.c
View File

@@ -1288,46 +1288,57 @@ g_file_query_file_type (GFile *file,
/** /**
* g_file_query_info: * g_file_query_info:
* @file: input #GFile * @file: input file
* @attributes: an attribute query string * @attributes: an attribute query string
* @flags: a set of #GFileQueryInfoFlags * @flags: flags to affect the query operation
* @cancellable: (nullable): optional #GCancellable object, * @cancellable: (nullable): optional cancellable object
* %NULL to ignore * @error: return location for an error
* @error: a #GError
* *
* Gets the requested information about specified @file. * 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). * attributes (such as the type or size of the file).
* *
* The @attributes value is a string that specifies the file * The @attributes value is a string that specifies the file
* attributes that should be gathered. It is not an error if * attributes that should be gathered. It is not an error if
* it's not possible to read a particular requested attribute * it’s not possible to read a particular requested attribute
* from a file - it just won't be set. @attributes should be a * from a file — it just won't be set. In particular this means that if a file
* comma-separated list of attributes or attribute wildcards. * is inaccessible (due to being in a folder with restrictive permissions), for
* The wildcard "*" means all attributes, and a wildcard like * example, you can expect the returned [class@Gio.FileInfo] to have very few
* "standard::*" means all attributes in the standard namespace. * attributes set. You should check whether an attribute is set using
* An example attribute query be "standard::*,owner::user". * [method@Gio.FileInfo.has_attribute] before trying to retrieve its value.
* The standard attributes are available as defines, like
* %G_FILE_ATTRIBUTE_STANDARD_NAME.
* *
* 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 * 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. * returned.
* *
* For symlinks, normally the information about the target of the * For symlinks, normally the information about the target of the
* symlink is returned, rather than information about the symlink * 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. * in @flags the information about the symlink itself will be returned.
* Also, for symlinks that point to non-existing files the information * Also, for symlinks that point to non-existing files the information
* about the symlink itself will be returned. * 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 * returned. Other errors are possible too, and depend on what kind of
* file system the file is on. * file system the file is on.
* *
* Returns: (transfer full): a #GFileInfo for the given @file, or %NULL * Returns: (transfer full): a [class@Gio.FileInfo] for the given @file
* on error. Free the returned object with g_object_unref().
*/ */
GFileInfo * GFileInfo *
g_file_query_info (GFile *file, g_file_query_info (GFile *file,