luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-01-14 00:06:24 +01:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'docgen-fixes' into 'main'

Browse Source 
Adapt documentation to gi-docgen

See merge request GNOME/glib!2206
This commit is contained in:
Philip Withnall 2021-08-03 13:53:38 +00:00
commit 709df8eeb4
45 changed files with 893 additions and 539 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
docs/reference/gio/gio-docs.xml
View File

@ -48,8 +48,8 @@
<title>Data conversion</title> <title>Data conversion</title>
<xi:include href="xml/gconverter.xml"/> <xi:include href="xml/gconverter.xml"/>
<xi:include href="xml/gcharsetconverter.xml"/> <xi:include href="xml/gcharsetconverter.xml"/>
<xi:include href="xml/gzcompressor.xml"/> <xi:include href="xml/gzlibcompressor.xml"/>
<xi:include href="xml/gzdecompressor.xml"/> <xi:include href="xml/gzlibdecompressor.xml"/>
</chapter> </chapter>
<chapter id="streaming"> <chapter id="streaming">
<title>Streaming I/O</title> <title>Streaming I/O</title>

4
docs/reference/gio/gio-sections-common.txt
View File

@ -2505,7 +2505,7 @@ g_converter_output_stream_get_type
</SECTION> </SECTION>
<SECTION> <SECTION>
<FILE>gzcompressor</FILE> <FILE>gzlibcompressor</FILE>
<TITLE>GZlibCompressor</TITLE> <TITLE>GZlibCompressor</TITLE>
GZlibCompressor GZlibCompressor
GZlibCompressorFormat GZlibCompressorFormat
@ -2527,7 +2527,7 @@ g_zlib_compressor_format_get_type
</SECTION> </SECTION>
<SECTION> <SECTION>
<FILE>gzdecompressor</FILE> <FILE>gzlibdecompressor</FILE>
<TITLE>GZlibDecompressor</TITLE> <TITLE>GZlibDecompressor</TITLE>
GZlibDecompressor GZlibDecompressor
g_zlib_decompressor_new g_zlib_decompressor_new

375
gio/gfileinfo.h
View File

