From 508e164056e6557c4c9f0d34e6ec899430ac37dd Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Mon, 23 Oct 2023 13:12:02 +0100 Subject: [PATCH] docs: Move the GFileAttribute SECTION to Markdown MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit It needs to be in a separate page because there isn’t actually a `GFileAttribute` type. Signed-off-by: Philip Withnall Helps: #3037 --- docs/reference/gio/file-attributes.md | 111 ++++++++++++++++++++++++++ docs/reference/gio/gio.toml.in | 1 + docs/reference/gio/meson.build | 1 + gio/gfileattribute.c | 107 ------------------------- 4 files changed, 113 insertions(+), 107 deletions(-) create mode 100644 docs/reference/gio/file-attributes.md diff --git a/docs/reference/gio/file-attributes.md b/docs/reference/gio/file-attributes.md new file mode 100644 index 000000000..c9f1fe70a --- /dev/null +++ b/docs/reference/gio/file-attributes.md @@ -0,0 +1,111 @@ +Title: File Attributes +SPDX-License-Identifier: LGPL-2.1-or-later +SPDX-FileCopyrightText: 2007 Andrew Walton +SPDX-FileCopyrightText: 2007 Alexander Larsson +SPDX-FileCopyrightText: 2008, 2014 Matthias Clasen +SPDX-FileCopyrightText: 2011 Murray Cumming +SPDX-FileCopyrightText: 2012 David King + +# File Attributes + +File attributes in GIO consist of a list of key-value pairs. + +Keys are strings that contain a key namespace and a key name, separated +by a colon, e.g. `namespace::keyname`. Namespaces are included to sort +key-value pairs by namespaces for relevance. Keys can be retrieved +using wildcards, e.g. `standard::*` will return all of the keys in the +`standard` namespace. + +The list of possible attributes for a filesystem (pointed to by a +[iface@Gio.File]) is available as a [struct@Gio.FileAttributeInfoList]. This +list is queryable by key names as indicated earlier. + +Information is stored within the list in [struct@Gio.FileAttributeInfo] +structures. The info structure can store different types, listed in the enum +[type@Gio.FileAttributeType]. Upon creation of a [struct@Gio.FileAttributeInfo], +the type will be set to `G_FILE_ATTRIBUTE_TYPE_INVALID`. + +Classes that implement [iface@Gio.File] will create a +[struct@Gio.FileAttributeInfoList] and install default keys and values for their +given file system, architecture, and other possible implementation details +(e.g., on a UNIX system, a file attribute key will be registered for the user ID +for a given file). + +## Default Namespaces + +- `"standard"`: The ‘Standard’ namespace. General file information that + any application may need should be put in this namespace. Examples + include the file’s name, type, and size. +- `"etag`: The [Entity Tag](gfile.html#entity-tags) namespace. Currently, the + only key in this namespace is `value`, which contains the value of the current + entity tag. +- `"id"`: The ‘Identification’ namespace. This namespace is used by file + managers and applications that list directories to check for loops and + to uniquely identify files. +- `"access"`: The ‘Access’ namespace. Used to check if a user has the + proper privileges to access files and perform file operations. Keys in + this namespace are made to be generic and easily understood, e.g. the + `can_read` key is true if the current user has permission to read the + file. UNIX permissions and NTFS ACLs in Windows should be mapped to + these values. +- `"mountable"`: The ‘Mountable’ namespace. Includes simple boolean keys + for checking if a file or path supports mount operations, e.g. mount, + unmount, eject. These are used for files of type `G_FILE_TYPE_MOUNTABLE`. +- `"time"`: The ‘Time’ namespace. Includes file access, changed, created + times. +- `"unix"`: The ‘Unix’ namespace. Includes UNIX-specific information and + may not be available for all files. Examples include the UNIX UID, + GID, etc. +- `"dos"`: The ‘DOS’ namespace. Includes DOS-specific information and may + not be available for all files. Examples include `is_system` for checking + if a file is marked as a system file, and `is_archive` for checking if a + file is marked as an archive file. +- `"owner"`: The ‘Owner’ namespace. Includes information about who owns a + file. May not be available for all file systems. Examples include `user` + for getting the user name of the file owner. This information is often + mapped from some backend specific data such as a UNIX UID. +- `"thumbnail"`: The ‘Thumbnail’ namespace. Includes information about file + thumbnails and their location within the file system. Examples of keys in + this namespace include `path` to get the location of a thumbnail, `failed` + to check if thumbnailing of the file failed, and `is-valid` to check if + the thumbnail is outdated. +- `"filesystem"`: The ‘Filesystem’ namespace. Gets information about the + file system where a file is located, such as its type, how much space is + left available, and the overall size of the file system. +- `"gvfs"`: The ‘GVFS’ namespace. Keys in this namespace contain information + about the current GVFS backend in use. +- `"xattr"`: The ‘xattr’ namespace. Gets information about extended user + attributes. See [`attr(5)`](man:attr(5)). The `user.` prefix of the extended + user attribute name is stripped away when constructing keys in this namespace, + e.g. `xattr::mime_type` for the extended attribute with the name + `user.mime_type`. Note that this information is only available if + GLib has been built with extended attribute support. +- `"xattr-sys"`: The ‘xattr-sys’ namespace. Gets information about + extended attributes which are not user-specific. See [`attr(5)`](man:attr(5)). + Note that this information is only available if GLib has been built with + extended attribute support. +- `"selinux"`: The ‘SELinux’ namespace. Includes information about the + SELinux context of files. Note that this information is only available + if GLib has been built with SELinux support. + +Please note that these are not all of the possible namespaces. +More namespaces can be added from GIO modules or by individual applications. +For more information about writing GIO modules, see [class@Gio.IOModule]. + + + +## Default Keys + +For a list of the built-in keys and their types, see the [class@Gio.FileInfo] +documentation. + +Note that there are no predefined keys in the `xattr` and `xattr-sys` +namespaces. Keys for the `xattr` namespace are constructed by stripping +away the `user.` prefix from the extended user attribute, and prepending +`xattr::`. Keys for the `xattr-sys` namespace are constructed by +concatenating `xattr-sys::` with the extended attribute name. All extended +attribute values are returned as hex-encoded strings in which bytes outside +the ASCII range are encoded as escape sequences of the form `\xnn` +where `nn` is a 2-digit hexadecimal number. + diff --git a/docs/reference/gio/gio.toml.in b/docs/reference/gio/gio.toml.in index 9fe1b3fba..d62bbd15e 100644 --- a/docs/reference/gio/gio.toml.in +++ b/docs/reference/gio/gio.toml.in @@ -41,6 +41,7 @@ urlmap_file = "urlmap.js" # The same order will be used when generating the index content_files = [ "overview.md", + "file-attributes.md", "migrating-gdbus.md", "migrating-gconf.md", diff --git a/docs/reference/gio/meson.build b/docs/reference/gio/meson.build index e16554aa6..bdcdde601 100644 --- a/docs/reference/gio/meson.build +++ b/docs/reference/gio/meson.build @@ -229,6 +229,7 @@ endif # gi-docgen version expand_content_files = [ + 'file-attributes.md', 'migrating-gconf.md', 'migrating-gdbus.md', 'migrating-gnome-vfs.md', diff --git a/gio/gfileattribute.c b/gio/gfileattribute.c index 124eb4d07..c6fde60fa 100644 --- a/gio/gfileattribute.c +++ b/gio/gfileattribute.c @@ -30,113 +30,6 @@ #include "glibintl.h" -/** - * SECTION:gfileattribute - * @short_description: Key-Value Paired File Attributes - * @include: gio/gio.h - * @see_also: #GFile, #GFileInfo - * - * File attributes in GIO consist of a list of key-value pairs. - * - * Keys are strings that contain a key namespace and a key name, separated - * by a colon, e.g. "namespace::keyname". Namespaces are included to sort - * key-value pairs by namespaces for relevance. Keys can be retrieved - * using wildcards, e.g. "standard::*" will return all of the keys in the - * "standard" namespace. - * - * The list of possible attributes for a filesystem (pointed to by a #GFile) is - * available as a #GFileAttributeInfoList. This list is queryable by key names - * as indicated earlier. - * - * Information is stored within the list in #GFileAttributeInfo structures. - * The info structure can store different types, listed in the enum - * #GFileAttributeType. Upon creation of a #GFileAttributeInfo, the type will - * be set to %G_FILE_ATTRIBUTE_TYPE_INVALID. - * - * Classes that implement #GFileIface will create a #GFileAttributeInfoList and - * install default keys and values for their given file system, architecture, - * and other possible implementation details (e.g., on a UNIX system, a file - * attribute key will be registered for the user id for a given file). - * - * ## Default Namespaces - * - * - `"standard"`: The "Standard" namespace. General file information that - * any application may need should be put in this namespace. Examples - * include the file's name, type, and size. - * - `"etag`: The [Entity Tag][gfile-etag] namespace. Currently, the only key - * in this namespace is "value", which contains the value of the current - * entity tag. - * - `"id"`: The "Identification" namespace. This namespace is used by file - * managers and applications that list directories to check for loops and - * to uniquely identify files. - * - `"access"`: The "Access" namespace. Used to check if a user has the - * proper privileges to access files and perform file operations. Keys in - * this namespace are made to be generic and easily understood, e.g. the - * "can_read" key is %TRUE if the current user has permission to read the - * file. UNIX permissions and NTFS ACLs in Windows should be mapped to - * these values. - * - `"mountable"`: The "Mountable" namespace. Includes simple boolean keys - * for checking if a file or path supports mount operations, e.g. mount, - * unmount, eject. These are used for files of type %G_FILE_TYPE_MOUNTABLE. - * - `"time"`: The "Time" namespace. Includes file access, changed, created - * times. - * - `"unix"`: The "Unix" namespace. Includes UNIX-specific information and - * may not be available for all files. Examples include the UNIX "UID", - * "GID", etc. - * - `"dos"`: The "DOS" namespace. Includes DOS-specific information and may - * not be available for all files. Examples include "is_system" for checking - * if a file is marked as a system file, and "is_archive" for checking if a - * file is marked as an archive file. - * - `"owner"`: The "Owner" namespace. Includes information about who owns a - * file. May not be available for all file systems. Examples include "user" - * for getting the user name of the file owner. This information is often - * mapped from some backend specific data such as a UNIX UID. - * - `"thumbnail"`: The "Thumbnail" namespace. Includes information about file - * thumbnails and their location within the file system. Examples of keys in - * this namespace include "path" to get the location of a thumbnail, "failed" - * to check if thumbnailing of the file failed, and "is-valid" to check if - * the thumbnail is outdated. - * - `"filesystem"`: The "Filesystem" namespace. Gets information about the - * file system where a file is located, such as its type, how much space is - * left available, and the overall size of the file system. - * - `"gvfs"`: The "GVFS" namespace. Keys in this namespace contain information - * about the current GVFS backend in use. - * - `"xattr"`: The "xattr" namespace. Gets information about extended - * user attributes. See attr(5). The "user." prefix of the extended user - * attribute name is stripped away when constructing keys in this namespace, - * e.g. "xattr::mime_type" for the extended attribute with the name - * "user.mime_type". Note that this information is only available if - * GLib has been built with extended attribute support. - * - `"xattr-sys"`: The "xattr-sys" namespace. Gets information about - * extended attributes which are not user-specific. See attr(5). Note - * that this information is only available if GLib has been built with - * extended attribute support. - * - `"selinux"`: The "SELinux" namespace. Includes information about the - * SELinux context of files. Note that this information is only available - * if GLib has been built with SELinux support. - * - * Please note that these are not all of the possible namespaces. - * More namespaces can be added from GIO modules or by individual applications. - * For more information about writing GIO modules, see #GIOModule. - * - * - * - * ## Default Keys - * - * For a list of the built-in keys and their types, see the - * [GFileInfo][GFileInfo] documentation. - * - * Note that there are no predefined keys in the "xattr" and "xattr-sys" - * namespaces. Keys for the "xattr" namespace are constructed by stripping - * away the "user." prefix from the extended user attribute, and prepending - * "xattr::". Keys for the "xattr-sys" namespace are constructed by - * concatenating "xattr-sys::" with the extended attribute name. All extended - * attribute values are returned as hex-encoded strings in which bytes outside - * the ASCII range are encoded as escape sequences of the form \x`nn` - * where `nn` is a 2-digit hexadecimal number. - */ - /** * _g_file_attribute_value_free: * @attr: a #GFileAttributeValue.