mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2025-07-23 10:27:51 +02:00
docs: Move the GFileAttribute SECTION to Markdown
It needs to be in a separate page because there isn’t actually a `GFileAttribute` type. Signed-off-by: Philip Withnall <philip@tecnocode.co.uk> Helps: #3037
This commit is contained in:
111
docs/reference/gio/file-attributes.md
Normal file
111
docs/reference/gio/file-attributes.md
Normal file
@@ -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].
|
||||
|
||||
<!-- TODO: Implementation note about using extended attributes on supported
|
||||
file systems -->
|
||||
|
||||
## 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.
|
||||
|
@@ -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",
|
||||
|
@@ -229,6 +229,7 @@ endif
|
||||
|
||||
# gi-docgen version
|
||||
expand_content_files = [
|
||||
'file-attributes.md',
|
||||
'migrating-gconf.md',
|
||||
'migrating-gdbus.md',
|
||||
'migrating-gnome-vfs.md',
|
||||
|
Reference in New Issue
Block a user