@ -49,7 +49,9 @@ typedef struct _GFileInfoClass GFileInfoClass;
* G_FILE_ATTRIBUTE_STANDARD_TYPE: * G_FILE_ATTRIBUTE_STANDARD_TYPE:
* *
* A key in the "standard" namespace for storing file types. * A key in the "standard" namespace for storing file types.
*
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32.
*
* The value for this key should contain a #GFileType. * The value for this key should contain a #GFileType.
**/ **/
#define G_FILE_ATTRIBUTE_STANDARD_TYPE "standard::type" /* uint32 (GFileType) */ #define G_FILE_ATTRIBUTE_STANDARD_TYPE "standard::type" /* uint32 (GFileType) */
@ -58,6 +60,7 @@ typedef struct _GFileInfoClass GFileInfoClass;
* G_FILE_ATTRIBUTE_STANDARD_IS_HIDDEN: * G_FILE_ATTRIBUTE_STANDARD_IS_HIDDEN:
* *
* A key in the "standard" namespace for checking if a file is hidden. * A key in the "standard" namespace for checking if a file is hidden.
*
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
**/ **/
#define G_FILE_ATTRIBUTE_STANDARD_IS_HIDDEN "standard::is-hidden" /* boolean */ #define G_FILE_ATTRIBUTE_STANDARD_IS_HIDDEN "standard::is-hidden" /* boolean */
@ -66,6 +69,7 @@ typedef struct _GFileInfoClass GFileInfoClass;
* G_FILE_ATTRIBUTE_STANDARD_IS_BACKUP: * G_FILE_ATTRIBUTE_STANDARD_IS_BACKUP:
* *
* A key in the "standard" namespace for checking if a file is a backup file. * A key in the "standard" namespace for checking if a file is a backup file.
*
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
**/ **/
#define G_FILE_ATTRIBUTE_STANDARD_IS_BACKUP "standard::is-backup" /* boolean */ #define G_FILE_ATTRIBUTE_STANDARD_IS_BACKUP "standard::is-backup" /* boolean */
@ -76,7 +80,9 @@ typedef struct _GFileInfoClass GFileInfoClass;
* A key in the "standard" namespace for checking if the file is a symlink. * A key in the "standard" namespace for checking if the file is a symlink.
* Typically the actual type is something else, if we followed the symlink * Typically the actual type is something else, if we followed the symlink
* to get the type. * to get the type.
*
* On Windows NTFS mountpoints are considered to be symlinks as well. * On Windows NTFS mountpoints are considered to be symlinks as well.
*
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
**/ **/
#define G_FILE_ATTRIBUTE_STANDARD_IS_SYMLINK "standard::is-symlink" /* boolean */ #define G_FILE_ATTRIBUTE_STANDARD_IS_SYMLINK "standard::is-symlink" /* boolean */
@ -85,6 +91,7 @@ typedef struct _GFileInfoClass GFileInfoClass;
* G_FILE_ATTRIBUTE_STANDARD_IS_VIRTUAL: * G_FILE_ATTRIBUTE_STANDARD_IS_VIRTUAL:
* *
* A key in the "standard" namespace for checking if a file is virtual. * A key in the "standard" namespace for checking if a file is virtual.
*
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
**/ **/
#define G_FILE_ATTRIBUTE_STANDARD_IS_VIRTUAL "standard::is-virtual" /* boolean */ #define G_FILE_ATTRIBUTE_STANDARD_IS_VIRTUAL "standard::is-virtual" /* boolean */
@ -95,7 +102,7 @@ typedef struct _GFileInfoClass GFileInfoClass;
* A key in the "standard" namespace for checking if a file is * A key in the "standard" namespace for checking if a file is
* volatile. This is meant for opaque, non-POSIX-like backends to * volatile. This is meant for opaque, non-POSIX-like backends to
* indicate that the URI is not persistent. Applications should look * indicate that the URI is not persistent. Applications should look
* at #G_FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET for the persistent URI. * at %G_FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET for the persistent URI.
* *
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
* *
@ -107,11 +114,14 @@ typedef struct _GFileInfoClass GFileInfoClass;
* G_FILE_ATTRIBUTE_STANDARD_NAME: * G_FILE_ATTRIBUTE_STANDARD_NAME:
* *
* A key in the "standard" namespace for getting the name of the file. * A key in the "standard" namespace for getting the name of the file.
*
* The name is the on-disk filename which may not be in any known encoding, * The name is the on-disk filename which may not be in any known encoding,
* and can thus not be generally displayed as is. It is guaranteed to be set on * and can thus not be generally displayed as is. It is guaranteed to be set on
* every file. * every file.
* Use #G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME if you need to display the *
* Use %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME if you need to display the
* name in a user interface. * name in a user interface.
*
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING. * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING.
**/ **/
#define G_FILE_ATTRIBUTE_STANDARD_NAME "standard::name" /* byte string */ #define G_FILE_ATTRIBUTE_STANDARD_NAME "standard::name" /* byte string */
@ -120,8 +130,10 @@ typedef struct _GFileInfoClass GFileInfoClass;
* G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME: * G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME:
* *
* A key in the "standard" namespace for getting the display name of the file. * A key in the "standard" namespace for getting the display name of the file.
*
* A display name is guaranteed to be in UTF-8 and can thus be displayed in * A display name is guaranteed to be in UTF-8 and can thus be displayed in
* the UI. It is guaranteed to be set on every file. * the UI. It is guaranteed to be set on every file.
*
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
**/ **/
#define G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME "standard::display-name" /* string */ #define G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME "standard::display-name" /* string */
@ -130,6 +142,7 @@ typedef struct _GFileInfoClass GFileInfoClass;
* G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME: * G_FILE_ATTRIBUTE_STANDARD_EDIT_NAME:
* *
* A key in the "standard" namespace for edit name of the file. * A key in the "standard" namespace for edit name of the file.
*
* An edit name is similar to the display name, but it is meant to be * An edit name is similar to the display name, but it is meant to be
* used when you want to rename the file in the UI. The display name * used when you want to rename the file in the UI. The display name
* might contain information you don't want in the new filename (such as * might contain information you don't want in the new filename (such as
@ -143,6 +156,7 @@ typedef struct _GFileInfoClass GFileInfoClass;
* G_FILE_ATTRIBUTE_STANDARD_COPY_NAME: * G_FILE_ATTRIBUTE_STANDARD_COPY_NAME:
* *
* A key in the "standard" namespace for getting the copy name of the file. * A key in the "standard" namespace for getting the copy name of the file.
*
* The copy name is an optional version of the name. If available it's always * The copy name is an optional version of the name. If available it's always
* in UTF8, and corresponds directly to the original filename (only transcoded to * in UTF8, and corresponds directly to the original filename (only transcoded to
* UTF8). This is useful if you want to copy the file to another filesystem that * UTF8). This is useful if you want to copy the file to another filesystem that
@ -157,6 +171,7 @@ typedef struct _GFileInfoClass GFileInfoClass;
* G_FILE_ATTRIBUTE_STANDARD_DESCRIPTION: * G_FILE_ATTRIBUTE_STANDARD_DESCRIPTION:
* *
* A key in the "standard" namespace for getting the description of the file. * A key in the "standard" namespace for getting the description of the file.
*
* The description is a utf8 string that describes the file, generally containing * The description is a utf8 string that describes the file, generally containing
* the filename, but can also contain further information. Example descriptions * the filename, but can also contain further information. Example descriptions
* could be "filename (on hostname)" for a remote file or "filename (in trash)" * could be "filename (on hostname)" for a remote file or "filename (in trash)"
@ -171,7 +186,9 @@ typedef struct _GFileInfoClass GFileInfoClass;
* G_FILE_ATTRIBUTE_STANDARD_ICON: * G_FILE_ATTRIBUTE_STANDARD_ICON:
* *
* A key in the "standard" namespace for getting the icon for the file. * A key in the "standard" namespace for getting the icon for the file.
*
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_OBJECT. * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_OBJECT.
*
* The value for this key should contain a #GIcon. * The value for this key should contain a #GIcon.
**/ **/
#define G_FILE_ATTRIBUTE_STANDARD_ICON "standard::icon" /* object (GIcon) */ #define G_FILE_ATTRIBUTE_STANDARD_ICON "standard::icon" /* object (GIcon) */
@ -180,7 +197,9 @@ typedef struct _GFileInfoClass GFileInfoClass;
* G_FILE_ATTRIBUTE_STANDARD_SYMBOLIC_ICON: * G_FILE_ATTRIBUTE_STANDARD_SYMBOLIC_ICON:
* *
* A key in the "standard" namespace for getting the symbolic icon for the file. * A key in the "standard" namespace for getting the symbolic icon for the file.
*
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_OBJECT. * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_OBJECT.
*
* The value for this key should contain a #GIcon. * The value for this key should contain a #GIcon.
* *
* Since: 2.34 * Since: 2.34
@ -191,7 +210,9 @@ typedef struct _GFileInfoClass GFileInfoClass;
* G_FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE: * G_FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE:
* *
* A key in the "standard" namespace for getting the content type of the file. * A key in the "standard" namespace for getting the content type of the file.
*
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
*
* The value for this key should contain a valid content type. * The value for this key should contain a valid content type.
**/ **/
#define G_FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE "standard::content-type" /* string */ #define G_FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE "standard::content-type" /* string */
@ -200,9 +221,11 @@ typedef struct _GFileInfoClass GFileInfoClass;
* G_FILE_ATTRIBUTE_STANDARD_FAST_CONTENT_TYPE: * G_FILE_ATTRIBUTE_STANDARD_FAST_CONTENT_TYPE:
* *
* A key in the "standard" namespace for getting the fast content type. * A key in the "standard" namespace for getting the fast content type.
*
* The fast content type isn't as reliable as the regular one, as it * The fast content type isn't as reliable as the regular one, as it
* only uses the filename to guess it, but it is faster to calculate than the * only uses the filename to guess it, but it is faster to calculate than the
* regular content type. * regular content type.
*
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
* *
**/ **/
@ -212,6 +235,7 @@ typedef struct _GFileInfoClass GFileInfoClass;
* G_FILE_ATTRIBUTE_STANDARD_SIZE: * G_FILE_ATTRIBUTE_STANDARD_SIZE:
* *
* A key in the "standard" namespace for getting the file's size (in bytes). * A key in the "standard" namespace for getting the file's size (in bytes).
*
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64. * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64.
**/ **/
#define G_FILE_ATTRIBUTE_STANDARD_SIZE "standard::size" /* uint64 */ #define G_FILE_ATTRIBUTE_STANDARD_SIZE "standard::size" /* uint64 */
@ -220,9 +244,11 @@ typedef struct _GFileInfoClass GFileInfoClass;
* G_FILE_ATTRIBUTE_STANDARD_ALLOCATED_SIZE: * G_FILE_ATTRIBUTE_STANDARD_ALLOCATED_SIZE:
* *
* A key in the "standard" namespace for getting the amount of disk space * A key in the "standard" namespace for getting the amount of disk space
* that is consumed by the file (in bytes). This will generally be larger * that is consumed by the file (in bytes).
* than the file size (due to block size overhead) but can occasionally be *
* smaller (for example, for sparse files). * This will generally be larger than the file size (due to block size
* overhead) but can occasionally be smaller (for example, for sparse files).
*
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64. * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64.
* *
* Since: 2.20 * Since: 2.20
@ -233,8 +259,9 @@ typedef struct _GFileInfoClass GFileInfoClass;
* G_FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET: * G_FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET:
* *
* A key in the "standard" namespace for getting the symlink target, if the file * A key in the "standard" namespace for getting the symlink target, if the file
* is a symlink. Corresponding #GFileAttributeType is * is a symlink.
* %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING. *
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING.
**/ **/
#define G_FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET "standard::symlink-target" /* byte string */ #define G_FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET "standard::symlink-target" /* byte string */
@ -243,6 +270,7 @@ typedef struct _GFileInfoClass GFileInfoClass;
* *
* A key in the "standard" namespace for getting the target URI for the file, in * A key in the "standard" namespace for getting the target URI for the file, in
* the case of %G_FILE_TYPE_SHORTCUT or %G_FILE_TYPE_MOUNTABLE files. * the case of %G_FILE_TYPE_SHORTCUT or %G_FILE_TYPE_MOUNTABLE files.
*
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
**/ **/
#define G_FILE_ATTRIBUTE_STANDARD_TARGET_URI "standard::target-uri" /* string */ #define G_FILE_ATTRIBUTE_STANDARD_TARGET_URI "standard::target-uri" /* string */
@ -251,7 +279,9 @@ typedef struct _GFileInfoClass GFileInfoClass;
* G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER: * G_FILE_ATTRIBUTE_STANDARD_SORT_ORDER:
* *
* A key in the "standard" namespace for setting the sort order of a file. * A key in the "standard" namespace for setting the sort order of a file.
*
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_INT32. * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_INT32.
*
* An example use would be in file managers, which would use this key * An example use would be in file managers, which would use this key
* to set the order files are displayed. Files with smaller sort order * to set the order files are displayed. Files with smaller sort order
* should be sorted first, and files without sort order as if sort order * should be sorted first, and files without sort order as if sort order
@ -265,8 +295,9 @@ typedef struct _GFileInfoClass GFileInfoClass;
* G_FILE_ATTRIBUTE_ETAG_VALUE: * G_FILE_ATTRIBUTE_ETAG_VALUE:
* *
* A key in the "etag" namespace for getting the value of the file's * A key in the "etag" namespace for getting the value of the file's
* entity tag. Corresponding #GFileAttributeType is * entity tag.
* %G_FILE_ATTRIBUTE_TYPE_STRING. *
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
**/ **/
#define G_FILE_ATTRIBUTE_ETAG_VALUE "etag::value" /* string */ #define G_FILE_ATTRIBUTE_ETAG_VALUE "etag::value" /* string */
@ -278,7 +309,9 @@ typedef struct _GFileInfoClass GFileInfoClass;
* G_FILE_ATTRIBUTE_ID_FILE: * G_FILE_ATTRIBUTE_ID_FILE:
* *
* A key in the "id" namespace for getting a file identifier. * A key in the "id" namespace for getting a file identifier.
*
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
*
* An example use would be during listing files, to avoid recursive * An example use would be during listing files, to avoid recursive
* directory scanning. * directory scanning.
**/ **/
@ -288,7 +321,9 @@ typedef struct _GFileInfoClass GFileInfoClass;
* G_FILE_ATTRIBUTE_ID_FILESYSTEM: * G_FILE_ATTRIBUTE_ID_FILESYSTEM:
* *
* A key in the "id" namespace for getting the file system identifier. * A key in the "id" namespace for getting the file system identifier.
*
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
*
* An example use would be during drag and drop to see if the source * An example use would be during drag and drop to see if the source
* and target are on the same filesystem (default to move) or not (default * and target are on the same filesystem (default to move) or not (default
* to copy). * to copy).
@ -301,7 +336,9 @@ typedef struct _GFileInfoClass GFileInfoClass;
* G_FILE_ATTRIBUTE_ACCESS_CAN_READ: * G_FILE_ATTRIBUTE_ACCESS_CAN_READ:
* *
* A key in the "access" namespace for getting read privileges. * A key in the "access" namespace for getting read privileges.
*
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
*
* This attribute will be %TRUE if the user is able to read the file. * This attribute will be %TRUE if the user is able to read the file.
**/ **/
#define G_FILE_ATTRIBUTE_ACCESS_CAN_READ "access::can-read" /* boolean */ #define G_FILE_ATTRIBUTE_ACCESS_CAN_READ "access::can-read" /* boolean */
@ -310,7 +347,9 @@ typedef struct _GFileInfoClass GFileInfoClass;
* G_FILE_ATTRIBUTE_ACCESS_CAN_WRITE: * G_FILE_ATTRIBUTE_ACCESS_CAN_WRITE:
* *
* A key in the "access" namespace for getting write privileges. * A key in the "access" namespace for getting write privileges.
*
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
*
* This attribute will be %TRUE if the user is able to write to the file. * This attribute will be %TRUE if the user is able to write to the file.
**/ **/
#define G_FILE_ATTRIBUTE_ACCESS_CAN_WRITE "access::can-write" /* boolean */ #define G_FILE_ATTRIBUTE_ACCESS_CAN_WRITE "access::can-write" /* boolean */
@ -319,7 +358,9 @@ typedef struct _GFileInfoClass GFileInfoClass;
* G_FILE_ATTRIBUTE_ACCESS_CAN_EXECUTE: * G_FILE_ATTRIBUTE_ACCESS_CAN_EXECUTE:
* *
* A key in the "access" namespace for getting execution privileges. * A key in the "access" namespace for getting execution privileges.
*
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
*
* This attribute will be %TRUE if the user is able to execute the file. * This attribute will be %TRUE if the user is able to execute the file.
**/ **/
#define G_FILE_ATTRIBUTE_ACCESS_CAN_EXECUTE "access::can-execute" /* boolean */ #define G_FILE_ATTRIBUTE_ACCESS_CAN_EXECUTE "access::can-execute" /* boolean */
@ -328,7 +369,9 @@ typedef struct _GFileInfoClass GFileInfoClass;
* G_FILE_ATTRIBUTE_ACCESS_CAN_DELETE: * G_FILE_ATTRIBUTE_ACCESS_CAN_DELETE:
* *
* A key in the "access" namespace for checking deletion privileges. * A key in the "access" namespace for checking deletion privileges.
*
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
*
* This attribute will be %TRUE if the user is able to delete the file. * This attribute will be %TRUE if the user is able to delete the file.
**/ **/
#define G_FILE_ATTRIBUTE_ACCESS_CAN_DELETE "access::can-delete" /* boolean */ #define G_FILE_ATTRIBUTE_ACCESS_CAN_DELETE "access::can-delete" /* boolean */
@ -337,7 +380,9 @@ typedef struct _GFileInfoClass GFileInfoClass;
* G_FILE_ATTRIBUTE_ACCESS_CAN_TRASH: * G_FILE_ATTRIBUTE_ACCESS_CAN_TRASH:
* *
* A key in the "access" namespace for checking trashing privileges. * A key in the "access" namespace for checking trashing privileges.
*
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
*
* This attribute will be %TRUE if the user is able to move the file to * This attribute will be %TRUE if the user is able to move the file to
* the trash. * the trash.
**/ **/
@ -347,7 +392,9 @@ typedef struct _GFileInfoClass GFileInfoClass;
* G_FILE_ATTRIBUTE_ACCESS_CAN_RENAME: * G_FILE_ATTRIBUTE_ACCESS_CAN_RENAME:
* *
* A key in the "access" namespace for checking renaming privileges. * A key in the "access" namespace for checking renaming privileges.
*
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
*
* This attribute will be %TRUE if the user is able to rename the file. * This attribute will be %TRUE if the user is able to rename the file.
**/ **/
#define G_FILE_ATTRIBUTE_ACCESS_CAN_RENAME "access::can-rename" /* boolean */ #define G_FILE_ATTRIBUTE_ACCESS_CAN_RENAME "access::can-rename" /* boolean */
@ -359,7 +406,9 @@ typedef struct _GFileInfoClass GFileInfoClass;
/** /**
* G_FILE_ATTRIBUTE_MOUNTABLE_CAN_MOUNT: * G_FILE_ATTRIBUTE_MOUNTABLE_CAN_MOUNT:
* *
* A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) is mountable. * A key in the "mountable" namespace for checking if a file (of
* type G_FILE_TYPE_MOUNTABLE) is mountable.
*
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
**/ **/
#define G_FILE_ATTRIBUTE_MOUNTABLE_CAN_MOUNT "mountable::can-mount" /* boolean */ #define G_FILE_ATTRIBUTE_MOUNTABLE_CAN_MOUNT "mountable::can-mount" /* boolean */
@ -367,7 +416,9 @@ typedef struct _GFileInfoClass GFileInfoClass;
/** /**
* G_FILE_ATTRIBUTE_MOUNTABLE_CAN_UNMOUNT: * G_FILE_ATTRIBUTE_MOUNTABLE_CAN_UNMOUNT:
* *
* A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) is unmountable. * A key in the "mountable" namespace for checking if a file (of
* type G_FILE_TYPE_MOUNTABLE) is unmountable.
*
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
**/ **/
#define G_FILE_ATTRIBUTE_MOUNTABLE_CAN_UNMOUNT "mountable::can-unmount" /* boolean */ #define G_FILE_ATTRIBUTE_MOUNTABLE_CAN_UNMOUNT "mountable::can-unmount" /* boolean */
@ -375,7 +426,9 @@ typedef struct _GFileInfoClass GFileInfoClass;
/** /**
* G_FILE_ATTRIBUTE_MOUNTABLE_CAN_EJECT: * G_FILE_ATTRIBUTE_MOUNTABLE_CAN_EJECT:
* *
* A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) can be ejected. * A key in the "mountable" namespace for checking if a file (of
* type G_FILE_TYPE_MOUNTABLE) can be ejected.
*
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
**/ **/
#define G_FILE_ATTRIBUTE_MOUNTABLE_CAN_EJECT "mountable::can-eject" /* boolean */ #define G_FILE_ATTRIBUTE_MOUNTABLE_CAN_EJECT "mountable::can-eject" /* boolean */
@ -384,6 +437,7 @@ typedef struct _GFileInfoClass GFileInfoClass;
* G_FILE_ATTRIBUTE_MOUNTABLE_UNIX_DEVICE: * G_FILE_ATTRIBUTE_MOUNTABLE_UNIX_DEVICE:
* *
* A key in the "mountable" namespace for getting the unix device. * A key in the "mountable" namespace for getting the unix device.
*
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32.
**/ **/
#define G_FILE_ATTRIBUTE_MOUNTABLE_UNIX_DEVICE "mountable::unix-device" /* uint32 */ #define G_FILE_ATTRIBUTE_MOUNTABLE_UNIX_DEVICE "mountable::unix-device" /* uint32 */
@ -392,6 +446,7 @@ typedef struct _GFileInfoClass GFileInfoClass;
* G_FILE_ATTRIBUTE_MOUNTABLE_UNIX_DEVICE_FILE: * G_FILE_ATTRIBUTE_MOUNTABLE_UNIX_DEVICE_FILE:
* *
* A key in the "mountable" namespace for getting the unix device file. * A key in the "mountable" namespace for getting the unix device file.
*
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
* *
* Since: 2.22 * Since: 2.22
@ -402,14 +457,18 @@ typedef struct _GFileInfoClass GFileInfoClass;
* G_FILE_ATTRIBUTE_MOUNTABLE_HAL_UDI: * G_FILE_ATTRIBUTE_MOUNTABLE_HAL_UDI:
* *
* A key in the "mountable" namespace for getting the HAL UDI for the mountable * A key in the "mountable" namespace for getting the HAL UDI for the mountable
* file. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. * file.
*
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
**/ **/
#define G_FILE_ATTRIBUTE_MOUNTABLE_HAL_UDI "mountable::hal-udi" /* string */ #define G_FILE_ATTRIBUTE_MOUNTABLE_HAL_UDI "mountable::hal-udi" /* string */
/** /**
* G_FILE_ATTRIBUTE_MOUNTABLE_CAN_START: * G_FILE_ATTRIBUTE_MOUNTABLE_CAN_START:
* *
* A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) can be started. * A key in the "mountable" namespace for checking if a file (of
* type G_FILE_TYPE_MOUNTABLE) can be started.
*
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
* *
* Since: 2.22 * Since: 2.22
@ -419,8 +478,9 @@ typedef struct _GFileInfoClass GFileInfoClass;
/** /**
* G_FILE_ATTRIBUTE_MOUNTABLE_CAN_START_DEGRADED: * G_FILE_ATTRIBUTE_MOUNTABLE_CAN_START_DEGRADED:
* *
* A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) can be started * A key in the "mountable" namespace for checking if a file (of
* degraded. * type G_FILE_TYPE_MOUNTABLE) can be started degraded.
*
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
* *
* Since: 2.22 * Since: 2.22
@ -430,7 +490,9 @@ typedef struct _GFileInfoClass GFileInfoClass;
/** /**
* G_FILE_ATTRIBUTE_MOUNTABLE_CAN_STOP: * G_FILE_ATTRIBUTE_MOUNTABLE_CAN_STOP:
* *
* A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) can be stopped. * A key in the "mountable" namespace for checking if a file (of
* type G_FILE_TYPE_MOUNTABLE) can be stopped.
*
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
* *
* Since: 2.22 * Since: 2.22
@ -441,6 +503,7 @@ typedef struct _GFileInfoClass GFileInfoClass;
* G_FILE_ATTRIBUTE_MOUNTABLE_START_STOP_TYPE: * G_FILE_ATTRIBUTE_MOUNTABLE_START_STOP_TYPE:
* *
* A key in the "mountable" namespace for getting the #GDriveStartStopType. * A key in the "mountable" namespace for getting the #GDriveStartStopType.
*
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32.
* *
* Since: 2.22 * Since: 2.22
@ -450,7 +513,9 @@ typedef struct _GFileInfoClass GFileInfoClass;
/** /**
* G_FILE_ATTRIBUTE_MOUNTABLE_CAN_POLL: * G_FILE_ATTRIBUTE_MOUNTABLE_CAN_POLL:
* *
* A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) can be polled. * A key in the "mountable" namespace for checking if a file (of
* type G_FILE_TYPE_MOUNTABLE) can be polled.
*
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
* *
* Since: 2.22 * Since: 2.22
@ -460,8 +525,9 @@ typedef struct _GFileInfoClass GFileInfoClass;
/** /**
* G_FILE_ATTRIBUTE_MOUNTABLE_IS_MEDIA_CHECK_AUTOMATIC: * G_FILE_ATTRIBUTE_MOUNTABLE_IS_MEDIA_CHECK_AUTOMATIC:
* *
* A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) * A key in the "mountable" namespace for checking if a file (of
* is automatically polled for media. * type G_FILE_TYPE_MOUNTABLE) is automatically polled for media.
*
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
* *
* Since: 2.22 * Since: 2.22
@ -474,9 +540,11 @@ typedef struct _GFileInfoClass GFileInfoClass;
* G_FILE_ATTRIBUTE_TIME_MODIFIED: * G_FILE_ATTRIBUTE_TIME_MODIFIED:
* *
* A key in the "time" namespace for getting the time the file was last * A key in the "time" namespace for getting the time the file was last
* modified. Corresponding #GFileAttributeType is * modified.
* %G_FILE_ATTRIBUTE_TYPE_UINT64, and contains the time since the *
* file was modified, in seconds since the UNIX epoch. * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64, and
* contains the time since the file was modified, in seconds since the UNIX
* epoch.
**/ **/
#define G_FILE_ATTRIBUTE_TIME_MODIFIED "time::modified" /* uint64 */ #define G_FILE_ATTRIBUTE_TIME_MODIFIED "time::modified" /* uint64 */
@ -484,9 +552,11 @@ typedef struct _GFileInfoClass GFileInfoClass;
* G_FILE_ATTRIBUTE_TIME_MODIFIED_USEC: * G_FILE_ATTRIBUTE_TIME_MODIFIED_USEC:
* *
* A key in the "time" namespace for getting the microseconds of the time * A key in the "time" namespace for getting the microseconds of the time
* the file was last modified. This should be used in conjunction with * the file was last modified.
* #G_FILE_ATTRIBUTE_TIME_MODIFIED. Corresponding #GFileAttributeType is *
* %G_FILE_ATTRIBUTE_TYPE_UINT32. * This should be used in conjunction with %G_FILE_ATTRIBUTE_TIME_MODIFIED.
*
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32.
**/ **/
#define G_FILE_ATTRIBUTE_TIME_MODIFIED_USEC "time::modified-usec" /* uint32 */ #define G_FILE_ATTRIBUTE_TIME_MODIFIED_USEC "time::modified-usec" /* uint32 */
@ -494,9 +564,11 @@ typedef struct _GFileInfoClass GFileInfoClass;
* G_FILE_ATTRIBUTE_TIME_ACCESS: * G_FILE_ATTRIBUTE_TIME_ACCESS:
* *
* A key in the "time" namespace for getting the time the file was last * A key in the "time" namespace for getting the time the file was last
* accessed. Corresponding #GFileAttributeType is * accessed.
* %G_FILE_ATTRIBUTE_TYPE_UINT64, and contains the time since the *
* file was last accessed, in seconds since the UNIX epoch. * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64, and
* contains the time since the file was last accessed, in seconds since the
* UNIX epoch.
**/ **/
#define G_FILE_ATTRIBUTE_TIME_ACCESS "time::access" /* uint64 */ #define G_FILE_ATTRIBUTE_TIME_ACCESS "time::access" /* uint64 */
@ -504,9 +576,11 @@ typedef struct _GFileInfoClass GFileInfoClass;
* G_FILE_ATTRIBUTE_TIME_ACCESS_USEC: * G_FILE_ATTRIBUTE_TIME_ACCESS_USEC:
* *
* A key in the "time" namespace for getting the microseconds of the time * A key in the "time" namespace for getting the microseconds of the time
* the file was last accessed. This should be used in conjunction with * the file was last accessed.
* #G_FILE_ATTRIBUTE_TIME_ACCESS. Corresponding #GFileAttributeType is *
* %G_FILE_ATTRIBUTE_TYPE_UINT32. * This should be used in conjunction with %G_FILE_ATTRIBUTE_TIME_ACCESS.
*
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32.
**/ **/
#define G_FILE_ATTRIBUTE_TIME_ACCESS_USEC "time::access-usec" /* uint32 */ #define G_FILE_ATTRIBUTE_TIME_ACCESS_USEC "time::access-usec" /* uint32 */
@ -514,9 +588,11 @@ typedef struct _GFileInfoClass GFileInfoClass;
* G_FILE_ATTRIBUTE_TIME_CHANGED: * G_FILE_ATTRIBUTE_TIME_CHANGED:
* *
* A key in the "time" namespace for getting the time the file was last * A key in the "time" namespace for getting the time the file was last
* changed. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64, * changed.
* and contains the time since the file was last changed, in seconds since the *
* UNIX epoch. * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64,
* and contains the time since the file was last changed, in seconds since
* the UNIX epoch.
* *
* This corresponds to the traditional UNIX ctime. * This corresponds to the traditional UNIX ctime.
**/ **/
@ -526,9 +602,11 @@ typedef struct _GFileInfoClass GFileInfoClass;
* G_FILE_ATTRIBUTE_TIME_CHANGED_USEC: * G_FILE_ATTRIBUTE_TIME_CHANGED_USEC:
* *
* A key in the "time" namespace for getting the microseconds of the time * A key in the "time" namespace for getting the microseconds of the time
* the file was last changed. This should be used in conjunction with * the file was last changed.
* #G_FILE_ATTRIBUTE_TIME_CHANGED. Corresponding #GFileAttributeType is *
* %G_FILE_ATTRIBUTE_TYPE_UINT32. * This should be used in conjunction with %G_FILE_ATTRIBUTE_TIME_CHANGED.
*
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32.
**/ **/
#define G_FILE_ATTRIBUTE_TIME_CHANGED_USEC "time::changed-usec" /* uint32 */ #define G_FILE_ATTRIBUTE_TIME_CHANGED_USEC "time::changed-usec" /* uint32 */
@ -536,12 +614,13 @@ typedef struct _GFileInfoClass GFileInfoClass;
* G_FILE_ATTRIBUTE_TIME_CREATED: * G_FILE_ATTRIBUTE_TIME_CREATED:
* *
* A key in the "time" namespace for getting the time the file was created. * A key in the "time" namespace for getting the time the file was created.
*
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64, * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64,
* and contains the time since the file was created, in seconds since the UNIX * and contains the time since the file was created, in seconds since the UNIX
* epoch. * epoch.
* *
* This may correspond to Linux stx_btime, FreeBSD st_birthtim, NetBSD * This may correspond to Linux `stx_btime`, FreeBSD `st_birthtim`, NetBSD
* st_birthtime or NTFS ctime. * `st_birthtime` or NTFS `ctime`.
**/ **/
#define G_FILE_ATTRIBUTE_TIME_CREATED "time::created" /* uint64 */ #define G_FILE_ATTRIBUTE_TIME_CREATED "time::created" /* uint64 */
@ -549,9 +628,11 @@ typedef struct _GFileInfoClass GFileInfoClass;
* G_FILE_ATTRIBUTE_TIME_CREATED_USEC: * G_FILE_ATTRIBUTE_TIME_CREATED_USEC:
* *
* A key in the "time" namespace for getting the microseconds of the time * A key in the "time" namespace for getting the microseconds of the time
* the file was created. This should be used in conjunction with * the file was created.
* #G_FILE_ATTRIBUTE_TIME_CREATED. Corresponding #GFileAttributeType is *
* %G_FILE_ATTRIBUTE_TYPE_UINT32. * This should be used in conjunction with %G_FILE_ATTRIBUTE_TIME_CREATED.
*
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32.
**/ **/
#define G_FILE_ATTRIBUTE_TIME_CREATED_USEC "time::created-usec" /* uint32 */ #define G_FILE_ATTRIBUTE_TIME_CREATED_USEC "time::created-usec" /* uint32 */
@ -561,9 +642,11 @@ typedef struct _GFileInfoClass GFileInfoClass;
* G_FILE_ATTRIBUTE_UNIX_DEVICE: * G_FILE_ATTRIBUTE_UNIX_DEVICE:
* *
* A key in the "unix" namespace for getting the device id of the device the * A key in the "unix" namespace for getting the device id of the device the
* file is located on (see stat() documentation). This attribute is only * file is located on (see stat() documentation).
* available for UNIX file systems. Corresponding #GFileAttributeType is *
* %G_FILE_ATTRIBUTE_TYPE_UINT32. * This attribute is only available for UNIX file systems.
*
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32.
**/ **/
#define G_FILE_ATTRIBUTE_UNIX_DEVICE "unix::device" /* uint32 */ #define G_FILE_ATTRIBUTE_UNIX_DEVICE "unix::device" /* uint32 */
@ -571,8 +654,10 @@ typedef struct _GFileInfoClass GFileInfoClass;
* G_FILE_ATTRIBUTE_UNIX_INODE: * G_FILE_ATTRIBUTE_UNIX_INODE:
* *
* A key in the "unix" namespace for getting the inode of the file. * A key in the "unix" namespace for getting the inode of the file.
* This attribute is only available for UNIX file systems. Corresponding *
* #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64. * This attribute is only available for UNIX file systems.
*
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64.
**/ **/
#define G_FILE_ATTRIBUTE_UNIX_INODE "unix::inode" /* uint64 */ #define G_FILE_ATTRIBUTE_UNIX_INODE "unix::inode" /* uint64 */
@ -580,10 +665,14 @@ typedef struct _GFileInfoClass GFileInfoClass;
* G_FILE_ATTRIBUTE_UNIX_MODE: * G_FILE_ATTRIBUTE_UNIX_MODE:
* *
* A key in the "unix" namespace for getting the mode of the file * A key in the "unix" namespace for getting the mode of the file
* (e.g. whether the file is a regular file, symlink, etc). See the * (e.g. whether the file is a regular file, symlink, etc).
* documentation for `lstat()`: this attribute is equivalent to the `st_mode` *
* member of `struct stat`, and includes both the file type and permissions. * See the documentation for `lstat()`: this attribute is equivalent to
* the `st_mode` member of `struct stat`, and includes both the file type
* and permissions.
*
* This attribute is only available for UNIX file systems. * This attribute is only available for UNIX file systems.
*
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32.
**/ **/
#define G_FILE_ATTRIBUTE_UNIX_MODE "unix::mode" /* uint32 */ #define G_FILE_ATTRIBUTE_UNIX_MODE "unix::mode" /* uint32 */
@ -592,9 +681,13 @@ typedef struct _GFileInfoClass GFileInfoClass;
* G_FILE_ATTRIBUTE_UNIX_NLINK: * G_FILE_ATTRIBUTE_UNIX_NLINK:
* *
* A key in the "unix" namespace for getting the number of hard links * A key in the "unix" namespace for getting the number of hard links
* for a file. See lstat() documentation. This attribute is only available * for a file.
* for UNIX file systems. Corresponding #GFileAttributeType is *
* %G_FILE_ATTRIBUTE_TYPE_UINT32. * See the documentation for `lstat()`.
*
* This attribute is only available for UNIX file systems.
*
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32.
**/ **/
#define G_FILE_ATTRIBUTE_UNIX_NLINK "unix::nlink" /* uint32 */ #define G_FILE_ATTRIBUTE_UNIX_NLINK "unix::nlink" /* uint32 */
@ -602,7 +695,9 @@ typedef struct _GFileInfoClass GFileInfoClass;
* G_FILE_ATTRIBUTE_UNIX_UID: * G_FILE_ATTRIBUTE_UNIX_UID:
* *
* A key in the "unix" namespace for getting the user ID for the file. * A key in the "unix" namespace for getting the user ID for the file.
*
* This attribute is only available for UNIX file systems. * This attribute is only available for UNIX file systems.
*
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32.
**/ **/
#define G_FILE_ATTRIBUTE_UNIX_UID "unix::uid" /* uint32 */ #define G_FILE_ATTRIBUTE_UNIX_UID "unix::uid" /* uint32 */
@ -611,7 +706,9 @@ typedef struct _GFileInfoClass GFileInfoClass;
* G_FILE_ATTRIBUTE_UNIX_GID: * G_FILE_ATTRIBUTE_UNIX_GID:
* *
* A key in the "unix" namespace for getting the group ID for the file. * A key in the "unix" namespace for getting the group ID for the file.
*
* This attribute is only available for UNIX file systems. * This attribute is only available for UNIX file systems.
*
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32.
**/ **/
#define G_FILE_ATTRIBUTE_UNIX_GID "unix::gid" /* uint32 */ #define G_FILE_ATTRIBUTE_UNIX_GID "unix::gid" /* uint32 */
@ -620,9 +717,13 @@ typedef struct _GFileInfoClass GFileInfoClass;
* G_FILE_ATTRIBUTE_UNIX_RDEV: * G_FILE_ATTRIBUTE_UNIX_RDEV:
* *
* A key in the "unix" namespace for getting the device ID for the file * A key in the "unix" namespace for getting the device ID for the file
* (if it is a special file). See lstat() documentation. This attribute * (if it is a special file).
* is only available for UNIX file systems. Corresponding #GFileAttributeType *
* is %G_FILE_ATTRIBUTE_TYPE_UINT32. * See the documentation for `lstat()`.
*
* This attribute is only available for UNIX file systems.
*
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32.
**/ **/
#define G_FILE_ATTRIBUTE_UNIX_RDEV "unix::rdev" /* uint32 */ #define G_FILE_ATTRIBUTE_UNIX_RDEV "unix::rdev" /* uint32 */
@ -630,7 +731,10 @@ typedef struct _GFileInfoClass GFileInfoClass;
* G_FILE_ATTRIBUTE_UNIX_BLOCK_SIZE: * G_FILE_ATTRIBUTE_UNIX_BLOCK_SIZE:
* *
* A key in the "unix" namespace for getting the block size for the file * A key in the "unix" namespace for getting the block size for the file
* system. This attribute is only available for UNIX file systems. * system.
*
* This attribute is only available for UNIX file systems.
*
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32.
**/ **/
#define G_FILE_ATTRIBUTE_UNIX_BLOCK_SIZE "unix::block-size" /* uint32 */ #define G_FILE_ATTRIBUTE_UNIX_BLOCK_SIZE "unix::block-size" /* uint32 */
@ -639,7 +743,10 @@ typedef struct _GFileInfoClass GFileInfoClass;
* G_FILE_ATTRIBUTE_UNIX_BLOCKS: * G_FILE_ATTRIBUTE_UNIX_BLOCKS:
* *
* A key in the "unix" namespace for getting the number of blocks allocated * A key in the "unix" namespace for getting the number of blocks allocated
* for the file. This attribute is only available for UNIX file systems. * for the file.
*
* This attribute is only available for UNIX file systems.
*
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64. * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64.
**/ **/
#define G_FILE_ATTRIBUTE_UNIX_BLOCKS "unix::blocks" /* uint64 */ #define G_FILE_ATTRIBUTE_UNIX_BLOCKS "unix::blocks" /* uint64 */
@ -648,9 +755,14 @@ typedef struct _GFileInfoClass GFileInfoClass;
* G_FILE_ATTRIBUTE_UNIX_IS_MOUNTPOINT: * G_FILE_ATTRIBUTE_UNIX_IS_MOUNTPOINT:
* *
* A key in the "unix" namespace for checking if the file represents a * A key in the "unix" namespace for checking if the file represents a
* UNIX mount point. This attribute is %TRUE if the file is a UNIX mount * UNIX mount point.
* point. Since 2.58, `/` is considered to be a mount point. *
* This attribute is %TRUE if the file is a UNIX mount point.
*
* Since 2.58, `/` is considered to be a mount point.
*
* This attribute is only available for UNIX file systems. * This attribute is only available for UNIX file systems.
*
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
**/ **/
#define G_FILE_ATTRIBUTE_UNIX_IS_MOUNTPOINT "unix::is-mountpoint" /* boolean */ #define G_FILE_ATTRIBUTE_UNIX_IS_MOUNTPOINT "unix::is-mountpoint" /* boolean */
@ -661,9 +773,13 @@ typedef struct _GFileInfoClass GFileInfoClass;
* G_FILE_ATTRIBUTE_DOS_IS_ARCHIVE: * G_FILE_ATTRIBUTE_DOS_IS_ARCHIVE:
* *
* A key in the "dos" namespace for checking if the file's archive flag * A key in the "dos" namespace for checking if the file's archive flag
* is set. This attribute is %TRUE if the archive flag is set. This attribute * is set.
* is only available for DOS file systems. Corresponding #GFileAttributeType *
* is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. * This attribute is %TRUE if the archive flag is set.
*
* This attribute is only available for DOS file systems.
*
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
**/ **/
#define G_FILE_ATTRIBUTE_DOS_IS_ARCHIVE "dos::is-archive" /* boolean */ #define G_FILE_ATTRIBUTE_DOS_IS_ARCHIVE "dos::is-archive" /* boolean */
@ -671,9 +787,13 @@ typedef struct _GFileInfoClass GFileInfoClass;
* G_FILE_ATTRIBUTE_DOS_IS_SYSTEM: * G_FILE_ATTRIBUTE_DOS_IS_SYSTEM:
* *
* A key in the "dos" namespace for checking if the file's backup flag * A key in the "dos" namespace for checking if the file's backup flag
* is set. This attribute is %TRUE if the backup flag is set. This attribute * is set.
* is only available for DOS file systems. Corresponding #GFileAttributeType *
* is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. * This attribute is %TRUE if the backup flag is set.
*
* This attribute is only available for DOS file systems.
*
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
**/ **/
#define G_FILE_ATTRIBUTE_DOS_IS_SYSTEM "dos::is-system" /* boolean */ #define G_FILE_ATTRIBUTE_DOS_IS_SYSTEM "dos::is-system" /* boolean */
@ -682,9 +802,12 @@ typedef struct _GFileInfoClass GFileInfoClass;
* *
* A key in the "dos" namespace for checking if the file is a NTFS mount point * A key in the "dos" namespace for checking if the file is a NTFS mount point
* (a volume mount or a junction point). * (a volume mount or a junction point).
*
* This attribute is %TRUE if file is a reparse point of type * This attribute is %TRUE if file is a reparse point of type
* [IO_REPARSE_TAG_MOUNT_POINT](https://msdn.microsoft.com/en-us/library/dd541667.aspx). * [IO_REPARSE_TAG_MOUNT_POINT](https://msdn.microsoft.com/en-us/library/dd541667.aspx).
*
* This attribute is only available for DOS file systems. * This attribute is only available for DOS file systems.
*
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
* *
* Since: 2.60 * Since: 2.60
@ -695,10 +818,13 @@ typedef struct _GFileInfoClass GFileInfoClass;
* G_FILE_ATTRIBUTE_DOS_REPARSE_POINT_TAG: * G_FILE_ATTRIBUTE_DOS_REPARSE_POINT_TAG:
* *
* A key in the "dos" namespace for getting the file NTFS reparse tag. * A key in the "dos" namespace for getting the file NTFS reparse tag.
*
* This value is 0 for files that are not reparse points. * This value is 0 for files that are not reparse points.
*
* See the [Reparse Tags](https://msdn.microsoft.com/en-us/library/dd541667.aspx) * See the [Reparse Tags](https://msdn.microsoft.com/en-us/library/dd541667.aspx)
* page for possible reparse tag values. Corresponding #GFileAttributeType * page for possible reparse tag values.
* is %G_FILE_ATTRIBUTE_TYPE_UINT32. *
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32.
* *
* Since: 2.60 * Since: 2.60
**/ **/
@ -710,8 +836,9 @@ typedef struct _GFileInfoClass GFileInfoClass;
* G_FILE_ATTRIBUTE_OWNER_USER: * G_FILE_ATTRIBUTE_OWNER_USER:
* *
* A key in the "owner" namespace for getting the user name of the * A key in the "owner" namespace for getting the user name of the
* file's owner. Corresponding #GFileAttributeType is * file's owner.
* %G_FILE_ATTRIBUTE_TYPE_STRING. *
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
**/ **/
#define G_FILE_ATTRIBUTE_OWNER_USER "owner::user" /* string */ #define G_FILE_ATTRIBUTE_OWNER_USER "owner::user" /* string */
@ -719,8 +846,9 @@ typedef struct _GFileInfoClass GFileInfoClass;
* G_FILE_ATTRIBUTE_OWNER_USER_REAL: * G_FILE_ATTRIBUTE_OWNER_USER_REAL:
* *
* A key in the "owner" namespace for getting the real name of the * A key in the "owner" namespace for getting the real name of the
* user that owns the file. Corresponding #GFileAttributeType is * user that owns the file.
* %G_FILE_ATTRIBUTE_TYPE_STRING. *
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
**/ **/
#define G_FILE_ATTRIBUTE_OWNER_USER_REAL "owner::user-real" /* string */ #define G_FILE_ATTRIBUTE_OWNER_USER_REAL "owner::user-real" /* string */
@ -728,6 +856,7 @@ typedef struct _GFileInfoClass GFileInfoClass;
* G_FILE_ATTRIBUTE_OWNER_GROUP: * G_FILE_ATTRIBUTE_OWNER_GROUP:
* *
* A key in the "owner" namespace for getting the file owner's group. * A key in the "owner" namespace for getting the file owner's group.
*
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
**/ **/
#define G_FILE_ATTRIBUTE_OWNER_GROUP "owner::group" /* string */ #define G_FILE_ATTRIBUTE_OWNER_GROUP "owner::group" /* string */
@ -738,22 +867,26 @@ typedef struct _GFileInfoClass GFileInfoClass;
* G_FILE_ATTRIBUTE_THUMBNAIL_PATH: * G_FILE_ATTRIBUTE_THUMBNAIL_PATH:
* *
* A key in the "thumbnail" namespace for getting the path to the thumbnail * A key in the "thumbnail" namespace for getting the path to the thumbnail
* image. Corresponding #GFileAttributeType is * image.
* %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING. *
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING.
**/ **/
#define G_FILE_ATTRIBUTE_THUMBNAIL_PATH "thumbnail::path" /* bytestring */ #define G_FILE_ATTRIBUTE_THUMBNAIL_PATH "thumbnail::path" /* bytestring */
/** /**
* G_FILE_ATTRIBUTE_THUMBNAILING_FAILED: * G_FILE_ATTRIBUTE_THUMBNAILING_FAILED:
* *
* A key in the "thumbnail" namespace for checking if thumbnailing failed. * A key in the "thumbnail" namespace for checking if thumbnailing failed.
* This attribute is %TRUE if thumbnailing failed. Corresponding *
* #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. * This attribute is %TRUE if thumbnailing failed.
*
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
**/ **/
#define G_FILE_ATTRIBUTE_THUMBNAILING_FAILED "thumbnail::failed" /* boolean */ #define G_FILE_ATTRIBUTE_THUMBNAILING_FAILED "thumbnail::failed" /* boolean */
/** /**
* G_FILE_ATTRIBUTE_THUMBNAIL_IS_VALID: * G_FILE_ATTRIBUTE_THUMBNAIL_IS_VALID:
* *
* A key in the "thumbnail" namespace for checking whether the thumbnail is outdated. * A key in the "thumbnail" namespace for checking whether the thumbnail is outdated.
*
* This attribute is %TRUE if the thumbnail is up-to-date with the file it represents, * This attribute is %TRUE if the thumbnail is up-to-date with the file it represents,
* and %FALSE if the file has been modified since the thumbnail was generated. * and %FALSE if the file has been modified since the thumbnail was generated.
* *
@ -772,10 +905,13 @@ typedef struct _GFileInfoClass GFileInfoClass;
* G_FILE_ATTRIBUTE_PREVIEW_ICON: * G_FILE_ATTRIBUTE_PREVIEW_ICON:
* *
* A key in the "preview" namespace for getting a #GIcon that can be * A key in the "preview" namespace for getting a #GIcon that can be
* used to get preview of the file. For example, it may be a low * used to get preview of the file.
* resolution thumbnail without metadata. Corresponding *
* #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_OBJECT. The value * For example, it may be a low resolution thumbnail without metadata.
* for this key should contain a #GIcon. *
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_OBJECT.
*
* The value for this key should contain a #GIcon.
* *
* Since: 2.20 * Since: 2.20
**/ **/
@ -786,27 +922,30 @@ typedef struct _GFileInfoClass GFileInfoClass;
/** /**
* G_FILE_ATTRIBUTE_FILESYSTEM_SIZE: * G_FILE_ATTRIBUTE_FILESYSTEM_SIZE:
* *
* A key in the "filesystem" namespace for getting the total size (in bytes) of the file system, * A key in the "filesystem" namespace for getting the total size (in
* used in g_file_query_filesystem_info(). Corresponding #GFileAttributeType * bytes) of the file system, used in g_file_query_filesystem_info().
* is %G_FILE_ATTRIBUTE_TYPE_UINT64. *
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64.
**/ **/
#define G_FILE_ATTRIBUTE_FILESYSTEM_SIZE "filesystem::size" /* uint64 */ #define G_FILE_ATTRIBUTE_FILESYSTEM_SIZE "filesystem::size" /* uint64 */
/** /**
* G_FILE_ATTRIBUTE_FILESYSTEM_FREE: * G_FILE_ATTRIBUTE_FILESYSTEM_FREE:
* *
* A key in the "filesystem" namespace for getting the number of bytes of free space left on the * A key in the "filesystem" namespace for getting the number of bytes
* file system. Corresponding #GFileAttributeType is * of free space left on the file system.
* %G_FILE_ATTRIBUTE_TYPE_UINT64. *
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64.
**/ **/
#define G_FILE_ATTRIBUTE_FILESYSTEM_FREE "filesystem::free" /* uint64 */ #define G_FILE_ATTRIBUTE_FILESYSTEM_FREE "filesystem::free" /* uint64 */
/** /**
* G_FILE_ATTRIBUTE_FILESYSTEM_USED: * G_FILE_ATTRIBUTE_FILESYSTEM_USED:
* *
* A key in the "filesystem" namespace for getting the number of bytes of used on the * A key in the "filesystem" namespace for getting the number of bytes
* file system. Corresponding #GFileAttributeType is * used by data on the file system.
* %G_FILE_ATTRIBUTE_TYPE_UINT64. *
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64.
* *
* Since: 2.32 * Since: 2.32
*/ */
@ -816,6 +955,7 @@ typedef struct _GFileInfoClass GFileInfoClass;
* G_FILE_ATTRIBUTE_FILESYSTEM_TYPE: * G_FILE_ATTRIBUTE_FILESYSTEM_TYPE:
* *
* A key in the "filesystem" namespace for getting the file system's type. * A key in the "filesystem" namespace for getting the file system's type.
*
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
**/ **/
#define G_FILE_ATTRIBUTE_FILESYSTEM_TYPE "filesystem::type" /* string */ #define G_FILE_ATTRIBUTE_FILESYSTEM_TYPE "filesystem::type" /* string */
@ -824,7 +964,10 @@ typedef struct _GFileInfoClass GFileInfoClass;
* G_FILE_ATTRIBUTE_FILESYSTEM_READONLY: * G_FILE_ATTRIBUTE_FILESYSTEM_READONLY:
* *
* A key in the "filesystem" namespace for checking if the file system * A key in the "filesystem" namespace for checking if the file system
* is read only. Is set to %TRUE if the file system is read only. * is read only.
*
* Is set to %TRUE if the file system is read only.
*
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
**/ **/
#define G_FILE_ATTRIBUTE_FILESYSTEM_READONLY "filesystem::readonly" /* boolean */ #define G_FILE_ATTRIBUTE_FILESYSTEM_READONLY "filesystem::readonly" /* boolean */
@ -834,8 +977,9 @@ typedef struct _GFileInfoClass GFileInfoClass;
* *
* A key in the "filesystem" namespace for hinting a file manager * A key in the "filesystem" namespace for hinting a file manager
* application whether it should preview (e.g. thumbnail) files on the * application whether it should preview (e.g. thumbnail) files on the
* file system. The value for this key contain a * file system.
* #GFilesystemPreviewType. *
* The value for this key contain a #GFilesystemPreviewType.
**/ **/
#define G_FILE_ATTRIBUTE_FILESYSTEM_USE_PREVIEW "filesystem::use-preview" /* uint32 (GFilesystemPreviewType) */ #define G_FILE_ATTRIBUTE_FILESYSTEM_USE_PREVIEW "filesystem::use-preview" /* uint32 (GFilesystemPreviewType) */
@ -843,7 +987,10 @@ typedef struct _GFileInfoClass GFileInfoClass;
* G_FILE_ATTRIBUTE_FILESYSTEM_REMOTE: * G_FILE_ATTRIBUTE_FILESYSTEM_REMOTE:
* *
* A key in the "filesystem" namespace for checking if the file system * A key in the "filesystem" namespace for checking if the file system
* is remote. Is set to %TRUE if the file system is remote. * is remote.
*
* Is set to %TRUE if the file system is remote.
*
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN.
**/ **/
#define G_FILE_ATTRIBUTE_FILESYSTEM_REMOTE "filesystem::remote" /* boolean */ #define G_FILE_ATTRIBUTE_FILESYSTEM_REMOTE "filesystem::remote" /* boolean */
@ -852,8 +999,9 @@ typedef struct _GFileInfoClass GFileInfoClass;
* G_FILE_ATTRIBUTE_GVFS_BACKEND: * G_FILE_ATTRIBUTE_GVFS_BACKEND:
* *
* A key in the "gvfs" namespace that gets the name of the current * A key in the "gvfs" namespace that gets the name of the current
* GVFS backend in use. Corresponding #GFileAttributeType is * GVFS backend in use.
* %G_FILE_ATTRIBUTE_TYPE_STRING. *
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
**/ **/
#define G_FILE_ATTRIBUTE_GVFS_BACKEND "gvfs::backend" /* string */ #define G_FILE_ATTRIBUTE_GVFS_BACKEND "gvfs::backend" /* string */
@ -861,17 +1009,21 @@ typedef struct _GFileInfoClass GFileInfoClass;
* G_FILE_ATTRIBUTE_SELINUX_CONTEXT: * G_FILE_ATTRIBUTE_SELINUX_CONTEXT:
* *
* A key in the "selinux" namespace for getting the file's SELinux * A key in the "selinux" namespace for getting the file's SELinux
* context. Corresponding #GFileAttributeType is * context.
* %G_FILE_ATTRIBUTE_TYPE_STRING. Note that this attribute is only *
* available if GLib has been built with SELinux support. * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
*
* Note that this attribute is only available if GLib has been built
* with SELinux support.
**/ **/
#define G_FILE_ATTRIBUTE_SELINUX_CONTEXT "selinux::context" /* string */ #define G_FILE_ATTRIBUTE_SELINUX_CONTEXT "selinux::context" /* string */
/** /**
* G_FILE_ATTRIBUTE_TRASH_ITEM_COUNT: * G_FILE_ATTRIBUTE_TRASH_ITEM_COUNT:
* *
* A key in the "trash" namespace. When requested against * A key in the "trash" namespace for getting the number of (toplevel) items
* `trash:///` returns the number of (toplevel) items in the trash folder. * that are present in the `trash:///` folder.
*
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32.
**/ **/
#define G_FILE_ATTRIBUTE_TRASH_ITEM_COUNT "trash::item-count" /* uint32 */ #define G_FILE_ATTRIBUTE_TRASH_ITEM_COUNT "trash::item-count" /* uint32 */
@ -879,10 +1031,10 @@ typedef struct _GFileInfoClass GFileInfoClass;
/** /**
* G_FILE_ATTRIBUTE_TRASH_ORIG_PATH: * G_FILE_ATTRIBUTE_TRASH_ORIG_PATH:
* *
* A key in the "trash" namespace. When requested against * A key in the "trash" namespace for getting the original path of a file
* items in `trash:///`, will return the original path to the file before it * inside the `trash:///` folder before it was trashed.
* was trashed. Corresponding #GFileAttributeType is *
* %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING. * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING.
* *
* Since: 2.24 * Since: 2.24
**/ **/
@ -891,9 +1043,11 @@ typedef struct _GFileInfoClass GFileInfoClass;
/** /**
* G_FILE_ATTRIBUTE_TRASH_DELETION_DATE: * G_FILE_ATTRIBUTE_TRASH_DELETION_DATE:
* *
* A key in the "trash" namespace. When requested against * A key in the "trash" namespace for getting the deletion date and time
* items in `trash:///`, will return the date and time when the file * of a file inside the `trash:///` folder.
* was trashed. The format of the returned string is YYYY-MM-DDThh:mm:ss. *
* The format of the returned string is `YYYY-MM-DDThh:mm:ss`.
*
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. * Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING.
* *
* Since: 2.24 * Since: 2.24
@ -904,8 +1058,9 @@ typedef struct _GFileInfoClass GFileInfoClass;
* G_FILE_ATTRIBUTE_RECENT_MODIFIED: * G_FILE_ATTRIBUTE_RECENT_MODIFIED:
* *
* A key in the "recent" namespace for getting time, when the metadata for the * A key in the "recent" namespace for getting time, when the metadata for the
* file in `recent:///` was last changed. Corresponding #GFileAttributeType is * file in `recent:///` was last changed.
* %G_FILE_ATTRIBUTE_TYPE_INT64. *
* Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_INT64.
* *
* Since: 2.52 * Since: 2.52
**/ **/

1
gio/gmemorymonitor.c
View File

@ -42,6 +42,7 @@
* There is also an implementation for use inside Flatpak sandboxes. * There is also an implementation for use inside Flatpak sandboxes.
* *
* Possible actions to take when the signal is received are: * Possible actions to take when the signal is received are:
*
* - Free caches * - Free caches
* - Save files that haven't been looked at in a while to disk, ready to be reopened when needed * - Save files that haven't been looked at in a while to disk, ready to be reopened when needed
* - Run a garbage collection cycle * - Run a garbage collection cycle

2
gio/gzlibcompressor.c
View File

@ -41,7 +41,7 @@ enum {
}; };
/** /**
* SECTION:gzcompressor * SECTION:gzlibcompressor
* @short_description: Zlib compressor * @short_description: Zlib compressor
* @include: gio/gio.h * @include: gio/gio.h
* *

2
gio/gzlibdecompressor.c
View File

@ -40,7 +40,7 @@ enum {
}; };
/** /**
* SECTION:gzdecompressor * SECTION:gzlibdecompressor
* @short_description: Zlib decompressor * @short_description: Zlib decompressor
* @include: gio/gio.h * @include: gio/gio.h
* *

6
glib/gasyncqueue.c
View File

@ -88,9 +88,9 @@
/** /**
* GAsyncQueue: * GAsyncQueue:
* *
* The GAsyncQueue struct is an opaque data structure which represents * An opaque data structure which represents an asynchronous queue.
* an asynchronous queue. It should only be accessed through the *
* g_async_queue_* functions. * It should only be accessed through the `g_async_queue_*` functions.
*/ */
struct _GAsyncQueue struct _GAsyncQueue
{ {

4
glib/gbookmarkfile.h
View File

@ -33,6 +33,7 @@ G_BEGIN_DECLS
* G_BOOKMARK_FILE_ERROR: * G_BOOKMARK_FILE_ERROR:
* *
* Error domain for bookmark file parsing. * Error domain for bookmark file parsing.
*
* Errors in this domain will be from the #GBookmarkFileError * Errors in this domain will be from the #GBookmarkFileError
* enumeration. See #GError for information on error domains. * enumeration. See #GError for information on error domains.
*/ */
@ -72,8 +73,7 @@ GQuark g_bookmark_file_error_quark (void);
/** /**
* GBookmarkFile: * GBookmarkFile:
* *
* The `GBookmarkFile` structure contains only * An opaque data structure representing a set of bookmarks.
* private data and should not be directly accessed.
*/ */
typedef struct _GBookmarkFile GBookmarkFile; typedef struct _GBookmarkFile GBookmarkFile;

1
glib/gchecksum.h
View File

@ -56,6 +56,7 @@ typedef enum {
* GChecksum: * GChecksum:
* *
* An opaque structure representing a checksumming operation. * An opaque structure representing a checksumming operation.
*
* To create a new GChecksum, use g_checksum_new(). To free * To create a new GChecksum, use g_checksum_new(). To free
* a GChecksum, use g_checksum_free(). * a GChecksum, use g_checksum_free().
* *

6
glib/gdataset.c
View File

@ -121,9 +121,9 @@
/** /**
* GData: * GData:
* *
* The #GData struct is an opaque data structure to represent a * An opaque data structure that represents a keyed data list.
* [Keyed Data List][glib-Keyed-Data-Lists]. It should only be *
* accessed via the following functions. * See also: [Keyed data lists][glib-Keyed-Data-Lists].
**/ **/
/** /**

27
glib/gdate.c
View File

@ -115,7 +115,8 @@
* @tv_usec: microseconds * @tv_usec: microseconds
* *
* Represents a precise time, with seconds and microseconds. * Represents a precise time, with seconds and microseconds.
* Similar to the struct timeval returned by the gettimeofday() *
* Similar to the struct timeval returned by the `gettimeofday()`
* UNIX system call. * UNIX system call.
* *
* GLib is attempting to unify around the use of 64-bit integers to * GLib is attempting to unify around the use of 64-bit integers to
@ -141,7 +142,7 @@
* Represents a day between January 1, Year 1 and a few thousand years in * Represents a day between January 1, Year 1 and a few thousand years in
* the future. None of its members should be accessed directly. * the future. None of its members should be accessed directly.
* *
* If the #GDate-struct is obtained from g_date_new(), it will be safe * If the `GDate` is obtained from g_date_new(), it will be safe
* to mutate but invalid and thus not safe for calendrical computations. * to mutate but invalid and thus not safe for calendrical computations.
* *
* If it's declared on the stack, it will contain garbage so must be * If it's declared on the stack, it will contain garbage so must be
@ -156,7 +157,9 @@
* *
* Simply a replacement for `time_t`. It has been deprecated * Simply a replacement for `time_t`. It has been deprecated
* since it is not equivalent to `time_t` on 64-bit platforms * since it is not equivalent to `time_t` on 64-bit platforms
* with a 64-bit `time_t`. Unrelated to #GTimer. * with a 64-bit `time_t`.
*
* Unrelated to #GTimer.
* *
* Note that #GTime is defined to always be a 32-bit integer, * Note that #GTime is defined to always be a 32-bit integer,
* unlike `time_t` which may be 64-bit on some systems. Therefore, * unlike `time_t` which may be 64-bit on some systems. Therefore,
@ -165,6 +168,7 @@
* function. * function.
* *
* Instead, do the following: * Instead, do the following:
*
* |[<!-- language="C" --> * |[<!-- language="C" -->
* time_t ttime; * time_t ttime;
* GTime gtime; * GTime gtime;
@ -191,7 +195,8 @@
* GDateDay: * GDateDay:
* *
* Integer representing a day of the month; between 1 and 31. * Integer representing a day of the month; between 1 and 31.
* #G_DATE_BAD_DAY represents an invalid day of the month. *
* The %G_DATE_BAD_DAY value represents an invalid day of the month.
*/ */
/** /**
@ -210,16 +215,20 @@
* @G_DATE_NOVEMBER: November * @G_DATE_NOVEMBER: November
* @G_DATE_DECEMBER: December * @G_DATE_DECEMBER: December
* *
* Enumeration representing a month; values are #G_DATE_JANUARY, * Enumeration representing a month; values are %G_DATE_JANUARY,
* #G_DATE_FEBRUARY, etc. #G_DATE_BAD_MONTH is the invalid value. * %G_DATE_FEBRUARY, etc. %G_DATE_BAD_MONTH is the invalid value.
*/ */
/** /**
* GDateYear: * GDateYear:
* *
* Integer representing a year; #G_DATE_BAD_YEAR is the invalid * Integer type representing a year.
* value. The year must be 1 or higher; negative (BC) years are not *
* allowed. The year is represented with four digits. * The %G_DATE_BAD_YEAR value is the invalid value. The year
* must be 1 or higher; negative ([BCE](https://en.wikipedia.org/wiki/Common_Era))
* years are not allowed.
*
* The year is represented with four digits.
*/ */
/** /**

3
glib/gdatetime.h
View File

@ -89,8 +89,7 @@ typedef gint64 GTimeSpan;
/** /**
* GDateTime: * GDateTime:
* *
* `GDateTime` is an opaque structure whose members * An opaque structure that represents a date and time, including a time zone.
* cannot be accessed directly.
* *
* Since: 2.26 * Since: 2.26
*/ */

5
glib/gfileutils.c
View File

@ -502,15 +502,16 @@ G_DEFINE_QUARK (g-file-error-quark, g_file_error)
* @err_no: an "errno" value * @err_no: an "errno" value
* *
* Gets a #GFileError constant based on the passed-in @err_no. * Gets a #GFileError constant based on the passed-in @err_no.
*
* For example, if you pass in `EEXIST` this function returns * For example, if you pass in `EEXIST` this function returns
* #G_FILE_ERROR_EXIST. Unlike `errno` values, you can portably * %G_FILE_ERROR_EXIST. Unlike `errno` values, you can portably
* assume that all #GFileError values will exist. * assume that all #GFileError values will exist.
* *
* Normally a #GFileError value goes into a #GError returned * Normally a #GFileError value goes into a #GError returned
* from a function that manipulates files. So you would use * from a function that manipulates files. So you would use
* g_file_error_from_errno() when constructing a #GError. * g_file_error_from_errno() when constructing a #GError.
* *
* Returns: #GFileError corresponding to the given @errno * Returns: #GFileError corresponding to the given @err_no
**/ **/
GFileError GFileError
g_file_error_from_errno (gint err_no) g_file_error_from_errno (gint err_no)

63
glib/gkeyfile.c
View File

@ -257,11 +257,12 @@
/** /**
* G_KEY_FILE_DESKTOP_KEY_TYPE: * G_KEY_FILE_DESKTOP_KEY_TYPE:
* *
* A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a string
* giving the type of the desktop entry. Usually * giving the type of the desktop entry.
* #G_KEY_FILE_DESKTOP_TYPE_APPLICATION, *
* #G_KEY_FILE_DESKTOP_TYPE_LINK, or * Usually %G_KEY_FILE_DESKTOP_TYPE_APPLICATION,
* #G_KEY_FILE_DESKTOP_TYPE_DIRECTORY. * %G_KEY_FILE_DESKTOP_TYPE_LINK, or
* %G_KEY_FILE_DESKTOP_TYPE_DIRECTORY.
* *
* Since: 2.14 * Since: 2.14
*/ */
@ -269,7 +270,7 @@
/** /**
* G_KEY_FILE_DESKTOP_KEY_VERSION: * G_KEY_FILE_DESKTOP_KEY_VERSION:
* *
* A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a string
* giving the version of the Desktop Entry Specification used for * giving the version of the Desktop Entry Specification used for
* the desktop entry file. * the desktop entry file.
* *
@ -279,7 +280,7 @@
/** /**
* G_KEY_FILE_DESKTOP_KEY_NAME: * G_KEY_FILE_DESKTOP_KEY_NAME:
* *
* A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a localized * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a localized
* string giving the specific name of the desktop entry. * string giving the specific name of the desktop entry.
* *
* Since: 2.14 * Since: 2.14
@ -288,7 +289,7 @@
/** /**
* G_KEY_FILE_DESKTOP_KEY_GENERIC_NAME: * G_KEY_FILE_DESKTOP_KEY_GENERIC_NAME:
* *
* A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a localized * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a localized
* string giving the generic name of the desktop entry. * string giving the generic name of the desktop entry.
* *
* Since: 2.14 * Since: 2.14
@ -297,7 +298,7 @@
/** /**
* G_KEY_FILE_DESKTOP_KEY_NO_DISPLAY: * G_KEY_FILE_DESKTOP_KEY_NO_DISPLAY:
* *
* A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean
* stating whether the desktop entry should be shown in menus. * stating whether the desktop entry should be shown in menus.
* *
* Since: 2.14 * Since: 2.14
@ -306,7 +307,7 @@
/** /**
* G_KEY_FILE_DESKTOP_KEY_COMMENT: * G_KEY_FILE_DESKTOP_KEY_COMMENT:
* *
* A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a localized * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a localized
* string giving the tooltip for the desktop entry. * string giving the tooltip for the desktop entry.
* *
* Since: 2.14 * Since: 2.14
@ -315,7 +316,7 @@
/** /**
* G_KEY_FILE_DESKTOP_KEY_ICON: * G_KEY_FILE_DESKTOP_KEY_ICON:
* *
* A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a localized * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a localized
* string giving the name of the icon to be displayed for the desktop * string giving the name of the icon to be displayed for the desktop
* entry. * entry.
* *
@ -325,7 +326,7 @@
/** /**
* G_KEY_FILE_DESKTOP_KEY_HIDDEN: * G_KEY_FILE_DESKTOP_KEY_HIDDEN:
* *
* A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean
* stating whether the desktop entry has been deleted by the user. * stating whether the desktop entry has been deleted by the user.
* *
* Since: 2.14 * Since: 2.14
@ -334,7 +335,7 @@
/** /**
* G_KEY_FILE_DESKTOP_KEY_ONLY_SHOW_IN: * G_KEY_FILE_DESKTOP_KEY_ONLY_SHOW_IN:
* *
* A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a list of * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a list of
* strings identifying the environments that should display the * strings identifying the environments that should display the
* desktop entry. * desktop entry.
* *
@ -344,7 +345,7 @@
/** /**
* G_KEY_FILE_DESKTOP_KEY_NOT_SHOW_IN: * G_KEY_FILE_DESKTOP_KEY_NOT_SHOW_IN:
* *
* A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a list of * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a list of
* strings identifying the environments that should not display the * strings identifying the environments that should not display the
* desktop entry. * desktop entry.
* *
@ -354,7 +355,7 @@
/** /**
* G_KEY_FILE_DESKTOP_KEY_TRY_EXEC: * G_KEY_FILE_DESKTOP_KEY_TRY_EXEC:
* *
* A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a string
* giving the file name of a binary on disk used to determine if the * giving the file name of a binary on disk used to determine if the
* program is actually installed. It is only valid for desktop entries * program is actually installed. It is only valid for desktop entries
* with the `Application` type. * with the `Application` type.
@ -365,7 +366,7 @@
/** /**
* G_KEY_FILE_DESKTOP_KEY_EXEC: * G_KEY_FILE_DESKTOP_KEY_EXEC:
* *
* A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a string
* giving the command line to execute. It is only valid for desktop * giving the command line to execute. It is only valid for desktop
* entries with the `Application` type. * entries with the `Application` type.
* *
@ -375,7 +376,7 @@
/** /**
* G_KEY_FILE_DESKTOP_KEY_PATH: * G_KEY_FILE_DESKTOP_KEY_PATH:
* *
* A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a string
* containing the working directory to run the program in. It is only * containing the working directory to run the program in. It is only
* valid for desktop entries with the `Application` type. * valid for desktop entries with the `Application` type.
* *
@ -385,10 +386,10 @@
/** /**
* G_KEY_FILE_DESKTOP_KEY_TERMINAL: * G_KEY_FILE_DESKTOP_KEY_TERMINAL:
* *
* A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean
* stating whether the program should be run in a terminal window. * stating whether the program should be run in a terminal window.
* It is only valid for desktop entries with the *
* `Application` type. * It is only valid for desktop entries with the `Application` type.
* *
* Since: 2.14 * Since: 2.14
*/ */
@ -396,7 +397,7 @@
/** /**
* G_KEY_FILE_DESKTOP_KEY_MIME_TYPE: * G_KEY_FILE_DESKTOP_KEY_MIME_TYPE:
* *
* A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a list * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a list
* of strings giving the MIME types supported by this desktop entry. * of strings giving the MIME types supported by this desktop entry.
* *
* Since: 2.14 * Since: 2.14
@ -405,7 +406,7 @@
/** /**
* G_KEY_FILE_DESKTOP_KEY_CATEGORIES: * G_KEY_FILE_DESKTOP_KEY_CATEGORIES:
* *
* A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a list * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a list
* of strings giving the categories in which the desktop entry * of strings giving the categories in which the desktop entry
* should be shown in a menu. * should be shown in a menu.
* *
@ -415,7 +416,7 @@
/** /**
* G_KEY_FILE_DESKTOP_KEY_STARTUP_NOTIFY: * G_KEY_FILE_DESKTOP_KEY_STARTUP_NOTIFY:
* *
* A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean
* stating whether the application supports the * stating whether the application supports the
* [Startup Notification Protocol Specification](http://www.freedesktop.org/Standards/startup-notification-spec). * [Startup Notification Protocol Specification](http://www.freedesktop.org/Standards/startup-notification-spec).
* *
@ -425,7 +426,7 @@
/** /**
* G_KEY_FILE_DESKTOP_KEY_STARTUP_WM_CLASS: * G_KEY_FILE_DESKTOP_KEY_STARTUP_WM_CLASS:
* *
* A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is string * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is string
* identifying the WM class or name hint of a window that the application * identifying the WM class or name hint of a window that the application
* will create, which can be used to emulate Startup Notification with * will create, which can be used to emulate Startup Notification with
* older applications. * older applications.
@ -436,7 +437,7 @@
/** /**
* G_KEY_FILE_DESKTOP_KEY_URL: * G_KEY_FILE_DESKTOP_KEY_URL:
* *
* A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a string
* giving the URL to access. It is only valid for desktop entries * giving the URL to access. It is only valid for desktop entries
* with the `Link` type. * with the `Link` type.
* *
@ -446,8 +447,8 @@
/** /**
* G_KEY_FILE_DESKTOP_KEY_DBUS_ACTIVATABLE: * G_KEY_FILE_DESKTOP_KEY_DBUS_ACTIVATABLE:
* *
* A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean set to true * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean
* if the application is D-Bus activatable. * set to true if the application is D-Bus activatable.
* *
* Since: 2.38 * Since: 2.38
*/ */
@ -455,7 +456,7 @@
/** /**
* G_KEY_FILE_DESKTOP_KEY_ACTIONS: * G_KEY_FILE_DESKTOP_KEY_ACTIONS:
* *
* A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string list * A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a string list
* giving the available application actions. * giving the available application actions.
* *
* Since: 2.38 * Since: 2.38
@ -464,7 +465,7 @@
/** /**
* G_KEY_FILE_DESKTOP_TYPE_APPLICATION: * G_KEY_FILE_DESKTOP_TYPE_APPLICATION:
* *
* The value of the #G_KEY_FILE_DESKTOP_KEY_TYPE, key for desktop * The value of the %G_KEY_FILE_DESKTOP_KEY_TYPE, key for desktop
* entries representing applications. * entries representing applications.
* *
* Since: 2.14 * Since: 2.14
@ -473,7 +474,7 @@
/** /**
* G_KEY_FILE_DESKTOP_TYPE_LINK: * G_KEY_FILE_DESKTOP_TYPE_LINK:
* *
* The value of the #G_KEY_FILE_DESKTOP_KEY_TYPE, key for desktop * The value of the %G_KEY_FILE_DESKTOP_KEY_TYPE, key for desktop
* entries representing links to documents. * entries representing links to documents.
* *
* Since: 2.14 * Since: 2.14
@ -482,7 +483,7 @@
/** /**
* G_KEY_FILE_DESKTOP_TYPE_DIRECTORY: * G_KEY_FILE_DESKTOP_TYPE_DIRECTORY:
* *
* The value of the #G_KEY_FILE_DESKTOP_KEY_TYPE, key for desktop * The value of the %G_KEY_FILE_DESKTOP_KEY_TYPE, key for desktop
* entries representing directories. * entries representing directories.
* *
* Since: 2.14 * Since: 2.14

59
glib/gmain.c
View File

@ -122,7 +122,7 @@
* thread-safe. * thread-safe.
* *
* Each event source is assigned a priority. The default priority, * Each event source is assigned a priority. The default priority,
* #G_PRIORITY_DEFAULT, is 0. Values less than 0 denote higher priorities. * %G_PRIORITY_DEFAULT, is 0. Values less than 0 denote higher priorities.
* Values greater than 0 denote lower priorities. Events from high priority * Values greater than 0 denote lower priorities. Events from high priority
* sources are always processed before events from lower priority sources. * sources are always processed before events from lower priority sources.
* *
@ -5005,7 +5005,7 @@ g_timeout_source_new_seconds (guint interval)
/** /**
* g_timeout_add_full: (rename-to g_timeout_add) * g_timeout_add_full: (rename-to g_timeout_add)
* @priority: the priority of the timeout source. Typically this will be in * @priority: the priority of the timeout source. Typically this will be in
* the range between #G_PRIORITY_DEFAULT and #G_PRIORITY_HIGH. * the range between %G_PRIORITY_DEFAULT and %G_PRIORITY_HIGH.
* @interval: the time between calls to the function, in milliseconds * @interval: the time between calls to the function, in milliseconds
* (1/1000ths of a second) * (1/1000ths of a second)
* @function: function to call * @function: function to call
@ -5074,10 +5074,12 @@ g_timeout_add_full (gint priority,
* @data: data to pass to @function * @data: data to pass to @function
* *
* Sets a function to be called at regular intervals, with the default * Sets a function to be called at regular intervals, with the default
* priority, #G_PRIORITY_DEFAULT. The function is called repeatedly * priority, %G_PRIORITY_DEFAULT.
* until it returns %FALSE, at which point the timeout is automatically *
* destroyed and the function will not be called again. The first call * The given @function is called repeatedly until it returns %G_SOURCE_REMOVE
* to the function will be at the end of the first @interval. * or %FALSE, at which point the timeout is automatically destroyed and the
* function will not be called again. The first call to the function will be
* at the end of the first @interval.
* *
* Note that timeout functions may be delayed, due to the processing of other * Note that timeout functions may be delayed, due to the processing of other
* event sources. Thus they should not be relied on for precise timing. * event sources. Thus they should not be relied on for precise timing.
@ -5118,24 +5120,25 @@ g_timeout_add (guint32 interval,
/** /**
* g_timeout_add_seconds_full: (rename-to g_timeout_add_seconds) * g_timeout_add_seconds_full: (rename-to g_timeout_add_seconds)
* @priority: the priority of the timeout source. Typically this will be in * @priority: the priority of the timeout source. Typically this will be in
* the range between #G_PRIORITY_DEFAULT and #G_PRIORITY_HIGH. * the range between %G_PRIORITY_DEFAULT and %G_PRIORITY_HIGH.
* @interval: the time between calls to the function, in seconds * @interval: the time between calls to the function, in seconds
* @function: function to call * @function: function to call
* @data: data to pass to @function * @data: data to pass to @function
* @notify: (nullable): function to call when the timeout is removed, or %NULL * @notify: (nullable): function to call when the timeout is removed, or %NULL
* *
* Sets a function to be called at regular intervals, with @priority. * Sets a function to be called at regular intervals, with @priority.
* The function is called repeatedly until it returns %FALSE, at which *
* point the timeout is automatically destroyed and the function will * The function is called repeatedly until it returns %G_SOURCE_REMOVE
* not be called again. * or %FALSE, at which point the timeout is automatically destroyed and
* the function will not be called again.
* *
* Unlike g_timeout_add(), this function operates at whole second granularity. * Unlike g_timeout_add(), this function operates at whole second granularity.
* The initial starting point of the timer is determined by the implementation * The initial starting point of the timer is determined by the implementation
* and the implementation is expected to group multiple timers together so that * and the implementation is expected to group multiple timers together so that
* they fire all at the same time. * they fire all at the same time. To allow this grouping, the @interval to the
* To allow this grouping, the @interval to the first timer is rounded * first timer is rounded and can deviate up to one second from the specified
* and can deviate up to one second from the specified interval. * interval. Subsequent timer iterations will generally run at the specified
* Subsequent timer iterations will generally run at the specified interval. * interval.
* *
* Note that timeout functions may be delayed, due to the processing of other * Note that timeout functions may be delayed, due to the processing of other
* event sources. Thus they should not be relied on for precise timing. * event sources. Thus they should not be relied on for precise timing.
@ -5198,8 +5201,10 @@ g_timeout_add_seconds_full (gint priority,
* @data: data to pass to @function * @data: data to pass to @function
* *
* Sets a function to be called at regular intervals with the default * Sets a function to be called at regular intervals with the default
* priority, #G_PRIORITY_DEFAULT. The function is called repeatedly until * priority, %G_PRIORITY_DEFAULT.
* it returns %FALSE, at which point the timeout is automatically destroyed *
* The function is called repeatedly until it returns %G_SOURCE_REMOVE
* or %FALSE, at which point the timeout is automatically destroyed
* and the function will not be called again. * and the function will not be called again.
* *
* This internally creates a main loop source using * This internally creates a main loop source using
@ -5753,7 +5758,7 @@ g_child_watch_source_new (GPid pid)
/** /**
* g_child_watch_add_full: (rename-to g_child_watch_add) * g_child_watch_add_full: (rename-to g_child_watch_add)
* @priority: the priority of the idle source. Typically this will be in the * @priority: the priority of the idle source. Typically this will be in the
* range between #G_PRIORITY_DEFAULT_IDLE and #G_PRIORITY_HIGH_IDLE. * range between %G_PRIORITY_DEFAULT_IDLE and %G_PRIORITY_HIGH_IDLE.
* @pid: process to watch. On POSIX the positive pid of a child process. On * @pid: process to watch. On POSIX the positive pid of a child process. On
* Windows a handle for a process (which doesn't have to be a child). * Windows a handle for a process (which doesn't have to be a child).
* @function: function to call * @function: function to call
@ -5764,7 +5769,7 @@ g_child_watch_source_new (GPid pid)
* exits, at the priority @priority. * exits, at the priority @priority.
* *
* If you obtain @pid from g_spawn_async() or g_spawn_async_with_pipes() * If you obtain @pid from g_spawn_async() or g_spawn_async_with_pipes()
* you will need to pass #G_SPAWN_DO_NOT_REAP_CHILD as flag to * you will need to pass %G_SPAWN_DO_NOT_REAP_CHILD as flag to
* the spawn function for the child watching to work. * the spawn function for the child watching to work.
* *
* In many programs, you will want to call g_spawn_check_wait_status() * In many programs, you will want to call g_spawn_check_wait_status()
@ -5819,16 +5824,16 @@ g_child_watch_add_full (gint priority,
/** /**
* g_child_watch_add: * g_child_watch_add:
* @pid: process id to watch. On POSIX the positive pid of a child * @pid: process id to watch. On POSIX the positive pid of a child
* process. On Windows a handle for a process (which doesn't have to be * process. On Windows a handle for a process (which doesn't have
* a child). * to be a child).
* @function: function to call * @function: function to call
* @data: data to pass to @function * @data: data to pass to @function
* *
* Sets a function to be called when the child indicated by @pid * Sets a function to be called when the child indicated by @pid
* exits, at a default priority, #G_PRIORITY_DEFAULT. * exits, at a default priority, %G_PRIORITY_DEFAULT.
* *
* If you obtain @pid from g_spawn_async() or g_spawn_async_with_pipes() * If you obtain @pid from g_spawn_async() or g_spawn_async_with_pipes()
* you will need to pass #G_SPAWN_DO_NOT_REAP_CHILD as flag to * you will need to pass %G_SPAWN_DO_NOT_REAP_CHILD as flag to
* the spawn function for the child watching to work. * the spawn function for the child watching to work.
* *
* Note that on platforms where #GPid must be explicitly closed * Note that on platforms where #GPid must be explicitly closed
@ -5926,13 +5931,15 @@ g_idle_source_new (void)
/** /**
* g_idle_add_full: (rename-to g_idle_add) * g_idle_add_full: (rename-to g_idle_add)
* @priority: the priority of the idle source. Typically this will be in the * @priority: the priority of the idle source. Typically this will be in the
* range between #G_PRIORITY_DEFAULT_IDLE and #G_PRIORITY_HIGH_IDLE. * range between %G_PRIORITY_DEFAULT_IDLE and %G_PRIORITY_HIGH_IDLE.
* @function: function to call * @function: function to call
* @data: data to pass to @function * @data: data to pass to @function
* @notify: (nullable): function to call when the idle is removed, or %NULL * @notify: (nullable): function to call when the idle is removed, or %NULL
* *
* Adds a function to be called whenever there are no higher priority * Adds a function to be called whenever there are no higher priority
* events pending. If the function returns %FALSE it is automatically * events pending.
*
* If the function returns %G_SOURCE_REMOVE or %FALSE it is automatically
* removed from the list of event sources and will not be called again. * removed from the list of event sources and will not be called again.
* *
* See [memory management of sources][mainloop-memory-management] for details * See [memory management of sources][mainloop-memory-management] for details
@ -5979,7 +5986,7 @@ g_idle_add_full (gint priority,
* *
* Adds a function to be called whenever there are no higher priority * Adds a function to be called whenever there are no higher priority
* events pending to the default main loop. The function is given the * events pending to the default main loop. The function is given the
* default idle priority, #G_PRIORITY_DEFAULT_IDLE. If the function * default idle priority, %G_PRIORITY_DEFAULT_IDLE. If the function
* returns %FALSE it is automatically removed from the list of event * returns %FALSE it is automatically removed from the list of event
* sources and will not be called again. * sources and will not be called again.
* *
@ -6035,7 +6042,7 @@ g_idle_remove_by_data (gpointer data)
* *
* In any other case, an idle source is created to call @function and * In any other case, an idle source is created to call @function and
* that source is attached to @context (presumably to be run in another * that source is attached to @context (presumably to be run in another
* thread). The idle source is attached with #G_PRIORITY_DEFAULT * thread). The idle source is attached with %G_PRIORITY_DEFAULT
* priority. If you want a different priority, use * priority. If you want a different priority, use
* g_main_context_invoke_full(). * g_main_context_invoke_full().
* *

38
glib/gmessages.c
View File

@ -383,7 +383,7 @@ myInvalidParameterHandler(const wchar_t *expression,
* @...: format string, followed by parameters to insert * @...: format string, followed by parameters to insert
* into the format string (as with printf()) * into the format string (as with printf())
* *
* Logs a "critical warning" (#G_LOG_LEVEL_CRITICAL). * Logs a "critical warning" (%G_LOG_LEVEL_CRITICAL).
* *
* Critical warnings are intended to be used in the event of an error * Critical warnings are intended to be used in the event of an error
* that originated in the current process (a programmer error). * that originated in the current process (a programmer error).
@ -797,37 +797,41 @@ g_log_set_fatal_mask (const gchar *log_domain,
* application domain * application domain
* @log_levels: the log levels to apply the log handler for. * @log_levels: the log levels to apply the log handler for.
* To handle fatal and recursive messages as well, combine * To handle fatal and recursive messages as well, combine
* the log levels with the #G_LOG_FLAG_FATAL and * the log levels with the %G_LOG_FLAG_FATAL and
* #G_LOG_FLAG_RECURSION bit flags. * %G_LOG_FLAG_RECURSION bit flags.
* @log_func: the log handler function * @log_func: the log handler function
* @user_data: data passed to the log handler * @user_data: data passed to the log handler
* *
* Sets the log handler for a domain and a set of log levels. * Sets the log handler for a domain and a set of log levels.
*
* To handle fatal and recursive messages the @log_levels parameter * To handle fatal and recursive messages the @log_levels parameter
* must be combined with the #G_LOG_FLAG_FATAL and #G_LOG_FLAG_RECURSION * must be combined with the %G_LOG_FLAG_FATAL and %G_LOG_FLAG_RECURSION
* bit flags. * bit flags.
* *
* Note that since the #G_LOG_LEVEL_ERROR log level is always fatal, if * Note that since the %G_LOG_LEVEL_ERROR log level is always fatal, if
* you want to set a handler for this log level you must combine it with * you want to set a handler for this log level you must combine it with
* #G_LOG_FLAG_FATAL. * %G_LOG_FLAG_FATAL.
* *
* This has no effect if structured logging is enabled; see * This has no effect if structured logging is enabled; see
* [Using Structured Logging][using-structured-logging]. * [Using Structured Logging][using-structured-logging].
* *
* Here is an example for adding a log handler for all warning messages * Here is an example for adding a log handler for all warning messages
* in the default domain: * in the default domain:
*
* |[<!-- language="C" --> * |[<!-- language="C" -->
* g_log_set_handler (NULL, G_LOG_LEVEL_WARNING | G_LOG_FLAG_FATAL * g_log_set_handler (NULL, G_LOG_LEVEL_WARNING | G_LOG_FLAG_FATAL
* | G_LOG_FLAG_RECURSION, my_log_handler, NULL); * | G_LOG_FLAG_RECURSION, my_log_handler, NULL);
* ]| * ]|
* *
* This example adds a log handler for all critical messages from GTK+: * This example adds a log handler for all critical messages from GTK+:
*
* |[<!-- language="C" --> * |[<!-- language="C" -->
* g_log_set_handler ("Gtk", G_LOG_LEVEL_CRITICAL | G_LOG_FLAG_FATAL * g_log_set_handler ("Gtk", G_LOG_LEVEL_CRITICAL | G_LOG_FLAG_FATAL
* | G_LOG_FLAG_RECURSION, my_log_handler, NULL); * | G_LOG_FLAG_RECURSION, my_log_handler, NULL);
* ]| * ]|
* *
* This example adds a log handler for all messages from GLib: * This example adds a log handler for all messages from GLib:
*
* |[<!-- language="C" --> * |[<!-- language="C" -->
* g_log_set_handler ("GLib", G_LOG_LEVEL_MASK | G_LOG_FLAG_FATAL * g_log_set_handler ("GLib", G_LOG_LEVEL_MASK | G_LOG_FLAG_FATAL
* | G_LOG_FLAG_RECURSION, my_log_handler, NULL); * | G_LOG_FLAG_RECURSION, my_log_handler, NULL);
@ -850,8 +854,8 @@ g_log_set_handler (const gchar *log_domain,
* application domain * application domain
* @log_levels: the log levels to apply the log handler for. * @log_levels: the log levels to apply the log handler for.
* To handle fatal and recursive messages as well, combine * To handle fatal and recursive messages as well, combine
* the log levels with the #G_LOG_FLAG_FATAL and * the log levels with the %G_LOG_FLAG_FATAL and
* #G_LOG_FLAG_RECURSION bit flags. * %G_LOG_FLAG_RECURSION bit flags.
* @log_func: the log handler function * @log_func: the log handler function
* @user_data: data passed to the log handler * @user_data: data passed to the log handler
* @destroy: destroy notify for @user_data, or %NULL * @destroy: destroy notify for @user_data, or %NULL
@ -1419,11 +1423,11 @@ g_logv (const gchar *log_domain,
/** /**
* g_log: * g_log:
* @log_domain: (nullable): the log domain, usually #G_LOG_DOMAIN, or %NULL * @log_domain: (nullable): the log domain, usually %G_LOG_DOMAIN, or %NULL
* for the default * for the default
* @log_level: the log level, either from #GLogLevelFlags * @log_level: the log level, either from #GLogLevelFlags
* or a user-defined level * or a user-defined level
* @format: the message format. See the printf() documentation * @format: the message format. See the `printf()` documentation
* @...: the parameters to insert into the format string * @...: the parameters to insert into the format string
* *
* Logs an error or debugging message. * Logs an error or debugging message.
@ -1611,10 +1615,12 @@ done_query:
* by the key "MESSAGE", followed by a printf()-style message format, * by the key "MESSAGE", followed by a printf()-style message format,
* followed by parameters to insert in the format string * followed by parameters to insert in the format string
* *
* Log a message with structured data. The message will be passed through to * Log a message with structured data.
* the log writer set by the application using g_log_set_writer_func(). If the *
* message is fatal (i.e. its log level is %G_LOG_LEVEL_ERROR), the program will * The message will be passed through to the log writer set by the application
* be aborted by calling G_BREAKPOINT() at the end of this function. If the log writer returns * using g_log_set_writer_func(). If the message is fatal (i.e. its log level
* is %G_LOG_LEVEL_ERROR), the program will be aborted by calling
* G_BREAKPOINT() at the end of this function. If the log writer returns
* %G_LOG_WRITER_UNHANDLED (failure), no other fallback writers will be tried. * %G_LOG_WRITER_UNHANDLED (failure), no other fallback writers will be tried.
* See the documentation for #GLogWriterFunc for information on chaining * See the documentation for #GLogWriterFunc for information on chaining
* writers. * writers.
@ -1648,9 +1654,10 @@ done_query:
* Note that `CODE_FILE`, `CODE_LINE` and `CODE_FUNC` are automatically set by * Note that `CODE_FILE`, `CODE_LINE` and `CODE_FUNC` are automatically set by
* the logging macros, G_DEBUG_HERE(), g_message(), g_warning(), g_critical(), * the logging macros, G_DEBUG_HERE(), g_message(), g_warning(), g_critical(),
* g_error(), etc, if the symbols `G_LOG_USE_STRUCTURED` is defined before including * g_error(), etc, if the symbols `G_LOG_USE_STRUCTURED` is defined before including
* glib.h. * `glib.h`.
* *
* For example: * For example:
*
* |[<!-- language="C" --> * |[<!-- language="C" -->
* g_log_structured (G_LOG_DOMAIN, G_LOG_LEVEL_DEBUG, * g_log_structured (G_LOG_DOMAIN, G_LOG_LEVEL_DEBUG,
* "MESSAGE_ID", "06d4df59e6c24647bfe69d2c27ef0b4e", * "MESSAGE_ID", "06d4df59e6c24647bfe69d2c27ef0b4e",
@ -1671,6 +1678,7 @@ done_query:
* interpreted as a string. * interpreted as a string.
* *
* For example: * For example:
*
* |[<!-- language="C" --> * |[<!-- language="C" -->
* const GLogField fields[] = { * const GLogField fields[] = {
* { "MESSAGE", "This is a debug message.", -1 }, * { "MESSAGE", "This is a debug message.", -1 },

1
glib/gmessages.h
View File

@ -189,6 +189,7 @@ struct _GLogField
* *
* Returns: %G_LOG_WRITER_HANDLED if the log entry was handled successfully; * Returns: %G_LOG_WRITER_HANDLED if the log entry was handled successfully;
* %G_LOG_WRITER_UNHANDLED otherwise * %G_LOG_WRITER_UNHANDLED otherwise
*
* Since: 2.50 * Since: 2.50
*/ */
typedef GLogWriterOutput (*GLogWriterFunc) (GLogLevelFlags log_level, typedef GLogWriterOutput (*GLogWriterFunc) (GLogLevelFlags log_level,

78
glib/gshell.c
View File

@ -48,9 +48,11 @@
/** /**
* G_SHELL_ERROR: * G_SHELL_ERROR:
* *
* Error domain for shell functions. Errors in this domain will be from * Error domain for shell functions.
* the #GShellError enumeration. See #GError for information on error *
* domains. * Errors in this domain will be from the #GShellError enumeration.
*
* See #GError for information on error domains.
**/ **/
/** /**
@ -191,13 +193,17 @@ unquote_string_inplace (gchar* str, gchar** end, GError** err)
* @unquoted_string: (type filename): a literal string * @unquoted_string: (type filename): a literal string
* *
* Quotes a string so that the shell (/bin/sh) will interpret the * Quotes a string so that the shell (/bin/sh) will interpret the
* quoted string to mean @unquoted_string. If you pass a filename to * quoted string to mean @unquoted_string.
* the shell, for example, you should first quote it with this *
* function. The return value must be freed with g_free(). The * If you pass a filename to the shell, for example, you should first
* quoting style used is undefined (single or double quotes may be * quote it with this function.
*
* The return value must be freed with g_free().
*
* The quoting style used is undefined (single or double quotes may be
* used). * used).
* *
* Returns: (type filename): quoted string * Returns: (type filename) (transfer full): quoted string
**/ **/
gchar* gchar*
g_shell_quote (const gchar *unquoted_string) g_shell_quote (const gchar *unquoted_string)
@ -241,27 +247,33 @@ g_shell_quote (const gchar *unquoted_string)
* @quoted_string: (type filename): shell-quoted string * @quoted_string: (type filename): shell-quoted string
* @error: error return location or NULL * @error: error return location or NULL
* *
* Unquotes a string as the shell (/bin/sh) would. Only handles * Unquotes a string as the shell (/bin/sh) would.
* quotes; if a string contains file globs, arithmetic operators, *
* variables, backticks, redirections, or other special-to-the-shell * This function only handles quotes; if a string contains file globs,
* features, the result will be different from the result a real shell * arithmetic operators, variables, backticks, redirections, or other
* would produce (the variables, backticks, etc. will be passed * special-to-the-shell features, the result will be different from the
* through literally instead of being expanded). This function is * result a real shell would produce (the variables, backticks, etc.
* guaranteed to succeed if applied to the result of * will be passed through literally instead of being expanded).
*
* This function is guaranteed to succeed if applied to the result of
* g_shell_quote(). If it fails, it returns %NULL and sets the * g_shell_quote(). If it fails, it returns %NULL and sets the
* error. The @quoted_string need not actually contain quoted or * error.
* escaped text; g_shell_unquote() simply goes through the string and *
* unquotes/unescapes anything that the shell would. Both single and * The @quoted_string need not actually contain quoted or escaped text;
* double quotes are handled, as are escapes including escaped * g_shell_unquote() simply goes through the string and unquotes/unescapes
* newlines. The return value must be freed with g_free(). Possible * anything that the shell would. Both single and double quotes are
* errors are in the #G_SHELL_ERROR domain. * handled, as are escapes including escaped newlines.
*
* The return value must be freed with g_free().
*
* Possible errors are in the %G_SHELL_ERROR domain.
* *
* Shell quoting rules are a bit strange. Single quotes preserve the * Shell quoting rules are a bit strange. Single quotes preserve the
* literal string exactly. escape sequences are not allowed; not even * literal string exactly. escape sequences are not allowed; not even
* \' - if you want a ' in the quoted text, you have to do something * `\'` - if you want a `'` in the quoted text, you have to do something
* like 'foo'\''bar'. Double quotes allow $, `, ", \, and newline to * like `'foo'\''bar'`. Double quotes allow `$`, ```, `"`, `\`, and
* be escaped with backslash. Otherwise double quotes preserve things * newline to be escaped with backslash. Otherwise double quotes
* literally. * preserve things literally.
* *
* Returns: (type filename): an unquoted string * Returns: (type filename): an unquoted string
**/ **/
@ -625,12 +637,16 @@ tokenize_command_line (const gchar *command_line,
* Parses a command line into an argument vector, in much the same way * Parses a command line into an argument vector, in much the same way
* the shell would, but without many of the expansions the shell would * the shell would, but without many of the expansions the shell would
* perform (variable expansion, globs, operators, filename expansion, * perform (variable expansion, globs, operators, filename expansion,
* etc. are not supported). The results are defined to be the same as * etc. are not supported).
* those you would get from a UNIX98 /bin/sh, as long as the input *
* contains none of the unsupported shell expansions. If the input * The results are defined to be the same as those you would get from
* does contain such expansions, they are passed through * a UNIX98 `/bin/sh`, as long as the input contains none of the
* literally. Possible errors are those from the #G_SHELL_ERROR * unsupported shell expansions. If the input does contain such expansions,
* domain. Free the returned vector with g_strfreev(). * they are passed through literally.
*
* Possible errors are those from the %G_SHELL_ERROR domain.
*
* Free the returned vector with g_strfreev().
* *
* Returns: %TRUE on success, %FALSE if error set * Returns: %TRUE on success, %FALSE if error set
**/ **/

15
glib/gslice.c
View File

@ -998,6 +998,7 @@ thread_memory_magazine2_free (ThreadMemory *tmem,
* @next: the field name of the next pointer in @type * @next: the field name of the next pointer in @type
* *
* Frees a linked list of memory blocks of structure type @type. * Frees a linked list of memory blocks of structure type @type.
*
* The memory blocks must be equal-sized, allocated via * The memory blocks must be equal-sized, allocated via
* g_slice_alloc() or g_slice_alloc0() and linked together by * g_slice_alloc() or g_slice_alloc0() and linked together by
* a @next pointer (similar to #GSList). The name of the * a @next pointer (similar to #GSList). The name of the
@ -1016,17 +1017,19 @@ thread_memory_magazine2_free (ThreadMemory *tmem,
* @block_size: the number of bytes to allocate * @block_size: the number of bytes to allocate
* *
* Allocates a block of memory from the slice allocator. * Allocates a block of memory from the slice allocator.
*
* The block address handed out can be expected to be aligned * The block address handed out can be expected to be aligned
* to at least 1 * sizeof (void*), * to at least `1 * sizeof (void*)`, though in general slices
* though in general slices are 2 * sizeof (void*) bytes aligned, * are `2 * sizeof (void*)` bytes aligned; if a `malloc()`
* if a malloc() fallback implementation is used instead, * fallback implementation is used instead, the alignment may
* the alignment may be reduced in a libc dependent fashion. * be reduced in a libc dependent fashion.
*
* Note that the underlying slice allocation mechanism can * Note that the underlying slice allocation mechanism can
* be changed with the [`G_SLICE=always-malloc`][G_SLICE] * be changed with the [`G_SLICE=always-malloc`][G_SLICE]
* environment variable. * environment variable.
* *
* Returns: a pointer to the allocated memory block, which will be %NULL if and * Returns: a pointer to the allocated memory block, which will
* only if @mem_size is 0 * be %NULL if and only if @mem_size is 0
* *
* Since: 2.10 * Since: 2.10
*/ */

106
glib/gspawn.c
View File

@ -210,13 +210,15 @@ G_DEFINE_QUARK (g-spawn-exit-error-quark, g_spawn_exit_error)
* @child_pid: (out) (optional): return location for child process reference, or %NULL * @child_pid: (out) (optional): return location for child process reference, or %NULL
* @error: return location for error * @error: return location for error
* *
* Executes a child program asynchronously.
*
* See g_spawn_async_with_pipes() for a full description; this function * See g_spawn_async_with_pipes() for a full description; this function
* simply calls the g_spawn_async_with_pipes() without any pipes. * simply calls the g_spawn_async_with_pipes() without any pipes.
* *
* You should call g_spawn_close_pid() on the returned child process * You should call g_spawn_close_pid() on the returned child process
* reference when you don't need it any more. * reference when you don't need it any more.
* *
* If you are writing a GTK+ application, and the program you are spawning is a * If you are writing a GTK application, and the program you are spawning is a
* graphical application too, then to ensure that the spawned program opens its * graphical application too, then to ensure that the spawned program opens its
* windows on the right screen, you may want to use #GdkAppLaunchContext, * windows on the right screen, you may want to use #GdkAppLaunchContext,
* #GAppLaunchContext, or set the %DISPLAY environment variable. * #GAppLaunchContext, or set the %DISPLAY environment variable.
@ -329,6 +331,7 @@ read_data (GString *str,
* @error: return location for error, or %NULL * @error: return location for error, or %NULL
* *
* Executes a child synchronously (waits for the child to exit before returning). * Executes a child synchronously (waits for the child to exit before returning).
*
* All output from the child is stored in @standard_output and @standard_error, * All output from the child is stored in @standard_output and @standard_error,
* if those parameters are non-%NULL. Note that you must set the * if those parameters are non-%NULL. Note that you must set the
* %G_SPAWN_STDOUT_TO_DEV_NULL and %G_SPAWN_STDERR_TO_DEV_NULL flags when * %G_SPAWN_STDOUT_TO_DEV_NULL and %G_SPAWN_STDERR_TO_DEV_NULL flags when
@ -665,52 +668,53 @@ g_spawn_async_with_pipes (const gchar *working_directory,
* @error: return location for error * @error: return location for error
* *
* Executes a child program asynchronously (your program will not * Executes a child program asynchronously (your program will not
* block waiting for the child to exit). The child program is * block waiting for the child to exit).
* specified by the only argument that must be provided, @argv.
* @argv should be a %NULL-terminated array of strings, to be passed
* as the argument vector for the child. The first string in @argv
* is of course the name of the program to execute. By default, the
* name of the program must be a full path. If @flags contains the
* %G_SPAWN_SEARCH_PATH flag, the `PATH` environment variable is
* used to search for the executable. If @flags contains the
* %G_SPAWN_SEARCH_PATH_FROM_ENVP flag, the `PATH` variable from
* @envp is used to search for the executable. If both the
* %G_SPAWN_SEARCH_PATH and %G_SPAWN_SEARCH_PATH_FROM_ENVP flags
* are set, the `PATH` variable from @envp takes precedence over
* the environment variable.
* *
* If the program name is not a full path and %G_SPAWN_SEARCH_PATH flag is not * The child program is specified by the only argument that must be
* used, then the program will be run from the current directory (or * provided, @argv. @argv should be a %NULL-terminated array of strings,
* @working_directory, if specified); this might be unexpected or even * to be passed as the argument vector for the child. The first string
* in @argv is of course the name of the program to execute. By default,
* the name of the program must be a full path. If @flags contains the
* %G_SPAWN_SEARCH_PATH flag, the `PATH` environment variable is used to
* search for the executable. If @flags contains the
* %G_SPAWN_SEARCH_PATH_FROM_ENVP flag, the `PATH` variable from @envp
* is used to search for the executable. If both the
* %G_SPAWN_SEARCH_PATH and %G_SPAWN_SEARCH_PATH_FROM_ENVP flags are
* set, the `PATH` variable from @envp takes precedence over the
* environment variable.
*
* If the program name is not a full path and %G_SPAWN_SEARCH_PATH flag
* is not used, then the program will be run from the current directory
* (or @working_directory, if specified); this might be unexpected or even
* dangerous in some cases when the current directory is world-writable. * dangerous in some cases when the current directory is world-writable.
* *
* On Windows, note that all the string or string vector arguments to * On Windows, note that all the string or string vector arguments to
* this function and the other g_spawn*() functions are in UTF-8, the * this function and the other `g_spawn*()` functions are in UTF-8, the
* GLib file name encoding. Unicode characters that are not part of * GLib file name encoding. Unicode characters that are not part of
* the system codepage passed in these arguments will be correctly * the system codepage passed in these arguments will be correctly
* available in the spawned program only if it uses wide character API * available in the spawned program only if it uses wide character API
* to retrieve its command line. For C programs built with Microsoft's * to retrieve its command line. For C programs built with Microsoft's
* tools it is enough to make the program have a wmain() instead of * tools it is enough to make the program have a `wmain()` instead of
* main(). wmain() has a wide character argument vector as parameter. * `main()`. `wmain()` has a wide character argument vector as parameter.
* *
* At least currently, mingw doesn't support wmain(), so if you use * At least currently, mingw doesn't support `wmain()`, so if you use
* mingw to develop the spawned program, it should call * mingw to develop the spawned program, it should call
* g_win32_get_command_line() to get arguments in UTF-8. * g_win32_get_command_line() to get arguments in UTF-8.
* *
* On Windows the low-level child process creation API CreateProcess() * On Windows the low-level child process creation API `CreateProcess()`
* doesn't use argument vectors, but a command line. The C runtime * doesn't use argument vectors, but a command line. The C runtime
* library's spawn*() family of functions (which g_spawn_async_with_pipes() * library's `spawn*()` family of functions (which g_spawn_async_with_pipes()
* eventually calls) paste the argument vector elements together into * eventually calls) paste the argument vector elements together into
* a command line, and the C runtime startup code does a corresponding * a command line, and the C runtime startup code does a corresponding
* reconstruction of an argument vector from the command line, to be * reconstruction of an argument vector from the command line, to be
* passed to main(). Complications arise when you have argument vector * passed to `main()`. Complications arise when you have argument vector
* elements that contain spaces or double quotes. The `spawn*()` functions * elements that contain spaces or double quotes. The `spawn*()` functions
* don't do any quoting or escaping, but on the other hand the startup * don't do any quoting or escaping, but on the other hand the startup
* code does do unquoting and unescaping in order to enable receiving * code does do unquoting and unescaping in order to enable receiving
* arguments with embedded spaces or double quotes. To work around this * arguments with embedded spaces or double quotes. To work around this
* asymmetry, g_spawn_async_with_pipes() will do quoting and escaping on * asymmetry, g_spawn_async_with_pipes() will do quoting and escaping on
* argument vector elements that need it before calling the C runtime * argument vector elements that need it before calling the C runtime
* spawn() function. * `spawn()` function.
* *
* The returned @child_pid on Windows is a handle to the child * The returned @child_pid on Windows is a handle to the child
* process, not its identifier. Process handles and process * process, not its identifier. Process handles and process
@ -729,13 +733,13 @@ g_spawn_async_with_pipes (const gchar *working_directory,
* free resources which may be associated with the child process. (On Unix, * free resources which may be associated with the child process. (On Unix,
* using a child watch is equivalent to calling waitpid() or handling * using a child watch is equivalent to calling waitpid() or handling
* the `SIGCHLD` signal manually. On Windows, calling g_spawn_close_pid() * the `SIGCHLD` signal manually. On Windows, calling g_spawn_close_pid()
* is equivalent to calling CloseHandle() on the process handle returned * is equivalent to calling `CloseHandle()` on the process handle returned
* in @child_pid). See g_child_watch_add(). * in @child_pid). See g_child_watch_add().
* *
* Open UNIX file descriptors marked as `FD_CLOEXEC` will be automatically * Open UNIX file descriptors marked as `FD_CLOEXEC` will be automatically
* closed in the child process. %G_SPAWN_LEAVE_DESCRIPTORS_OPEN means that * closed in the child process. %G_SPAWN_LEAVE_DESCRIPTORS_OPEN means that
* other open file descriptors will be inherited by the child; otherwise all * other open file descriptors will be inherited by the child; otherwise all
* descriptors except stdin/stdout/stderr will be closed before calling exec() * descriptors except stdin/stdout/stderr will be closed before calling `exec()`
* in the child. %G_SPAWN_SEARCH_PATH means that @argv[0] need not be an * in the child. %G_SPAWN_SEARCH_PATH means that @argv[0] need not be an
* absolute path, it will be looked for in the `PATH` environment * absolute path, it will be looked for in the `PATH` environment
* variable. %G_SPAWN_SEARCH_PATH_FROM_ENVP means need not be an * variable. %G_SPAWN_SEARCH_PATH_FROM_ENVP means need not be an
@ -776,25 +780,25 @@ g_spawn_async_with_pipes (const gchar *working_directory,
* @child_setup and @user_data are a function and user data. On POSIX * @child_setup and @user_data are a function and user data. On POSIX
* platforms, the function is called in the child after GLib has * platforms, the function is called in the child after GLib has
* performed all the setup it plans to perform (including creating * performed all the setup it plans to perform (including creating
* pipes, closing file descriptors, etc.) but before calling exec(). * pipes, closing file descriptors, etc.) but before calling `exec()`.
* That is, @child_setup is called just before calling exec() in the * That is, @child_setup is called just before calling `exec()` in the
* child. Obviously actions taken in this function will only affect * child. Obviously actions taken in this function will only affect
* the child, not the parent. * the child, not the parent.
* *
* On Windows, there is no separate fork() and exec() functionality. * On Windows, there is no separate `fork()` and `exec()` functionality.
* Child processes are created and run with a single API call, * Child processes are created and run with a single API call,
* CreateProcess(). There is no sensible thing @child_setup * `CreateProcess()`. There is no sensible thing @child_setup
* could be used for on Windows so it is ignored and not called. * could be used for on Windows so it is ignored and not called.
* *
* If non-%NULL, @child_pid will on Unix be filled with the child's * If non-%NULL, @child_pid will on Unix be filled with the child's
* process ID. You can use the process ID to send signals to the child, * process ID. You can use the process ID to send signals to the child,
* or to use g_child_watch_add() (or waitpid()) if you specified the * or to use g_child_watch_add() (or `waitpid()`) if you specified the
* %G_SPAWN_DO_NOT_REAP_CHILD flag. On Windows, @child_pid will be * %G_SPAWN_DO_NOT_REAP_CHILD flag. On Windows, @child_pid will be
* filled with a handle to the child process only if you specified the * filled with a handle to the child process only if you specified the
* %G_SPAWN_DO_NOT_REAP_CHILD flag. You can then access the child * %G_SPAWN_DO_NOT_REAP_CHILD flag. You can then access the child
* process using the Win32 API, for example wait for its termination * process using the Win32 API, for example wait for its termination
* with the WaitFor*() functions, or examine its exit code with * with the `WaitFor*()` functions, or examine its exit code with
* GetExitCodeProcess(). You should close the handle with CloseHandle() * `GetExitCodeProcess()`. You should close the handle with `CloseHandle()`
* or g_spawn_close_pid() when you no longer need it. * or g_spawn_close_pid() when you no longer need it.
* *
* If non-%NULL, the @stdin_pipe_out, @stdout_pipe_out, @stderr_pipe_out * If non-%NULL, the @stdin_pipe_out, @stdout_pipe_out, @stderr_pipe_out
@ -818,7 +822,7 @@ g_spawn_async_with_pipes (const gchar *working_directory,
* @error can be %NULL to ignore errors, or non-%NULL to report errors. * @error can be %NULL to ignore errors, or non-%NULL to report errors.
* If an error is set, the function returns %FALSE. Errors are reported * If an error is set, the function returns %FALSE. Errors are reported
* even if they occur in the child (for example if the executable in * even if they occur in the child (for example if the executable in
* @argv[0] is not found). Typically the `message` field of returned * `@argv[0]` is not found). Typically the `message` field of returned
* errors should be displayed to users. Possible errors are those from * errors should be displayed to users. Possible errors are those from
* the #G_SPAWN_ERROR domain. * the #G_SPAWN_ERROR domain.
* *
@ -829,7 +833,7 @@ g_spawn_async_with_pipes (const gchar *working_directory,
* process reference must be closed using g_spawn_close_pid(). * process reference must be closed using g_spawn_close_pid().
* *
* On modern UNIX platforms, GLib can use an efficient process launching * On modern UNIX platforms, GLib can use an efficient process launching
* codepath driven internally by posix_spawn(). This has the advantage of * codepath driven internally by `posix_spawn()`. This has the advantage of
* avoiding the fork-time performance costs of cloning the parent process * avoiding the fork-time performance costs of cloning the parent process
* address space, and avoiding associated memory overcommit checks that are * address space, and avoiding associated memory overcommit checks that are
* not relevant in the context of immediately executing a distinct process. * not relevant in the context of immediately executing a distinct process.
@ -841,9 +845,11 @@ g_spawn_async_with_pipes (const gchar *working_directory,
* 3. %G_SPAWN_SEARCH_PATH_FROM_ENVP is not set * 3. %G_SPAWN_SEARCH_PATH_FROM_ENVP is not set
* 4. @working_directory is %NULL * 4. @working_directory is %NULL
* 5. @child_setup is %NULL * 5. @child_setup is %NULL
* 6. The program is of a recognised binary format, or has a shebang. Otherwise, GLib will have to execute the program through the shell, which is not done using the optimized codepath. * 6. The program is of a recognised binary format, or has a shebang.
* Otherwise, GLib will have to execute the program through the
* shell, which is not done using the optimized codepath.
* *
* If you are writing a GTK+ application, and the program you are spawning is a * If you are writing a GTK application, and the program you are spawning is a
* graphical application too, then to ensure that the spawned program opens its * graphical application too, then to ensure that the spawned program opens its
* windows on the right screen, you may want to use #GdkAppLaunchContext, * windows on the right screen, you may want to use #GdkAppLaunchContext,
* #GAppLaunchContext, or set the `DISPLAY` environment variable. * #GAppLaunchContext, or set the `DISPLAY` environment variable.
@ -925,6 +931,8 @@ g_spawn_async_with_pipes_and_fds (const gchar *working_directory,
* @stderr_fd: file descriptor to use for child's stderr, or `-1` * @stderr_fd: file descriptor to use for child's stderr, or `-1`
* @error: return location for error * @error: return location for error
* *
* Executes a child program asynchronously.
*
* Identical to g_spawn_async_with_pipes_and_fds() but with `n_fds` set to zero, * Identical to g_spawn_async_with_pipes_and_fds() but with `n_fds` set to zero,
* so no FD assignments are used. * so no FD assignments are used.
* *
@ -986,12 +994,17 @@ g_spawn_async_with_fds (const gchar *working_directory,
* @error: return location for errors * @error: return location for errors
* *
* A simple version of g_spawn_sync() with little-used parameters * A simple version of g_spawn_sync() with little-used parameters
* removed, taking a command line instead of an argument vector. See * removed, taking a command line instead of an argument vector.
* g_spawn_sync() for full details. @command_line will be parsed by *
* g_shell_parse_argv(). Unlike g_spawn_sync(), the %G_SPAWN_SEARCH_PATH flag * See g_spawn_sync() for full details.
* is enabled. Note that %G_SPAWN_SEARCH_PATH can have security *
* implications, so consider using g_spawn_sync() directly if * The @command_line argument will be parsed by g_shell_parse_argv().
* appropriate. Possible errors are those from g_spawn_sync() and those *
* Unlike g_spawn_sync(), the %G_SPAWN_SEARCH_PATH flag is enabled.
* Note that %G_SPAWN_SEARCH_PATH can have security implications, so
* consider using g_spawn_sync() directly if appropriate.
*
* Possible errors are those from g_spawn_sync() and those
* from g_shell_parse_argv(). * from g_shell_parse_argv().
* *
* If @wait_status is non-%NULL, the platform-specific status of * If @wait_status is non-%NULL, the platform-specific status of
@ -1050,8 +1063,9 @@ g_spawn_command_line_sync (const gchar *command_line,
* @error: return location for errors * @error: return location for errors
* *
* A simple version of g_spawn_async() that parses a command line with * A simple version of g_spawn_async() that parses a command line with
* g_shell_parse_argv() and passes it to g_spawn_async(). Runs a * g_shell_parse_argv() and passes it to g_spawn_async().
* command line in the background. Unlike g_spawn_async(), the *
* Runs a command line in the background. Unlike g_spawn_async(), the
* %G_SPAWN_SEARCH_PATH flag is enabled, other flags are not. Note * %G_SPAWN_SEARCH_PATH flag is enabled, other flags are not. Note
* that %G_SPAWN_SEARCH_PATH can have security implications, so * that %G_SPAWN_SEARCH_PATH can have security implications, so
* consider using g_spawn_async() directly if appropriate. Possible * consider using g_spawn_async() directly if appropriate. Possible

25
glib/gstrfuncs.c
View File

@ -2028,22 +2028,26 @@ g_strncasecmp (const gchar *s1,
* @new_delimiter: the new delimiter character * @new_delimiter: the new delimiter character
* *
* Converts any delimiter characters in @string to @new_delimiter. * Converts any delimiter characters in @string to @new_delimiter.
*
* Any characters in @string which are found in @delimiters are * Any characters in @string which are found in @delimiters are
* changed to the @new_delimiter character. Modifies @string in place, * changed to the @new_delimiter character. Modifies @string in place,
* and returns @string itself, not a copy. The return value is to * and returns @string itself, not a copy.
* allow nesting such as *
* The return value is to allow nesting such as:
*
* |[<!-- language="C" --> * |[<!-- language="C" -->
* g_ascii_strup (g_strdelimit (str, "abc", '?')) * g_ascii_strup (g_strdelimit (str, "abc", '?'))
* ]| * ]|
* *
* In order to modify a copy, you may use `g_strdup()`: * In order to modify a copy, you may use g_strdup():
*
* |[<!-- language="C" --> * |[<!-- language="C" -->
* reformatted = g_strdelimit (g_strdup (const_str), "abc", '?'); * reformatted = g_strdelimit (g_strdup (const_str), "abc", '?');
* ... * ...
* g_free (reformatted); * g_free (reformatted);
* ]| * ]|
* *
* Returns: @string * Returns: the modified @string
*/ */
gchar * gchar *
g_strdelimit (gchar *string, g_strdelimit (gchar *string,
@ -2073,21 +2077,24 @@ g_strdelimit (gchar *string,
* @substitutor: replacement character for disallowed bytes * @substitutor: replacement character for disallowed bytes
* *
* For each character in @string, if the character is not in @valid_chars, * For each character in @string, if the character is not in @valid_chars,
* replaces the character with @substitutor. Modifies @string in place, * replaces the character with @substitutor.
* and return @string itself, not a copy. The return value is to allow *
* nesting such as * Modifies @string in place, and return @string itself, not a copy. The
* return value is to allow nesting such as:
*
* |[<!-- language="C" --> * |[<!-- language="C" -->
* g_ascii_strup (g_strcanon (str, "abc", '?')) * g_ascii_strup (g_strcanon (str, "abc", '?'))
* ]| * ]|
* *
* In order to modify a copy, you may use `g_strdup()`: * In order to modify a copy, you may use g_strdup():
*
* |[<!-- language="C" --> * |[<!-- language="C" -->
* reformatted = g_strcanon (g_strdup (const_str), "abc", '?'); * reformatted = g_strcanon (g_strdup (const_str), "abc", '?');
* ... * ...
* g_free (reformatted); * g_free (reformatted);
* ]| * ]|
* *
* Returns: @string * Returns: the modified @string
*/ */
gchar * gchar *
g_strcanon (gchar *string, g_strcanon (gchar *string,

19
glib/gthread.c
View File

@ -164,16 +164,17 @@
* G_LOCK_DEFINE: * G_LOCK_DEFINE:
* @name: the name of the lock * @name: the name of the lock
* *
* The #G_LOCK_ macros provide a convenient interface to #GMutex. * The `G_LOCK_` macros provide a convenient interface to #GMutex.
* #G_LOCK_DEFINE defines a lock. It can appear in any place where * %G_LOCK_DEFINE defines a lock. It can appear in any place where
* variable definitions may appear in programs, i.e. in the first block * variable definitions may appear in programs, i.e. in the first block
* of a function or outside of functions. The @name parameter will be * of a function or outside of functions. The @name parameter will be
* mangled to get the name of the #GMutex. This means that you * mangled to get the name of the #GMutex. This means that you
* can use names of existing variables as the parameter - e.g. the name * can use names of existing variables as the parameter - e.g. the name
* of the variable you intend to protect with the lock. Look at our * of the variable you intend to protect with the lock. Look at our
* give_me_next_number() example using the #G_LOCK macros: * give_me_next_number() example using the `G_LOCK` macros:
*
* Here is an example for using the `G_LOCK` convenience macros:
* *
* Here is an example for using the #G_LOCK convenience macros:
* |[<!-- language="C" --> * |[<!-- language="C" -->
* G_LOCK_DEFINE (current_number); * G_LOCK_DEFINE (current_number);
* *
@ -196,14 +197,14 @@
* G_LOCK_DEFINE_STATIC: * G_LOCK_DEFINE_STATIC:
* @name: the name of the lock * @name: the name of the lock
* *
* This works like #G_LOCK_DEFINE, but it creates a static object. * This works like %G_LOCK_DEFINE, but it creates a static object.
*/ */
/** /**
* G_LOCK_EXTERN: * G_LOCK_EXTERN:
* @name: the name of the lock * @name: the name of the lock
* *
* This declares a lock, that is defined with #G_LOCK_DEFINE in another * This declares a lock, that is defined with %G_LOCK_DEFINE in another
* module. * module.
*/ */
@ -212,7 +213,7 @@
* @name: the name of the lock * @name: the name of the lock
* *
* Works like g_mutex_lock(), but for a lock defined with * Works like g_mutex_lock(), but for a lock defined with
* #G_LOCK_DEFINE. * %G_LOCK_DEFINE.
*/ */
/** /**
@ -220,7 +221,7 @@
* @name: the name of the lock * @name: the name of the lock
* *
* Works like g_mutex_trylock(), but for a lock defined with * Works like g_mutex_trylock(), but for a lock defined with
* #G_LOCK_DEFINE. * %G_LOCK_DEFINE.
* *
* Returns: %TRUE, if the lock could be locked. * Returns: %TRUE, if the lock could be locked.
*/ */
@ -230,7 +231,7 @@
* @name: the name of the lock * @name: the name of the lock
* *
* Works like g_mutex_unlock(), but for a lock defined with * Works like g_mutex_unlock(), but for a lock defined with
* #G_LOCK_DEFINE. * %G_LOCK_DEFINE.
*/ */
/* GMutex Documentation {{{1 ------------------------------------------ */ /* GMutex Documentation {{{1 ------------------------------------------ */

13
glib/gunicode.h
View File

@ -760,10 +760,15 @@ GLIB_VAR const gchar * const g_utf8_skip;
* g_utf8_next_char: * g_utf8_next_char:
* @p: Pointer to the start of a valid UTF-8 character * @p: Pointer to the start of a valid UTF-8 character
* *
* Skips to the next character in a UTF-8 string. The string must be * Skips to the next character in a UTF-8 string.
* valid; this macro is as fast as possible, and has no error-checking. *
* You would use this macro to iterate over a string character by * The string must be valid; this macro is as fast as possible, and has
* character. The macro returns the start of the next UTF-8 character. * no error-checking.
*
* You would use this macro to iterate over a string character by character.
*
* The macro returns the start of the next UTF-8 character.
*
* Before using this macro, use g_utf8_validate() to validate strings * Before using this macro, use g_utf8_validate() to validate strings
* that may contain invalid UTF-8. * that may contain invalid UTF-8.
*/ */

9
glib/gvariant.h
View File

@ -345,7 +345,9 @@ GQuark g_variant_parse_error_quark (void);
* A stack-allocated #GVariantBuilder must be initialized if it is * A stack-allocated #GVariantBuilder must be initialized if it is
* used together with g_auto() to avoid warnings or crashes if * used together with g_auto() to avoid warnings or crashes if
* function returns before g_variant_builder_init() is called on the * function returns before g_variant_builder_init() is called on the
* builder. This macro can be used as initializer instead of an * builder.
*
* This macro can be used as initializer instead of an
* explicit zeroing a variable when declaring it and a following * explicit zeroing a variable when declaring it and a following
* g_variant_builder_init(), but it cannot be assigned to a variable. * g_variant_builder_init(), but it cannot be assigned to a variable.
* *
@ -354,7 +356,7 @@ GQuark g_variant_parse_error_quark (void);
* the G_VARIANT_BUILDER_INIT() call, but rather in functions that * the G_VARIANT_BUILDER_INIT() call, but rather in functions that
* make sure that #GVariantBuilder is valid. * make sure that #GVariantBuilder is valid.
* *
* |[ * |[<!-- language="C" -->
* g_auto(GVariantBuilder) builder = G_VARIANT_BUILDER_INIT (G_VARIANT_TYPE_BYTESTRING); * g_auto(GVariantBuilder) builder = G_VARIANT_BUILDER_INIT (G_VARIANT_TYPE_BYTESTRING);
* ]| * ]|
* *
@ -455,6 +457,7 @@ struct _GVariantDict {
* A stack-allocated #GVariantDict must be initialized if it is used * A stack-allocated #GVariantDict must be initialized if it is used
* together with g_auto() to avoid warnings or crashes if function * together with g_auto() to avoid warnings or crashes if function
* returns before g_variant_dict_init() is called on the builder. * returns before g_variant_dict_init() is called on the builder.
*
* This macro can be used as initializer instead of an explicit * This macro can be used as initializer instead of an explicit
* zeroing a variable when declaring it and a following * zeroing a variable when declaring it and a following
* g_variant_dict_init(), but it cannot be assigned to a variable. * g_variant_dict_init(), but it cannot be assigned to a variable.
@ -468,7 +471,7 @@ struct _GVariantDict {
* safely with a different @asv right after the variable was * safely with a different @asv right after the variable was
* initialized with G_VARIANT_DICT_INIT(). * initialized with G_VARIANT_DICT_INIT().
* *
* |[ * |[<!-- language="C" -->
* g_autoptr(GVariant) variant = get_asv_variant (); * g_autoptr(GVariant) variant = get_asv_variant ();
* g_auto(GVariantDict) dict = G_VARIANT_DICT_INIT (variant); * g_auto(GVariantDict) dict = G_VARIANT_DICT_INIT (variant);
* ]| * ]|

25
glib/gversion.c
View File

@ -151,24 +151,25 @@ const guint glib_binary_age = GLIB_BINARY_AGE;
* @required_micro: the required micro version * @required_micro: the required micro version
* *
* Checks that the GLib library in use is compatible with the * Checks that the GLib library in use is compatible with the
* given version. Generally you would pass in the constants * given version.
* #GLIB_MAJOR_VERSION, #GLIB_MINOR_VERSION, #GLIB_MICRO_VERSION *
* as the three arguments to this function; that produces * Generally you would pass in the constants %GLIB_MAJOR_VERSION,
* a check that the library in use is compatible with * %GLIB_MINOR_VERSION, %GLIB_MICRO_VERSION as the three arguments
* the version of GLib the application or module was compiled * to this function; that produces a check that the library in use
* against. * is compatible with the version of GLib the application or module
* was compiled against.
* *
* Compatibility is defined by two things: first the version * Compatibility is defined by two things: first the version
* of the running library is newer than the version * of the running library is newer than the version
* @required_major.required_minor.@required_micro. Second * `@required_major.required_minor.@required_micro`. Second
* the running library must be binary compatible with the * the running library must be binary compatible with the
* version @required_major.required_minor.@required_micro * version `@required_major.@required_minor.@required_micro`
* (same major version.) * (same major version.)
* *
* Returns: %NULL if the GLib library is compatible with the * Returns: (transfer none) (nullable): %NULL if the GLib library is
* given version, or a string describing the version mismatch. * compatible with the given version, or a string describing the
* The returned string is owned by GLib and must not be modified * version mismatch. The returned string is owned by GLib and must
* or freed. * not be modified or freed.
* *
* Since: 2.6 * Since: 2.6
*/ */

13
gobject/gbinding.c
View File

@ -25,9 +25,10 @@
* *
* #GBinding is the representation of a binding between a property on a * #GBinding is the representation of a binding between a property on a
* #GObject instance (or source) and another property on another #GObject * #GObject instance (or source) and another property on another #GObject
* instance (or target). Whenever the source property changes, the same * instance (or target).
* value is applied to the target property; for instance, the following *
* binding: * Whenever the source property changes, the same value is applied to the
* target property; for instance, the following binding:
* *
* |[<!-- language="C" --> * |[<!-- language="C" -->
* g_object_bind_property (object1, "property-a", * g_object_bind_property (object1, "property-a",
@ -1409,10 +1410,12 @@ g_object_bind_property_full (gpointer source,
* @flags: flags to pass to #GBinding * @flags: flags to pass to #GBinding
* *
* Creates a binding between @source_property on @source and @target_property * Creates a binding between @source_property on @source and @target_property
* on @target. Whenever the @source_property is changed the @target_property is * on @target.
*
* Whenever the @source_property is changed the @target_property is
* updated using the same value. For instance: * updated using the same value. For instance:
* *
* |[ * |[<!-- language="C" -->
* g_object_bind_property (action, "active", widget, "sensitive", 0); * g_object_bind_property (action, "active", widget, "sensitive", 0);
* ]| * ]|
* *

5
gobject/gbinding.h
View File

@ -53,8 +53,9 @@ typedef struct _GBinding GBinding;
* @to_value: the #GValue in which to store the transformed value * @to_value: the #GValue in which to store the transformed value
* @user_data: data passed to the transform function * @user_data: data passed to the transform function
* *
* A function to be called to transform @from_value to @to_value. If * A function to be called to transform @from_value to @to_value.
* this is the @transform_to function of a binding, then @from_value *
* If this is the @transform_to function of a binding, then @from_value
* is the @source_property on the @source object, and @to_value is the * is the @source_property on the @source object, and @to_value is the
* @target_property on the @target object. If this is the * @target_property on the @target object. If this is the
* @transform_from function of a %G_BINDING_BIDIRECTIONAL binding, * @transform_from function of a %G_BINDING_BIDIRECTIONAL binding,

16
gobject/gboxed.c
View File

@ -39,10 +39,11 @@
* @see_also: #GParamSpecBoxed, g_param_spec_boxed() * @see_also: #GParamSpecBoxed, g_param_spec_boxed()
* @title: Boxed Types * @title: Boxed Types
* *
* #GBoxed is a generic wrapper mechanism for arbitrary C structures. The only * #GBoxed is a generic wrapper mechanism for arbitrary C structures.
* thing the type system needs to know about the structures is how to copy them *
* (a #GBoxedCopyFunc) and how to free them (a #GBoxedFreeFunc) — beyond that * The only thing the type system needs to know about the structures is how to
* they are treated as opaque chunks of memory. * copy them (a #GBoxedCopyFunc) and how to free them (a #GBoxedFreeFunc);
* beyond that, they are treated as opaque chunks of memory.
* *
* Boxed types are useful for simple value-holder structures like rectangles or * Boxed types are useful for simple value-holder structures like rectangles or
* points. They can also be used for wrapping structures defined in non-#GObject * points. They can also be used for wrapping structures defined in non-#GObject
@ -280,8 +281,10 @@ boxed_proxy_lcopy_value (const GValue *value,
* @boxed_free: Boxed structure free function. * @boxed_free: Boxed structure free function.
* *
* This function creates a new %G_TYPE_BOXED derived type id for a new * This function creates a new %G_TYPE_BOXED derived type id for a new
* boxed type with name @name. Boxed type handling functions have to be * boxed type with name @name.
* provided to copy and free opaque boxed structures of this type. *
* Boxed type handling functions have to be provided to copy and free
* opaque boxed structures of this type.
* *
* For the general case, it is recommended to use #G_DEFINE_BOXED_TYPE * For the general case, it is recommended to use #G_DEFINE_BOXED_TYPE
* instead of calling g_boxed_type_register_static() directly. The macro * instead of calling g_boxed_type_register_static() directly. The macro
@ -510,6 +513,7 @@ g_value_set_boxed (GValue *value,
* @v_boxed: (nullable): static boxed value to be set * @v_boxed: (nullable): static boxed value to be set
* *
* Set the contents of a %G_TYPE_BOXED derived #GValue to @v_boxed. * Set the contents of a %G_TYPE_BOXED derived #GValue to @v_boxed.
*
* The boxed value is assumed to be static, and is thus not duplicated * The boxed value is assumed to be static, and is thus not duplicated
* when setting the #GValue. * when setting the #GValue.
*/ */

92
gobject/gclosure.c
View File

@ -41,8 +41,9 @@
* @short_description: Functions as first-class objects * @short_description: Functions as first-class objects
* @title: Closures * @title: Closures
* *
* A #GClosure represents a callback supplied by the programmer. It * A #GClosure represents a callback supplied by the programmer.
* will generally comprise a function of some kind and a marshaller *
* It will generally comprise a function of some kind and a marshaller
* used to call it. It is the responsibility of the marshaller to * used to call it. It is the responsibility of the marshaller to
* convert the arguments for the invocation from #GValues into * convert the arguments for the invocation from #GValues into
* a suitable form, perform the callback on the converted arguments, * a suitable form, perform the callback on the converted arguments,
@ -150,8 +151,9 @@ enum {
* @data: data to store in the @data field of the newly allocated #GClosure * @data: data to store in the @data field of the newly allocated #GClosure
* *
* Allocates a struct of the given size and initializes the initial * Allocates a struct of the given size and initializes the initial
* part as a #GClosure. This function is mainly useful when * part as a #GClosure.
* implementing new types of closures. *
* This function is mainly useful when implementing new types of closures:
* *
* |[<!-- language="C" --> * |[<!-- language="C" -->
* typedef struct _MyClosure MyClosure; * typedef struct _MyClosure MyClosure;
@ -327,12 +329,15 @@ g_closure_set_meta_va_marshal (GClosure *closure,
* to @meta_marshal * to @meta_marshal
* @meta_marshal: a #GClosureMarshal function * @meta_marshal: a #GClosureMarshal function
* *
* Sets the meta marshaller of @closure. A meta marshaller wraps * Sets the meta marshaller of @closure.
* @closure->marshal and modifies the way it is called in some *
* fashion. The most common use of this facility is for C callbacks. * A meta marshaller wraps the @closure's marshal and modifies the way
* it is called in some fashion. The most common use of this facility
* is for C callbacks.
*
* The same marshallers (generated by [glib-genmarshal][glib-genmarshal]), * The same marshallers (generated by [glib-genmarshal][glib-genmarshal]),
* are used everywhere, but the way that we get the callback function * are used everywhere, but the way that we get the callback function
* differs. In most cases we want to use @closure->callback, but in * differs. In most cases we want to use the @closure's callback, but in
* other cases we want to use some different technique to retrieve the * other cases we want to use some different technique to retrieve the
* callback function. * callback function.
* *
@ -373,9 +378,11 @@ g_closure_set_meta_marshal (GClosure *closure,
* @post_marshal_notify: a function to call after the closure callback * @post_marshal_notify: a function to call after the closure callback
* *
* Adds a pair of notifiers which get invoked before and after the * Adds a pair of notifiers which get invoked before and after the
* closure callback, respectively. This is typically used to protect * closure callback, respectively.
* the extra arguments for the duration of the callback. See *
* g_object_watch_closure() for an example of marshal guards. * This is typically used to protect the extra arguments for the
* duration of the callback. See g_object_watch_closure() for an
* example of marshal guards.
*/ */
void void
g_closure_add_marshal_guards (GClosure *closure, g_closure_add_marshal_guards (GClosure *closure,
@ -428,11 +435,12 @@ g_closure_add_marshal_guards (GClosure *closure,
* @notify_func: the callback function to register * @notify_func: the callback function to register
* *
* Registers a finalization notifier which will be called when the * Registers a finalization notifier which will be called when the
* reference count of @closure goes down to 0. Multiple finalization * reference count of @closure goes down to 0.
* notifiers on a single closure are invoked in unspecified order. If *
* a single call to g_closure_unref() results in the closure being * Multiple finalization notifiers on a single closure are invoked in
* both invalidated and finalized, then the invalidate notifiers will * unspecified order. If a single call to g_closure_unref() results in
* be run before the finalize notifiers. * the closure being both invalidated and finalized, then the invalidate
* notifiers will be run before the finalize notifiers.
*/ */
void void
g_closure_add_finalize_notifier (GClosure *closure, g_closure_add_finalize_notifier (GClosure *closure,
@ -464,9 +472,10 @@ g_closure_add_finalize_notifier (GClosure *closure,
* @notify_func: the callback function to register * @notify_func: the callback function to register
* *
* Registers an invalidation notifier which will be called when the * Registers an invalidation notifier which will be called when the
* @closure is invalidated with g_closure_invalidate(). Invalidation * @closure is invalidated with g_closure_invalidate().
* notifiers are invoked before finalization notifiers, in an *
* unspecified order. * Invalidation notifiers are invoked before finalization notifiers,
* in an unspecified order.
*/ */
void void
g_closure_add_invalidate_notifier (GClosure *closure, g_closure_add_invalidate_notifier (GClosure *closure,
@ -561,7 +570,9 @@ g_closure_ref (GClosure *closure)
* Sets a flag on the closure to indicate that its calling * Sets a flag on the closure to indicate that its calling
* environment has become invalid, and thus causes any future * environment has become invalid, and thus causes any future
* invocations of g_closure_invoke() on this @closure to be * invocations of g_closure_invoke() on this @closure to be
* ignored. Also, invalidation notifiers installed on the closure will * ignored.
*
* Also, invalidation notifiers installed on the closure will
* be called at this point. Note that unless you are holding a * be called at this point. Note that unless you are holding a
* reference to the closure yourself, the invalidation notifiers may * reference to the closure yourself, the invalidation notifiers may
* unref the closure and cause it to be destroyed, so if you need to * unref the closure and cause it to be destroyed, so if you need to
@ -594,8 +605,10 @@ g_closure_invalidate (GClosure *closure)
* @closure: #GClosure to decrement the reference count on * @closure: #GClosure to decrement the reference count on
* *
* Decrements the reference count of a closure after it was previously * Decrements the reference count of a closure after it was previously
* incremented by the same caller. If no other callers are using the * incremented by the same caller.
* closure, then the closure will be destroyed and freed. *
* If no other callers are using the closure, then the closure will be
* destroyed and freed.
*/ */
void void
g_closure_unref (GClosure *closure) g_closure_unref (GClosure *closure)
@ -640,27 +653,34 @@ g_closure_unref (GClosure *closure)
* @closure: #GClosure to decrement the initial reference count on, if it's * @closure: #GClosure to decrement the initial reference count on, if it's
* still being held * still being held
* *
* Takes over the initial ownership of a closure. Each closure is * Takes over the initial ownership of a closure.
* initially created in a "floating" state, which means that the initial *
* reference count is not owned by any caller. g_closure_sink() checks * Each closure is initially created in a "floating" state, which means
* to see if the object is still floating, and if so, unsets the * that the initial reference count is not owned by any caller.
* floating state and decreases the reference count. If the closure *
* is not floating, g_closure_sink() does nothing. The reason for the * This function checks to see if the object is still floating, and if so,
* existence of the floating state is to prevent cumbersome code * unsets the floating state and decreases the reference count. If the
* sequences like: * closure is not floating, g_closure_sink() does nothing.
*
* The reason for the existence of the floating state is to prevent
* cumbersome code sequences like:
*
* |[<!-- language="C" --> * |[<!-- language="C" -->
* closure = g_cclosure_new (cb_func, cb_data); * closure = g_cclosure_new (cb_func, cb_data);
* g_source_set_closure (source, closure); * g_source_set_closure (source, closure);
* g_closure_unref (closure); // GObject doesn't really need this * g_closure_unref (closure); // GObject doesn't really need this
* ]| * ]|
*
* Because g_source_set_closure() (and similar functions) take ownership of the * Because g_source_set_closure() (and similar functions) take ownership of the
* initial reference count, if it is unowned, we instead can write: * initial reference count, if it is unowned, we instead can write:
*
* |[<!-- language="C" --> * |[<!-- language="C" -->
* g_source_set_closure (source, g_cclosure_new (cb_func, cb_data)); * g_source_set_closure (source, g_cclosure_new (cb_func, cb_data));
* ]| * ]|
* *
* Generally, this function is used together with g_closure_ref(). An example * Generally, this function is used together with g_closure_ref(). An example
* of storing a closure for later notification looks like: * of storing a closure for later notification looks like:
*
* |[<!-- language="C" --> * |[<!-- language="C" -->
* static GClosure *notify_closure = NULL; * static GClosure *notify_closure = NULL;
* void * void
@ -888,12 +908,16 @@ _g_closure_invoke_va (GClosure *closure,
* @closure: a #GClosure * @closure: a #GClosure
* @marshal: a #GClosureMarshal function * @marshal: a #GClosureMarshal function
* *
* Sets the marshaller of @closure. The `marshal_data` * Sets the marshaller of @closure.
* of @marshal provides a way for a meta marshaller to provide additional *
* information to the marshaller. (See g_closure_set_meta_marshal().) For * The `marshal_data` of @marshal provides a way for a meta marshaller to
* GObject's C predefined marshallers (the g_cclosure_marshal_*() * provide additional information to the marshaller.
*
* For GObject's C predefined marshallers (the `g_cclosure_marshal_*()`
* functions), what it provides is a callback function to use instead of * functions), what it provides is a callback function to use instead of
* @closure->callback. * @closure->callback.
*
* See also: g_closure_set_meta_marshal()
*/ */
void void
g_closure_set_marshal (GClosure *closure, g_closure_set_marshal (GClosure *closure,

12
gobject/gclosure.h
View File

@ -42,6 +42,7 @@ G_BEGIN_DECLS
* @cl: a #GClosure * @cl: a #GClosure
* *
* Get the total number of notifiers connected with the closure @cl. * Get the total number of notifiers connected with the closure @cl.
*
* The count includes the meta marshaller, the finalize and invalidate notifiers * The count includes the meta marshaller, the finalize and invalidate notifiers
* and the marshal guards. Note that each guard counts as two notifiers. * and the marshal guards. Note that each guard counts as two notifiers.
* See g_closure_set_meta_marshal(), g_closure_add_finalize_notifier(), * See g_closure_set_meta_marshal(), g_closure_add_finalize_notifier(),
@ -78,10 +79,13 @@ typedef struct _GClosureNotifyData GClosureNotifyData;
* GCallback: * GCallback:
* *
* The type used for callback functions in structure definitions and function * The type used for callback functions in structure definitions and function
* signatures. This doesn't mean that all callback functions must take no * signatures.
* parameters and return void. The required signature of a callback function *
* is determined by the context in which is used (e.g. the signal to which it * This doesn't mean that all callback functions must take no parameters and
* is connected). Use G_CALLBACK() to cast the callback function to a #GCallback. * return void. The required signature of a callback function is determined by
* the context in which is used (e.g. the signal to which it is connected).
*
* Use G_CALLBACK() to cast the callback function to a #GCallback.
*/ */
typedef void (*GCallback) (void); typedef void (*GCallback) (void);
/** /**

17
gobject/gobject.c
View File

@ -66,15 +66,18 @@
* claimed to be "owned" by any code portion. The main motivation for * claimed to be "owned" by any code portion. The main motivation for
* providing floating references is C convenience. In particular, it * providing floating references is C convenience. In particular, it
* allows code to be written as: * allows code to be written as:
*
* |[<!-- language="C" --> * |[<!-- language="C" -->
* container = create_container (); * container = create_container ();
* container_add_child (container, create_child()); * container_add_child (container, create_child());
* ]| * ]|
*
* If container_add_child() calls g_object_ref_sink() on the passed-in child, * If container_add_child() calls g_object_ref_sink() on the passed-in child,
* no reference of the newly created child is leaked. Without floating * no reference of the newly created child is leaked. Without floating
* references, container_add_child() can only g_object_ref() the new child, * references, container_add_child() can only g_object_ref() the new child,
* so to implement this code without reference leaks, it would have to be * so to implement this code without reference leaks, it would have to be
* written as: * written as:
*
* |[<!-- language="C" --> * |[<!-- language="C" -->
* Child *child; * Child *child;
* container = create_container (); * container = create_container ();
@ -82,6 +85,7 @@
* container_add_child (container, child); * container_add_child (container, child);
* g_object_unref (child); * g_object_unref (child);
* ]| * ]|
*
* The floating reference can be converted into an ordinary reference by * The floating reference can be converted into an ordinary reference by
* calling g_object_ref_sink(). For already sunken objects (objects that * calling g_object_ref_sink(). For already sunken objects (objects that
* don't have a floating reference anymore), g_object_ref_sink() is equivalent * don't have a floating reference anymore), g_object_ref_sink() is equivalent
@ -537,11 +541,13 @@ g_object_do_class_init (GObjectClass *class)
* This signal is typically used to obtain change notification for a * This signal is typically used to obtain change notification for a
* single property, by specifying the property name as a detail in the * single property, by specifying the property name as a detail in the
* g_signal_connect() call, like this: * g_signal_connect() call, like this:
*
* |[<!-- language="C" --> * |[<!-- language="C" -->
* g_signal_connect (text_view->buffer, "notify::paste-target-list", * g_signal_connect (text_view->buffer, "notify::paste-target-list",
* G_CALLBACK (gtk_text_view_target_list_notify), * G_CALLBACK (gtk_text_view_target_list_notify),
* text_view) * text_view)
* ]| * ]|
*
* It is important to note that you must use * It is important to note that you must use
* [canonical parameter names][canonical-parameter-names] as * [canonical parameter names][canonical-parameter-names] as
* detail strings for the notify signal. * detail strings for the notify signal.
@ -4530,11 +4536,12 @@ g_initially_unowned_class_init (GInitiallyUnownedClass *klass)
/** /**
* GWeakRef: * GWeakRef:
* *
* A structure containing a weak reference to a #GObject. It can either * A structure containing a weak reference to a #GObject.
* be empty (i.e. point to %NULL), or point to an object for as long as *
* at least one "strong" reference to that object exists. Before the * A `GWeakRef` can either be empty (i.e. point to %NULL), or point to an
* object's #GObjectClass.dispose method is called, every #GWeakRef * object for as long as at least one "strong" reference to that object
* associated with becomes empty (i.e. points to %NULL). * exists. Before the object's #GObjectClass.dispose method is called,
* every #GWeakRef associated with becomes empty (i.e. points to %NULL).
* *
* Like #GValue, #GWeakRef can be statically allocated, stack- or * Like #GValue, #GWeakRef can be statically allocated, stack- or
* heap-allocated, or embedded in larger structures. * heap-allocated, or embedded in larger structures.

59
gobject/gobject.h
View File

@ -45,6 +45,7 @@ G_BEGIN_DECLS
* @object: Object which is subject to casting. * @object: Object which is subject to casting.
* *
* Casts a #GObject or derived pointer into a (GObject*) pointer. * Casts a #GObject or derived pointer into a (GObject*) pointer.
*
* Depending on the current debugging level, this function may invoke * Depending on the current debugging level, this function may invoke
* certain runtime checks to identify invalid casts. * certain runtime checks to identify invalid casts.
*/ */
@ -144,7 +145,9 @@ G_BEGIN_DECLS
* @object: Object which is subject to casting. * @object: Object which is subject to casting.
* *
* Casts a #GInitiallyUnowned or derived pointer into a (GInitiallyUnowned*) * Casts a #GInitiallyUnowned or derived pointer into a (GInitiallyUnowned*)
* pointer. Depending on the current debugging level, this function may invoke * pointer.
*
* Depending on the current debugging level, this function may invoke
* certain runtime checks to identify invalid casts. * certain runtime checks to identify invalid casts.
*/ */
#define G_INITIALLY_UNOWNED(object) (G_TYPE_CHECK_INSTANCE_CAST ((object), G_TYPE_INITIALLY_UNOWNED, GInitiallyUnowned)) #define G_INITIALLY_UNOWNED(object) (G_TYPE_CHECK_INSTANCE_CAST ((object), G_TYPE_INITIALLY_UNOWNED, GInitiallyUnowned))
@ -230,17 +233,21 @@ typedef void (*GObjectFinalizeFunc) (GObject *object);
* @where_the_object_was: the object being disposed * @where_the_object_was: the object being disposed
* *
* A #GWeakNotify function can be added to an object as a callback that gets * A #GWeakNotify function can be added to an object as a callback that gets
* triggered when the object is finalized. Since the object is already being * triggered when the object is finalized.
* disposed when the #GWeakNotify is called, there's not much you could do *
* with the object, apart from e.g. using its address as hash-index or the like. * Since the object is already being disposed when the #GWeakNotify is called,
* there's not much you could do with the object, apart from e.g. using its
* address as hash-index or the like.
*/ */
typedef void (*GWeakNotify) (gpointer data, typedef void (*GWeakNotify) (gpointer data,
GObject *where_the_object_was); GObject *where_the_object_was);
/** /**
* GObject: * GObject:
* *
* All the fields in the GObject structure are private * The base object type.
* to the #GObject implementation and should never be accessed directly. *
* All the fields in the `GObject` structure are private to the implementation
* and should never be accessed directly.
*/ */
struct _GObject struct _GObject
{ {
@ -352,14 +359,14 @@ struct _GObjectClass
/* padding */ /* padding */
gpointer pdummy[6]; gpointer pdummy[6];
}; };
/** /**
* GObjectConstructParam: * GObjectConstructParam:
* @pspec: the #GParamSpec of the construct parameter * @pspec: the #GParamSpec of the construct parameter
* @value: the value to set the parameter to * @value: the value to set the parameter to
* *
* The GObjectConstructParam struct is an auxiliary * The GObjectConstructParam struct is an auxiliary structure used to hand
* structure used to hand #GParamSpec/#GValue pairs to the @constructor of * #GParamSpec/#GValue pairs to the @constructor of a #GObjectClass.
* a #GObjectClass.
*/ */
struct _GObjectConstructParam struct _GObjectConstructParam
{ {
@ -370,9 +377,10 @@ struct _GObjectConstructParam
/** /**
* GInitiallyUnowned: * GInitiallyUnowned:
* *
* All the fields in the GInitiallyUnowned structure * A type for objects that have an initially floating reference.
* are private to the #GInitiallyUnowned implementation and should never be *
* accessed directly. * All the fields in the `GInitiallyUnowned` structure are private to the
* implementation and should never be accessed directly.
*/ */
/** /**
* GInitiallyUnownedClass: * GInitiallyUnownedClass:
@ -531,7 +539,9 @@ void g_object_remove_weak_pointer (GObject *object,
* references. * references.
* *
* A callback function used for notification when the state * A callback function used for notification when the state
* of a toggle reference changes. See g_object_add_toggle_ref(). * of a toggle reference changes.
*
* See also: g_object_add_toggle_ref()
*/ */
typedef void (*GToggleNotify) (gpointer data, typedef void (*GToggleNotify) (gpointer data,
GObject *object, GObject *object,
@ -685,10 +695,11 @@ void g_clear_object (GObject **object_ptr);
* @new_object: (nullable) (transfer none): a pointer to the new #GObject to * @new_object: (nullable) (transfer none): a pointer to the new #GObject to
* assign to @object_ptr, or %NULL to clear the pointer * assign to @object_ptr, or %NULL to clear the pointer
* *
* Updates a #GObject pointer to refer to @new_object. It increments the * Updates a #GObject pointer to refer to @new_object.
* reference count of @new_object (if non-%NULL), decrements the reference *
* count of the current value of @object_ptr (if non-%NULL), and assigns * It increments the reference count of @new_object (if non-%NULL), decrements
* @new_object to @object_ptr. The assignment is not atomic. * the reference count of the current value of @object_ptr (if non-%NULL), and
* assigns @new_object to @object_ptr. The assignment is not atomic.
* *
* @object_ptr must not be %NULL, but can point to a %NULL value. * @object_ptr must not be %NULL, but can point to a %NULL value.
* *
@ -838,13 +849,15 @@ static inline void
* @new_object: (nullable) (transfer none): a pointer to the new #GObject to * @new_object: (nullable) (transfer none): a pointer to the new #GObject to
* assign to it, or %NULL to clear the pointer * assign to it, or %NULL to clear the pointer
* *
* Updates a pointer to weakly refer to @new_object. It assigns @new_object * Updates a pointer to weakly refer to @new_object.
* to @weak_pointer_location and ensures that @weak_pointer_location will
* automatically be set to %NULL if @new_object gets destroyed. The assignment
* is not atomic. The weak reference is not thread-safe, see
* g_object_add_weak_pointer() for details.
* *
* @weak_pointer_location must not be %NULL. * It assigns @new_object to @weak_pointer_location and ensures
* that @weak_pointer_location will automatically be set to %NULL
* if @new_object gets destroyed. The assignment is not atomic.
* The weak reference is not thread-safe, see g_object_add_weak_pointer()
* for details.
*
* The @weak_pointer_location argument must not be %NULL.
* *
* A macro is also included that allows this function to be used without * A macro is also included that allows this function to be used without
* pointer casts. The function itself is static inline, so its address may vary * pointer casts. The function itself is static inline, so its address may vary

17
gobject/gparam.c
View File

@ -890,9 +890,10 @@ value_param_lcopy_value (const GValue *value,
* GParamSpecPool: * GParamSpecPool:
* *
* A #GParamSpecPool maintains a collection of #GParamSpecs which can be * A #GParamSpecPool maintains a collection of #GParamSpecs which can be
* quickly accessed by owner and name. The implementation of the #GObject property * quickly accessed by owner and name.
* system uses such a pool to store the #GParamSpecs of the properties all object *
* types. * The implementation of the #GObject property system uses such a pool to
* store the #GParamSpecs of the properties all object types.
*/ */
struct _GParamSpecPool struct _GParamSpecPool
{ {
@ -1401,10 +1402,12 @@ default_values_cmp (GParamSpec *pspec,
* @name: 0-terminated string used as the name of the new #GParamSpec type. * @name: 0-terminated string used as the name of the new #GParamSpec type.
* @pspec_info: The #GParamSpecTypeInfo for this #GParamSpec type. * @pspec_info: The #GParamSpecTypeInfo for this #GParamSpec type.
* *
* Registers @name as the name of a new static type derived from * Registers @name as the name of a new static type derived
* #G_TYPE_PARAM. The type system uses the information contained in * from #G_TYPE_PARAM.
* the #GParamSpecTypeInfo structure pointed to by @info to manage the *
* #GParamSpec type and its instances. * The type system uses the information contained in the #GParamSpecTypeInfo
* structure pointed to by @info to manage the #GParamSpec type and its
* instances.
* *
* Returns: The new type identifier. * Returns: The new type identifier.
*/ */

5
gobject/gparam.h
View File

@ -145,7 +145,9 @@ G_BEGIN_DECLS
* Since 2.26 * Since 2.26
* *
* Through the #GParamFlags flag values, certain aspects of parameters * Through the #GParamFlags flag values, certain aspects of parameters
* can be configured. See also #G_PARAM_STATIC_STRINGS. * can be configured.
*
* See also: %G_PARAM_STATIC_STRINGS
*/ */
typedef enum typedef enum
{ {
@ -368,6 +370,7 @@ typedef struct _GParamSpecTypeInfo GParamSpecTypeInfo;
* This structure is used to provide the type system with the information * This structure is used to provide the type system with the information
* required to initialize and destruct (finalize) a parameter's class and * required to initialize and destruct (finalize) a parameter's class and
* instances thereof. * instances thereof.
*
* The initialized structure is passed to the g_param_type_register_static() * The initialized structure is passed to the g_param_type_register_static()
* The type system will perform a deep copy of this structure, so its memory * The type system will perform a deep copy of this structure, so its memory
* does not need to be persistent across invocation of * does not need to be persistent across invocation of

13
gobject/gparamspecs.h
View File

@ -923,11 +923,14 @@ struct _GParamSpecObject
/** /**
* GParamSpecOverride: * GParamSpecOverride:
* *
* This is a type of #GParamSpec type that simply redirects operations to * A #GParamSpec derived structure that redirects operations to
* another paramspec. All operations other than getting or * other types of #GParamSpec.
* setting the value are redirected, including accessing the nick and *
* blurb, validating a value, and so forth. See * All operations other than getting or setting the value are redirected,
* g_param_spec_get_redirect_target() for retrieving the overridden * including accessing the nick and blurb, validating a value, and so
* forth.
*
* See g_param_spec_get_redirect_target() for retrieving the overridden
* property. #GParamSpecOverride is used in implementing * property. #GParamSpecOverride is used in implementing
* g_object_class_override_property(), and will not be directly useful * g_object_class_override_property(), and will not be directly useful
* unless you are implementing a new base type similar to GObject. * unless you are implementing a new base type similar to GObject.

34
gobject/gsignal.h
View File

@ -36,9 +36,11 @@ typedef struct _GSignalInvocationHint GSignalInvocationHint;
* *
* This is the signature of marshaller functions, required to marshall * This is the signature of marshaller functions, required to marshall
* arrays of parameter values to signal emissions into C language callback * arrays of parameter values to signal emissions into C language callback
* invocations. It is merely an alias to #GClosureMarshal since the #GClosure * invocations.
* mechanism takes over responsibility of actual function invocation for the *
* signal system. * It is merely an alias to #GClosureMarshal since the #GClosure mechanism
* takes over responsibility of actual function invocation for the signal
* system.
*/ */
typedef GClosureMarshal GSignalCMarshaller; typedef GClosureMarshal GSignalCMarshaller;
/** /**
@ -58,9 +60,10 @@ typedef GVaClosureMarshal GSignalCVaMarshaller;
* the signal was emitted, followed by the parameters of the emission. * the signal was emitted, followed by the parameters of the emission.
* @data: user data associated with the hook. * @data: user data associated with the hook.
* *
* A simple function pointer to get invoked when the signal is emitted. This * A simple function pointer to get invoked when the signal is emitted.
* allows you to tie a hook to the signal type, so that it will trap all *
* emissions of that signal, from any object. * Emission hooks allow you to tie a hook to the signal type, so that it will
* trap all emissions of that signal, from any object.
* *
* You may not attach these to signals created with the #G_SIGNAL_NO_HOOKS flag. * You may not attach these to signals created with the #G_SIGNAL_NO_HOOKS flag.
* *
@ -81,10 +84,12 @@ typedef gboolean (*GSignalEmissionHook) (GSignalInvocationHint *ihint,
* *
* The signal accumulator is a special callback function that can be used * The signal accumulator is a special callback function that can be used
* to collect return values of the various callbacks that are called * to collect return values of the various callbacks that are called
* during a signal emission. The signal accumulator is specified at signal * during a signal emission.
* creation time, if it is left %NULL, no accumulation of callback return *
* values is performed. The return value of signal emissions is then the * The signal accumulator is specified at signal creation time, if it is
* value returned by the last callback. * left %NULL, no accumulation of callback return values is performed.
* The return value of signal emissions is then the value returned by the
* last callback.
* *
* Returns: The accumulator function returns whether the signal emission * Returns: The accumulator function returns whether the signal emission
* should be aborted. Returning %TRUE will continue with * should be aborted. Returning %TRUE will continue with
@ -126,9 +131,7 @@ typedef gboolean (*GSignalAccumulator) (GSignalInvocationHint *ihint,
* functions for the #GSignalInvocationHint::run_type field to mark the first * functions for the #GSignalInvocationHint::run_type field to mark the first
* call to the accumulator function for a signal emission. Since 2.68. * call to the accumulator function for a signal emission. Since 2.68.
* *
* The signal flags are used to specify a signal's behaviour, the overall * The signal flags are used to specify a signal's behaviour.
* signal description outlines how especially the RUN flags control the
* stages of a signal emission.
*/ */
typedef enum typedef enum
{ {
@ -253,8 +256,9 @@ struct _GSignalInvocationHint
* gpointer data2); * gpointer data2);
* ]| * ]|
* *
* A structure holding in-depth information for a specific signal. It is * A structure holding in-depth information for a specific signal.
* filled in by the g_signal_query() function. *
* See also: g_signal_query()
*/ */
struct _GSignalQuery struct _GSignalQuery
{ {

89
gobject/gtype.h
View File

@ -32,6 +32,7 @@ G_BEGIN_DECLS
* @type: A #GType value. * @type: A #GType value.
* *
* The fundamental type which is the ancestor of @type. * The fundamental type which is the ancestor of @type.
*
* Fundamental types are types that serve as ultimate bases for the derived types, * Fundamental types are types that serve as ultimate bases for the derived types,
* thus they are the roots of distinct inheritance hierarchies. * thus they are the roots of distinct inheritance hierarchies.
*/ */
@ -70,6 +71,7 @@ G_BEGIN_DECLS
* G_TYPE_CHAR: * G_TYPE_CHAR:
* *
* The fundamental type corresponding to #gchar. * The fundamental type corresponding to #gchar.
*
* The type designated by G_TYPE_CHAR is unconditionally an 8-bit signed integer. * The type designated by G_TYPE_CHAR is unconditionally an 8-bit signed integer.
* This may or may not be the same type a the C type "gchar". * This may or may not be the same type a the C type "gchar".
*/ */
@ -213,6 +215,7 @@ G_BEGIN_DECLS
* @x: the fundamental type number. * @x: the fundamental type number.
* *
* Get the type ID for the fundamental type number @x. * Get the type ID for the fundamental type number @x.
*
* Use g_type_fundamental_next() instead of this macro to create new fundamental * Use g_type_fundamental_next() instead of this macro to create new fundamental
* types. * types.
* *
@ -281,6 +284,7 @@ G_BEGIN_DECLS
* @type: A #GType value * @type: A #GType value
* *
* Checks if @type is an interface type. * Checks if @type is an interface type.
*
* An interface type provides a pure API, the implementation * An interface type provides a pure API, the implementation
* of which is provided by another type (which is then said to conform * of which is provided by another type (which is then said to conform
* to the interface). GLib interfaces are somewhat analogous to Java * to the interface). GLib interfaces are somewhat analogous to Java
@ -451,7 +455,8 @@ struct _GTypeInterface
* @instance_size: the size of the instance structure * @instance_size: the size of the instance structure
* *
* A structure holding information for a specific type. * A structure holding information for a specific type.
* It is filled in by the g_type_query() function. *
* See also: g_type_query()
*/ */
struct _GTypeQuery struct _GTypeQuery
{ {
@ -642,6 +647,7 @@ struct _GTypeQuery
* @c_type: The C type for the private structure * @c_type: The C type for the private structure
* *
* Gets the private structure for a particular type. * Gets the private structure for a particular type.
*
* The private structure must have been registered in the * The private structure must have been registered in the
* class_init function with g_type_class_add_private(). * class_init function with g_type_class_add_private().
* *
@ -661,6 +667,7 @@ struct _GTypeQuery
* @c_type: The C type for the private structure * @c_type: The C type for the private structure
* *
* Gets the private class structure for a particular type. * Gets the private class structure for a particular type.
*
* The private structure must have been registered in the * The private structure must have been registered in the
* get_type() function with g_type_add_class_private(). * get_type() function with g_type_add_class_private().
* *
@ -773,9 +780,12 @@ int g_type_get_instance_count (GType type);
* @g_class: (type GObject.TypeClass): The #GTypeClass structure to initialize * @g_class: (type GObject.TypeClass): The #GTypeClass structure to initialize
* *
* A callback function used by the type system to do base initialization * A callback function used by the type system to do base initialization
* of the class structures of derived types. It is called as part of the * of the class structures of derived types.
* initialization process of all derived classes and should reallocate *
* or reset all dynamic class members copied over from the parent class. * This function is called as part of the initialization process of all derived
* classes and should reallocate or reset all dynamic class members copied over
* from the parent class.
*
* For example, class members (such as strings) that are not sufficiently * For example, class members (such as strings) that are not sufficiently
* handled by a plain memory copy of the parent class into the derived class * handled by a plain memory copy of the parent class into the derived class
* have to be altered. See GClassInitFunc() for a discussion of the class * have to be altered. See GClassInitFunc() for a discussion of the class
@ -788,8 +798,11 @@ typedef void (*GBaseInitFunc) (gpointer g_class);
* *
* A callback function used by the type system to finalize those portions * A callback function used by the type system to finalize those portions
* of a derived types class structure that were setup from the corresponding * of a derived types class structure that were setup from the corresponding
* GBaseInitFunc() function. Class finalization basically works the inverse * GBaseInitFunc() function.
* way in which class initialization is performed. *
* Class finalization basically works the inverse way in which class
* initialization is performed.
*
* See GClassInitFunc() for a discussion of the class initialization process. * See GClassInitFunc() for a discussion of the class initialization process.
*/ */
typedef void (*GBaseFinalizeFunc) (gpointer g_class); typedef void (*GBaseFinalizeFunc) (gpointer g_class);
@ -799,8 +812,9 @@ typedef void (*GBaseFinalizeFunc) (gpointer g_class);
* @class_data: The @class_data member supplied via the #GTypeInfo structure. * @class_data: The @class_data member supplied via the #GTypeInfo structure.
* *
* A callback function used by the type system to initialize the class * A callback function used by the type system to initialize the class
* of a specific type. This function should initialize all static class * of a specific type.
* members. *
* This function should initialize all static class members.
* *
* The initialization process of a class involves: * The initialization process of a class involves:
* *
@ -869,6 +883,7 @@ typedef void (*GBaseFinalizeFunc) (gpointer g_class);
* class->static_float = 3.14159265358979323846; * class->static_float = 3.14159265358979323846;
* } * }
* ]| * ]|
*
* Initialization of TypeBClass will first cause initialization of * Initialization of TypeBClass will first cause initialization of
* TypeAClass (derived classes reference their parent classes, see * TypeAClass (derived classes reference their parent classes, see
* g_type_class_ref() on this). * g_type_class_ref() on this).
@ -902,8 +917,10 @@ typedef void (*GClassInitFunc) (gpointer g_class,
* @class_data: The @class_data member supplied via the #GTypeInfo structure * @class_data: The @class_data member supplied via the #GTypeInfo structure
* *
* A callback function used by the type system to finalize a class. * A callback function used by the type system to finalize a class.
*
* This function is rarely needed, as dynamically allocated class resources * This function is rarely needed, as dynamically allocated class resources
* should be handled by GBaseInitFunc() and GBaseFinalizeFunc(). * should be handled by GBaseInitFunc() and GBaseFinalizeFunc().
*
* Also, specification of a GClassFinalizeFunc() in the #GTypeInfo * Also, specification of a GClassFinalizeFunc() in the #GTypeInfo
* structure of a static type is invalid, because classes of static types * structure of a static type is invalid, because classes of static types
* will never be finalized (they are artificially kept alive when their * will never be finalized (they are artificially kept alive when their
@ -918,8 +935,10 @@ typedef void (*GClassFinalizeFunc) (gpointer g_class,
* created for * created for
* *
* A callback function used by the type system to initialize a new * A callback function used by the type system to initialize a new
* instance of a type. This function initializes all instance members and * instance of a type.
* allocates any resources required by it. *
* This function initializes all instance members and allocates any resources
* required by it.
* *
* Initialization of a derived instance involves calling all its parent * Initialization of a derived instance involves calling all its parent
* types instance initializers, so the class member of the instance * types instance initializers, so the class member of the instance
@ -937,8 +956,10 @@ typedef void (*GInstanceInitFunc) (GTypeInstance *instance,
* @iface_data: The @interface_data supplied via the #GInterfaceInfo structure * @iface_data: The @interface_data supplied via the #GInterfaceInfo structure
* *
* A callback function used by the type system to initialize a new * A callback function used by the type system to initialize a new
* interface. This function should initialize all internal data and * interface.
* allocate any resources required by the interface. *
* This function should initialize all internal data and* allocate any
* resources required by the interface.
* *
* The members of @iface_data are guaranteed to have been filled with * The members of @iface_data are guaranteed to have been filled with
* zeros before this function is called. * zeros before this function is called.
@ -951,6 +972,7 @@ typedef void (*GInterfaceInitFunc) (gpointer g_iface,
* @iface_data: The @interface_data supplied via the #GInterfaceInfo structure * @iface_data: The @interface_data supplied via the #GInterfaceInfo structure
* *
* A callback function used by the type system to finalize an interface. * A callback function used by the type system to finalize an interface.
*
* This function should destroy any internal data and release any resources * This function should destroy any internal data and release any resources
* allocated by the corresponding GInterfaceInitFunc() function. * allocated by the corresponding GInterfaceInitFunc() function.
*/ */
@ -963,10 +985,11 @@ typedef void (*GInterfaceFinalizeFunc) (gpointer g_iface,
* unreferenced * unreferenced
* *
* A callback function which is called when the reference count of a class * A callback function which is called when the reference count of a class
* drops to zero. It may use g_type_class_ref() to prevent the class from * drops to zero.
* being freed. You should not call g_type_class_unref() from a *
* #GTypeClassCacheFunc function to prevent infinite recursion, use * It may use g_type_class_ref() to prevent the class from being freed. You
* g_type_class_unref_uncached() instead. * should not call g_type_class_unref() from a #GTypeClassCacheFunc function
* to prevent infinite recursion, use g_type_class_unref_uncached() instead.
* *
* The functions have to check the class id passed in to figure * The functions have to check the class id passed in to figure
* whether they actually want to cache the class of this type, since all * whether they actually want to cache the class of this type, since all
@ -984,6 +1007,7 @@ typedef gboolean (*GTypeClassCacheFunc) (gpointer cache_data,
* initialized * initialized
* *
* A callback called after an interface vtable is initialized. * A callback called after an interface vtable is initialized.
*
* See g_type_add_interface_check(). * See g_type_add_interface_check().
* *
* Since: 2.4 * Since: 2.4
@ -1356,12 +1380,12 @@ guint g_type_get_type_registration_serial (void);
* @OBJ_NAME: The bare name of the type, in all caps (like `WIDGET`) * @OBJ_NAME: The bare name of the type, in all caps (like `WIDGET`)
* @ParentName: the name of the parent type, in camel case (like `GtkWidget`) * @ParentName: the name of the parent type, in camel case (like `GtkWidget`)
* *
* A convenience macro for emitting the usual declarations in the header file for a type which is not (at the * A convenience macro for emitting the usual declarations in the header file
* present time) intended to be subclassed. * for a type which is not (at the present time) intended to be subclassed.
* *
* You might use it in a header as follows: * You might use it in a header as follows:
* *
* |[ * |[<!-- language="C" -->
* #ifndef _myapp_window_h_ * #ifndef _myapp_window_h_
* #define _myapp_window_h_ * #define _myapp_window_h_
* *
@ -1442,7 +1466,7 @@ guint g_type_get_type_registration_serial (void);
* *
* You might use it in a header as follows: * You might use it in a header as follows:
* *
* |[ * |[<!-- language="C" -->
* #ifndef _gtk_frobber_h_ * #ifndef _gtk_frobber_h_
* #define _gtk_frobber_h_ * #define _gtk_frobber_h_
* *
@ -1539,7 +1563,7 @@ guint g_type_get_type_registration_serial (void);
* *
* You might use it in a header as follows: * You might use it in a header as follows:
* *
* |[ * |[<!-- language="C" -->
* #ifndef _my_model_h_ * #ifndef _my_model_h_
* #define _my_model_h_ * #define _my_model_h_
* *
@ -1624,6 +1648,7 @@ guint g_type_get_type_registration_serial (void);
* @_C_: Custom code that gets inserted in the `*_get_type()` function. * @_C_: Custom code that gets inserted in the `*_get_type()` function.
* *
* A convenience macro for type implementations. * A convenience macro for type implementations.
*
* Similar to G_DEFINE_TYPE(), but allows you to insert custom code into the * Similar to G_DEFINE_TYPE(), but allows you to insert custom code into the
* `*_get_type()` function, e.g. interface implementations via G_IMPLEMENT_INTERFACE(). * `*_get_type()` function, e.g. interface implementations via G_IMPLEMENT_INTERFACE().
* See G_DEFINE_TYPE_EXTENDED() for an example. * See G_DEFINE_TYPE_EXTENDED() for an example.
@ -1642,6 +1667,7 @@ guint g_type_get_type_registration_serial (void);
* initialization function, an instance initialization function (see #GTypeInfo * initialization function, an instance initialization function (see #GTypeInfo
* for information about these), a static variable named `t_n_parent_class` * for information about these), a static variable named `t_n_parent_class`
* pointing to the parent class, and adds private instance data to the type. * pointing to the parent class, and adds private instance data to the type.
*
* Furthermore, it defines a `*_get_type()` function. See G_DEFINE_TYPE_EXTENDED() * Furthermore, it defines a `*_get_type()` function. See G_DEFINE_TYPE_EXTENDED()
* for an example. * for an example.
* *
@ -1664,6 +1690,7 @@ guint g_type_get_type_registration_serial (void);
* @T_P: The #GType of the parent type. * @T_P: The #GType of the parent type.
* *
* A convenience macro for type implementations. * A convenience macro for type implementations.
*
* Similar to G_DEFINE_TYPE(), but defines an abstract type. * Similar to G_DEFINE_TYPE(), but defines an abstract type.
* See G_DEFINE_TYPE_EXTENDED() for an example. * See G_DEFINE_TYPE_EXTENDED() for an example.
* *
@ -1679,9 +1706,11 @@ guint g_type_get_type_registration_serial (void);
* @_C_: Custom code that gets inserted in the `type_name_get_type()` function. * @_C_: Custom code that gets inserted in the `type_name_get_type()` function.
* *
* A convenience macro for type implementations. * A convenience macro for type implementations.
*
* Similar to G_DEFINE_TYPE_WITH_CODE(), but defines an abstract type and * Similar to G_DEFINE_TYPE_WITH_CODE(), but defines an abstract type and
* allows you to insert custom code into the `*_get_type()` function, e.g. * allows you to insert custom code into the `*_get_type()` function, e.g.
* interface implementations via G_IMPLEMENT_INTERFACE(). * interface implementations via G_IMPLEMENT_INTERFACE().
*
* See G_DEFINE_TYPE_EXTENDED() for an example. * See G_DEFINE_TYPE_EXTENDED() for an example.
* *
* Since: 2.4 * Since: 2.4
@ -1695,6 +1724,7 @@ guint g_type_get_type_registration_serial (void);
* @T_P: The #GType of the parent type. * @T_P: The #GType of the parent type.
* *
* Similar to G_DEFINE_TYPE_WITH_PRIVATE(), but defines an abstract type. * Similar to G_DEFINE_TYPE_WITH_PRIVATE(), but defines an abstract type.
*
* See G_DEFINE_TYPE_EXTENDED() for an example. * See G_DEFINE_TYPE_EXTENDED() for an example.
* *
* Since: 2.38 * Since: 2.38
@ -1772,7 +1802,9 @@ guint g_type_get_type_registration_serial (void);
* G_IMPLEMENT_INTERFACE (TYPE_GIZMO, * G_IMPLEMENT_INTERFACE (TYPE_GIZMO,
* gtk_gadget_gizmo_init)); * gtk_gadget_gizmo_init));
* ]| * ]|
*
* expands to * expands to
*
* |[<!-- language="C" --> * |[<!-- language="C" -->
* static void gtk_gadget_init (GtkGadget *self); * static void gtk_gadget_init (GtkGadget *self);
* static void gtk_gadget_class_init (GtkGadgetClass *klass); * static void gtk_gadget_class_init (GtkGadgetClass *klass);
@ -1819,6 +1851,7 @@ guint g_type_get_type_registration_serial (void);
* return static_g_define_type_id; * return static_g_define_type_id;
* } * }
* ]| * ]|
*
* The only pieces which have to be manually provided are the definitions of * The only pieces which have to be manually provided are the definitions of
* the instance and class structure and the definitions of the instance and * the instance and class structure and the definitions of the instance and
* class init functions. * class init functions.
@ -1860,11 +1893,13 @@ guint g_type_get_type_registration_serial (void);
* for no prerequisite type. * for no prerequisite type.
* @_C_: Custom code that gets inserted in the `*_get_type()` function. * @_C_: Custom code that gets inserted in the `*_get_type()` function.
* *
* A convenience macro for #GTypeInterface definitions. Similar to * A convenience macro for #GTypeInterface definitions.
* G_DEFINE_INTERFACE(), but allows you to insert custom code into the *
* `*_get_type()` function, e.g. additional interface implementations * Similar to G_DEFINE_INTERFACE(), but allows you to insert custom code
* via G_IMPLEMENT_INTERFACE(), or additional prerequisite types. See * into the `*_get_type()` function, e.g. additional interface implementations
* G_DEFINE_TYPE_EXTENDED() for a similar example using * via G_IMPLEMENT_INTERFACE(), or additional prerequisite types.
*
* See G_DEFINE_TYPE_EXTENDED() for a similar example using
* G_DEFINE_TYPE_WITH_CODE(). * G_DEFINE_TYPE_WITH_CODE().
* *
* Since: 2.24 * Since: 2.24
@ -2153,7 +2188,6 @@ type_name##_get_type (void) \
* GType type = my_struct_get_type (); * GType type = my_struct_get_type ();
* // ... your code ... * // ... your code ...
* } * }
*
* ]| * ]|
* *
* Since: 2.26 * Since: 2.26
@ -2169,6 +2203,7 @@ type_name##_get_type (void) \
* @_C_: Custom code that gets inserted in the `*_get_type()` function * @_C_: Custom code that gets inserted in the `*_get_type()` function
* *
* A convenience macro for boxed type implementations. * A convenience macro for boxed type implementations.
*
* Similar to G_DEFINE_BOXED_TYPE(), but allows to insert custom code into the * Similar to G_DEFINE_BOXED_TYPE(), but allows to insert custom code into the
* `type_name_get_type()` function, e.g. to register value transformations with * `type_name_get_type()` function, e.g. to register value transformations with
* g_value_register_transform_func(), for instance: * g_value_register_transform_func(), for instance:

13
gobject/gtypemodule.c
View File

@ -30,16 +30,20 @@
* @title: GTypeModule * @title: GTypeModule
* *
* #GTypeModule provides a simple implementation of the #GTypePlugin * #GTypeModule provides a simple implementation of the #GTypePlugin
* interface. The model of #GTypeModule is a dynamically loaded module * interface.
* which implements some number of types and interface implementations. *
* The model of #GTypeModule is a dynamically loaded module which
* implements some number of types and interface implementations.
*
* When the module is loaded, it registers its types and interfaces * When the module is loaded, it registers its types and interfaces
* using g_type_module_register_type() and g_type_module_add_interface(). * using g_type_module_register_type() and g_type_module_add_interface().
* As long as any instances of these types and interface implementations * As long as any instances of these types and interface implementations
* are in use, the module is kept loaded. When the types and interfaces * are in use, the module is kept loaded. When the types and interfaces
* are gone, the module may be unloaded. If the types and interfaces * are gone, the module may be unloaded. If the types and interfaces
* become used again, the module will be reloaded. Note that the last * become used again, the module will be reloaded. Note that the last
* unref cannot happen in module code, since that would lead to the * reference cannot be released from within the module code, since that
* caller's code being unloaded before g_object_unref() returns to it. * would lead to the caller's code being unloaded before g_object_unref()
* returns to it.
* *
* Keeping track of whether the module should be loaded or not is done by * Keeping track of whether the module should be loaded or not is done by
* using a use count - it starts at zero, and whenever it is greater than * using a use count - it starts at zero, and whenever it is greater than
@ -57,7 +61,6 @@
* in #GTypeModuleClass. * in #GTypeModuleClass.
*/ */
typedef struct _ModuleTypeInfo ModuleTypeInfo; typedef struct _ModuleTypeInfo ModuleTypeInfo;
typedef struct _ModuleInterfaceInfo ModuleInterfaceInfo; typedef struct _ModuleInterfaceInfo ModuleInterfaceInfo;

23
gobject/gtypemodule.h
View File

@ -93,9 +93,10 @@ struct _GTypeModuleClass
* A convenience macro for dynamic type implementations, which declares a * A convenience macro for dynamic type implementations, which declares a
* class initialization function, an instance initialization function (see * class initialization function, an instance initialization function (see
* #GTypeInfo for information about these) and a static variable named * #GTypeInfo for information about these) and a static variable named
* `t_n`_parent_class pointing to the parent class. Furthermore, * `t_n`_parent_class pointing to the parent class.
* it defines a `*_get_type()` and a static `*_register_type()` functions *
* for use in your `module_init()`. * Furthermore, it defines a `*_get_type()` and a static `*_register_type()`
* functions for use in your `module_init()`.
* *
* See G_DEFINE_DYNAMIC_TYPE_EXTENDED() for an example. * See G_DEFINE_DYNAMIC_TYPE_EXTENDED() for an example.
* *
@ -114,7 +115,7 @@ struct _GTypeModuleClass
* A more general version of G_DEFINE_DYNAMIC_TYPE() which * A more general version of G_DEFINE_DYNAMIC_TYPE() which
* allows to specify #GTypeFlags and custom code. * allows to specify #GTypeFlags and custom code.
* *
* |[ * |[<!-- language="C" -->
* G_DEFINE_DYNAMIC_TYPE_EXTENDED (GtkGadget, * G_DEFINE_DYNAMIC_TYPE_EXTENDED (GtkGadget,
* gtk_gadget, * gtk_gadget,
* GTK_TYPE_THING, * GTK_TYPE_THING,
@ -122,8 +123,10 @@ struct _GTypeModuleClass
* G_IMPLEMENT_INTERFACE_DYNAMIC (TYPE_GIZMO, * G_IMPLEMENT_INTERFACE_DYNAMIC (TYPE_GIZMO,
* gtk_gadget_gizmo_init)); * gtk_gadget_gizmo_init));
* ]| * ]|
*
* expands to * expands to
* |[ *
* |[<!-- language="C" -->
* static void gtk_gadget_init (GtkGadget *self); * static void gtk_gadget_init (GtkGadget *self);
* static void gtk_gadget_class_init (GtkGadgetClass *klass); * static void gtk_gadget_class_init (GtkGadgetClass *klass);
* static void gtk_gadget_class_finalize (GtkGadgetClass *klass); * static void gtk_gadget_class_finalize (GtkGadgetClass *klass);
@ -227,8 +230,9 @@ type_name##_register_type (GTypeModule *type_module) \
* @iface_init: The interface init function * @iface_init: The interface init function
* *
* A convenience macro to ease interface addition in the @_C_ section * A convenience macro to ease interface addition in the @_C_ section
* of G_DEFINE_DYNAMIC_TYPE_EXTENDED(). See G_DEFINE_DYNAMIC_TYPE_EXTENDED() * of G_DEFINE_DYNAMIC_TYPE_EXTENDED().
* for an example. *
* See G_DEFINE_DYNAMIC_TYPE_EXTENDED() for an example.
* *
* Note that this macro can only be used together with the * Note that this macro can only be used together with the
* G_DEFINE_DYNAMIC_TYPE_EXTENDED macros, since it depends on variable * G_DEFINE_DYNAMIC_TYPE_EXTENDED macros, since it depends on variable
@ -248,8 +252,9 @@ type_name##_register_type (GTypeModule *type_module) \
* @TypeName: the name of the type in CamelCase * @TypeName: the name of the type in CamelCase
* *
* A convenience macro to ease adding private data to instances of a new dynamic * A convenience macro to ease adding private data to instances of a new dynamic
* type in the @_C_ section of G_DEFINE_DYNAMIC_TYPE_EXTENDED(). See * type in the @_C_ section of G_DEFINE_DYNAMIC_TYPE_EXTENDED().
* G_ADD_PRIVATE() for details, it is similar but for static types. *
* See G_ADD_PRIVATE() for details, it is similar but for static types.
* *
* Note that this macro can only be used together with the * Note that this macro can only be used together with the
* G_DEFINE_DYNAMIC_TYPE_EXTENDED macros, since it depends on variable * G_DEFINE_DYNAMIC_TYPE_EXTENDED macros, since it depends on variable

5
gobject/gtypeplugin.c
View File

@ -26,9 +26,10 @@
* @see_also: #GTypeModule and g_type_register_dynamic(). * @see_also: #GTypeModule and g_type_register_dynamic().
* @title: GTypePlugin * @title: GTypePlugin
* *
* An interface that handles the lifecycle of dynamically loaded types.
*
* The GObject type system supports dynamic loading of types. * The GObject type system supports dynamic loading of types.
* The #GTypePlugin interface is used to handle the lifecycle * It goes as follows:
* of dynamically loaded types. It goes as follows:
* *
* 1. The type is initially introduced (usually upon loading the module * 1. The type is initially introduced (usually upon loading the module
* the first time, or by your main application that knows what modules * the first time, or by your main application that knows what modules

1
gobject/gvalue.c
View File

@ -42,6 +42,7 @@
* *
* The #GValue structure is basically a variable container that consists * The #GValue structure is basically a variable container that consists
* of a type identifier and a specific value of that type. * of a type identifier and a specific value of that type.
*
* The type identifier within a #GValue structure always determines the * The type identifier within a #GValue structure always determines the
* type of the associated value. * type of the associated value.
* *

5
gobject/gvalue.h
View File

@ -33,6 +33,7 @@ G_BEGIN_DECLS
* @type: A #GType value. * @type: A #GType value.
* *
* Checks whether the passed in type ID can be used for g_value_init(). * Checks whether the passed in type ID can be used for g_value_init().
*
* That is, this macro checks whether this type provides an implementation * That is, this macro checks whether this type provides an implementation
* of the #GTypeValueTable functions required for a type to create a #GValue of. * of the #GTypeValueTable functions required for a type to create a #GValue of.
* *
@ -97,10 +98,12 @@ typedef void (*GValueTransform) (const GValue *src_value,
* GValue: * GValue:
* *
* An opaque structure used to hold different types of values. * An opaque structure used to hold different types of values.
*
* The data within the structure has protected scope: it is accessible only * The data within the structure has protected scope: it is accessible only
* to functions within a #GTypeValueTable structure, or implementations of * to functions within a #GTypeValueTable structure, or implementations of
* the g_value_*() API. That is, code portions which implement new fundamental * the g_value_*() API. That is, code portions which implement new fundamental
* types. * types.
*
* #GValue users cannot make any assumptions about how data is stored * #GValue users cannot make any assumptions about how data is stored
* within the 2 element @data union, and the @g_type member should * within the 2 element @data union, and the @g_type member should
* only be accessed through the G_VALUE_TYPE() macro. * only be accessed through the G_VALUE_TYPE() macro.
@ -193,7 +196,7 @@ void g_value_register_transform_func (GType src_type,
* be used as initializer instead of an explicit `{ 0 }` when declaring * be used as initializer instead of an explicit `{ 0 }` when declaring
* a variable, but it cannot be assigned to a variable. * a variable, but it cannot be assigned to a variable.
* *
* |[ * |[<!-- language="C" -->
* GValue value = G_VALUE_INIT; * GValue value = G_VALUE_INIT;
* ]| * ]|
* *

18
gobject/gvaluecollector.h
View File

@ -23,6 +23,7 @@
* *
* The macros in this section provide the varargs parsing support needed * The macros in this section provide the varargs parsing support needed
* in variadic GObject functions such as g_object_new() or g_object_set(). * in variadic GObject functions such as g_object_new() or g_object_set().
*
* They currently support the collection of integral types, floating point * They currently support the collection of integral types, floating point
* types and pointers. * types and pointers.
*/ */
@ -79,9 +80,10 @@ union _GTypeCValue
* @__error: a #gchar** variable that will be modified to hold a g_new() * @__error: a #gchar** variable that will be modified to hold a g_new()
* allocated error messages if something fails * allocated error messages if something fails
* *
* Collects a variable argument value from a va_list. We have to * Collects a variable argument value from a `va_list`.
* implement the varargs collection as a macro, because on some systems *
* va_list variables cannot be passed by reference. * We have to implement the varargs collection as a macro, because on some
* systems `va_list` variables cannot be passed by reference.
* *
* Since: 2.24 * Since: 2.24
*/ */
@ -136,9 +138,10 @@ G_STMT_START { \
* @__error: a #gchar** variable that will be modified to hold a g_new() * @__error: a #gchar** variable that will be modified to hold a g_new()
* allocated error messages if something fails * allocated error messages if something fails
* *
* Collects a variable argument value from a va_list. We have to * Collects a variable argument value from a `va_list`.
* implement the varargs collection as a macro, because on some systems *
* va_list variables cannot be passed by reference. * We have to implement the varargs collection as a macro, because on some systems
* `va_list` variables cannot be passed by reference.
* *
* Note: If you are creating the @value argument just before calling this macro, * Note: If you are creating the @value argument just before calling this macro,
* you should use the #G_VALUE_COLLECT_INIT variant and pass the uninitialized * you should use the #G_VALUE_COLLECT_INIT variant and pass the uninitialized
@ -203,7 +206,8 @@ G_STMT_START { \
* @__error: a #gchar** variable that will be modified to hold a g_new() * @__error: a #gchar** variable that will be modified to hold a g_new()
* allocated error message if something fails * allocated error message if something fails
* *
* Stores a value’s value into one or more argument locations from a va_list. * Stores a value’s value into one or more argument locations from a `va_list`.
*
* This is the inverse of G_VALUE_COLLECT(). * This is the inverse of G_VALUE_COLLECT().
*/ */
#define G_VALUE_LCOPY(value, var_args, flags, __error) \ #define G_VALUE_LCOPY(value, var_args, flags, __error) \