* various functions such as g_io_channel_write_chars() to
* write raw bytes to the channel. Encoding and buffering
* issues are dealt with at a higher level.
- * @io_seek: (optional) seeks the channel. This is called from
+ * @io_seek: (optional): seeks the channel. This is called from
* g_io_channel_seek() on channels that support it.
* @io_close: closes the channel. This is called from
* g_io_channel_close() after flushing the buffers.
* "Presentación.sxi". If the application which created it uses
* ISO-8859-1 for its encoding,
* |[
- * Character: P r e s e n t a c i ó n . s x i
+ * Character: P r e s e n t a c i ó n . s x i
* Hex code: 50 72 65 73 65 6e 74 61 63 69 f3 6e 2e 73 78 69
* ]|
* However, if the application use UTF-8, the actual file name on
* disk would look like this:
* |[
- * Character: P r e s e n t a c i ó n . s x i
+ * Character: P r e s e n t a c i ó n . s x i
* Hex code: 50 72 65 73 65 6e 74 61 63 69 c3 b3 6e 2e 73 78 69
* ]|
* Glib uses UTF-8 for its strings, and GUI toolkits like GTK+ that use
* Note that, unless you set the #G_REGEX_RAW flag, all the strings passed
* to these functions must be encoded in UTF-8. The lengths and the positions
* inside the strings are in bytes and not in characters, so, for instance,
- * "\xc3\xa0" (i.e. "à") is two bytes long but it is treated as a
+ * "\xc3\xa0" (i.e. "à") is two bytes long but it is treated as a
* single character. If you set #G_REGEX_RAW the strings can be non-valid
* UTF-8 strings and a byte is treated as a character, so "\xc3\xa0" is two
* bytes and two characters long.
* @short_description: strongly typed value datatype
* @see_also: GVariantType
*
- * #GVariant is a variant datatype; it stores a value along with
- * information about the type of that value. The range of possible
- * values is determined by the type. The type system used by #GVariant
- * is #GVariantType.
+ * #GVariant is a variant datatype; it can contain one or more values
+ * along with information about the type of the values.
+ *
+ * A #GVariant may contain simple types, like an integer, or a boolean value;
+ * or complex types, like an array of two strings, or a dictionary of key
+ * value pairs. A #GVariant is also immutable: once it's been created neither
+ * its type nor its content can be modified further.
+ *
+ * GVariant is useful whenever data needs to be serialized, for example when
+ * sending method parameters in DBus, or when saving settings using GSettings.
+ *
+ * When creating a new #GVariant, you pass the data you want to store in it
+ * along with a string representing the type of data you wish to pass to it.
+ *
+ * For instance, if you want to create a #GVariant holding an integer value you
+ * can use:
+ *
+ * |[<!-- language="C" -->
+ * GVariant *v = g_variant_new ('u', 40);
+ * ]|
+ *
+ * The string 'u' in the first argument tells #GVariant that the data passed to
+ * the constructor (40) is going to be an unsigned integer.
+ *
+ * More advanced examples of #GVariant in use can be found in documentation for
+ * [GVariant format strings][gvariant-format-strings-pointers].
+ *
+ * The range of possible values is determined by the type.
+ *
+ * The type system used by #GVariant is #GVariantType.
*
* #GVariant instances always have a type and a value (which are given
* at construction time). The type and value of a #GVariant instance
* generally considered undefined after one of these checks fails.
* They are not intended for normal control flow, only to give a
* perhaps-helpful warning before giving up.
+ *
+ * Structured logging output is supported using g_log_structured(). This differs
+ * from the traditional g_log() API in that log messages are handled as a
+ * collection of key–value pairs representing individual pieces of information,
+ * rather than as a single string containing all the information in an arbitrary
+ * format.
+ *
+ * The support for structured logging was motivated by the following needs (some
+ * of which were supported previously; others weren’t):
+ * * Support for multiple logging levels.
+ * * Structured log support with the ability to add `MESSAGE_ID`s (see
+ * g_log_structured()).
+ * * Moving the responsibility for filtering log messages from the program to
+ * the log viewer — instead of libraries and programs installing log handlers
+ * (with g_log_set_handler()) which filter messages before output, all log
+ * messages are outputted, and the log viewer program (such as `journalctl`)
+ * must filter them. This is based on the idea that bugs are sometimes hard
+ * to reproduce, so it is better to log everything possible and then use
+ * tools to analyse the logs than it is to not be able to reproduce a bug to
+ * get additional log data. Code which uses logging in performance-critical
+ * sections should compile out the g_log_structured() calls in
+ * release builds, and compile them in in debugging builds.
+ * * A single writer function which handles all log messages in a process, from
+ * all libraries and program code; rather than multiple log handlers with
+ * poorly defined interactions between them. This allows a program to easily
+ * change its logging policy by changing the writer function, for example to
+ * log to an additional location or to change what logging output fallbacks
+ * are used. The log writer functions provided by GLib are exposed publicly
+ * so they can be used from programs’ log writers. This allows log writer
+ * policy and implementation to be kept separate.
+ * * If a library wants to add standard information to all of its log messages
+ * (such as library state) or to redact private data (such as passwords or
+ * network credentials), it should use a wrapper function around its
+ * g_log_structured() calls or implement that in the single log writer
+ * function.
+ * * If a program wants to pass context data from a g_log_structured() call to
+ * its log writer function so that, for example, it can use the correct
+ * server connection to submit logs to, that user data can be passed as a
+ * zero-length #GLogField to g_log_structured_array().
+ * * Color output needed to be supported on the terminal, to make reading
+ * through logs easier.
*/
/**
+ * g_abort:
+ *
+ * A wrapper for the POSIX abort() function.
+ *
+ * On Windows it is a function that makes extra effort (including a call
+ * to abort()) to ensure that a debugger-catchable exception is thrown
+ * before the program terminates.
+ *
+ * See your C library manual for more details about abort().
+ *
+ * Since: 2.50
+ */
+
+
+/**
* g_access:
- * @filename: a pathname in the GLib file name encoding (UTF-8 on Windows)
+ * @filename: (type filename): a pathname in the GLib file name encoding
+ * (UTF-8 on Windows)
* @mode: as in access()
*
* A wrapper for the POSIX access() function. This function is used to
/**
* g_basename:
- * @file_name: the name of the file
+ * @file_name: (type filename): the name of the file
*
* Gets the name of the file without any leading directory
* components. It returns a pointer into the given file name
* string.
*
- * Returns: the name of the file without any leading
+ * Returns: (type filename): the name of the file without any leading
* directory components
* Deprecated: 2.2: Use g_path_get_basename() instead, but notice
* that g_path_get_basename() allocates new memory for the
/**
* g_bookmark_file_load_from_data_dirs:
* @bookmark: a #GBookmarkFile
- * @file: a relative path to a filename to open and parse
- * @full_path: (allow-none): return location for a string containing the full path
- * of the file, or %NULL
+ * @file: (type filename): a relative path to a filename to open and parse
+ * @full_path: (type filename) (allow-none): return location for a string
+ * containing the full path of the file, or %NULL
* @error: return location for a #GError, or %NULL
*
* This function looks for a desktop bookmark file named @file in the
/**
* g_bookmark_file_load_from_file:
* @bookmark: an empty #GBookmarkFile struct
- * @filename: the path of a filename to load, in the GLib file name encoding
+ * @filename: (type filename): the path of a filename to load, in the
+ * GLib file name encoding
* @error: return location for a #GError, or %NULL
*
* Loads a desktop bookmark file into an empty #GBookmarkFile structure.
/**
* g_bookmark_file_to_file:
* @bookmark: a #GBookmarkFile
- * @filename: path of the output file
+ * @filename: (type filename): path of the output file
* @error: return location for a #GError, or %NULL
*
* This function outputs @bookmark into a file. The write process is
/**
* g_build_filename:
- * @first_element: the first element in the path
+ * @first_element: (type filename): the first element in the path
* @...: remaining elements in path, terminated by %NULL
*
* Creates a filename from a series of elements using the correct
* path. If the first element is a relative path, the result will
* be a relative path.
*
- * Returns: a newly-allocated string that must be freed with g_free().
+ * Returns: (type filename): a newly-allocated string that must be freed with
+ * g_free().
*/
/**
* g_build_filenamev:
- * @args: (array zero-terminated=1): %NULL-terminated array of strings containing the path elements.
+ * @args: (array zero-terminated=1) (element-type filename): %NULL-terminated
+ * array of strings containing the path elements.
*
* Behaves exactly like g_build_filename(), but takes the path elements
* as a string array, instead of varargs. This function is mainly
* meant for language bindings.
*
- * Returns: a newly-allocated string that must be freed with g_free().
+ * Returns: (type filename): a newly-allocated string that must be freed
+ * with g_free().
* Since: 2.8
*/
/**
* g_build_path:
- * @separator: a string used to separator the elements of the path.
- * @first_element: the first element in the path
+ * @separator: (type filename): a string used to separator the elements of the path.
+ * @first_element: (type filename): the first element in the path
* @...: remaining elements in path, terminated by %NULL
*
* Creates a path from a series of elements using @separator as the
* copies of the separator, elements consisting only of copies
* of the separator are ignored.
*
- * Returns: a newly-allocated string that must be freed with g_free().
+ * Returns: (type filename): a newly-allocated string that must be freed with
+ * g_free().
*/
/**
* g_build_pathv:
* @separator: a string used to separator the elements of the path.
- * @args: (array zero-terminated=1): %NULL-terminated array of strings containing the path elements.
+ * @args: (array zero-terminated=1) (element-type filename): %NULL-terminated
+ * array of strings containing the path elements.
*
* Behaves exactly like g_build_path(), but takes the path elements
* as a string array, instead of varargs. This function is mainly
* meant for language bindings.
*
- * Returns: a newly-allocated string that must be freed with g_free().
+ * Returns: (type filename): a newly-allocated string that must be freed
+ * with g_free().
* Since: 2.8
*/
/**
* g_chdir:
- * @path: a pathname in the GLib file name encoding (UTF-8 on Windows)
+ * @path: (type filename): a pathname in the GLib file name encoding
+ * (UTF-8 on Windows)
*
* A wrapper for the POSIX chdir() function. The function changes the
* current directory of the process to @path.
/**
* g_chmod:
- * @filename: a pathname in the GLib file name encoding (UTF-8 on Windows)
+ * @filename: (type filename): a pathname in the GLib file name encoding
+ * (UTF-8 on Windows)
* @mode: as in chmod()
*
* A wrapper for the POSIX chmod() function. The chmod() function is
/**
+ * g_compute_hmac_for_bytes:
+ * @digest_type: a #GChecksumType to use for the HMAC
+ * @key: the key to use in the HMAC
+ * @data: binary blob to compute the HMAC of
+ *
+ * Computes the HMAC for a binary @data. This is a
+ * convenience wrapper for g_hmac_new(), g_hmac_get_string()
+ * and g_hmac_unref().
+ *
+ * The hexadecimal string returned will be in lower case.
+ *
+ * Returns: the HMAC of the binary data as a string in hexadecimal.
+ * The returned string should be freed with g_free() when done using it.
+ * Since: 2.50
+ */
+
+
+/**
* g_compute_hmac_for_data:
* @digest_type: a #GChecksumType to use for the HMAC
* @key: (array length=key_len): the key to use in the HMAC
* @key_len: the length of the key
- * @data: binary blob to compute the HMAC of
+ * @data: (array length=length): binary blob to compute the HMAC of
* @length: length of @data
*
* Computes the HMAC for a binary @data of @length. This is a
/**
* g_creat:
- * @filename: a pathname in the GLib file name encoding (UTF-8 on Windows)
+ * @filename: (type filename): a pathname in the GLib file name encoding
+ * (UTF-8 on Windows)
* @mode: as in creat()
*
* A wrapper for the POSIX creat() function. The creat() function is
* @date: a #GDate
*
* Returns the week of the year during which this date falls, if
- * weeks are understood to being on Sunday. The date must be valid.
+ * weeks are understood to begin on Sunday. The date must be valid.
* Can return 0 if the day is before the first Sunday of the year.
*
* Returns: week number
* On Windows, as is true of all GLib functions which operate on
* filenames, the returned name is in UTF-8.
*
- * Returns: The entry's name or %NULL if there are no
+ * Returns: (type filename): The entry's name or %NULL if there are no
* more entries. The return value is owned by GLib and
* must not be modified or freed.
*/
/**
* g_dirname:
- * @file_name: the name of the file
+ * @file_name: (type filename): the name of the file
*
* Gets the directory components of a file name.
*
* If the file name has no directory components "." is returned.
* The returned string should be freed when no longer needed.
*
- * Returns: the directory components of the file
+ * Returns: (type filename): the directory components of the file
* Deprecated: use g_path_get_dirname() instead
*/
/**
* g_file_read_link:
- * @filename: the symbolic link
+ * @filename: (type filename): the symbolic link
* @error: return location for a #GError
*
* Reads the contents of the symbolic link @filename like the POSIX
* readlink() function. The returned string is in the encoding used
* for filenames. Use g_filename_to_utf8() to convert it to UTF-8.
*
- * Returns: A newly-allocated string with the contents of the symbolic link,
- * or %NULL if an error occurred.
+ * Returns: (type filename): A newly-allocated string with the contents of
+ * the symbolic link, or %NULL if an error occurred.
* Since: 2.4
*/
/**
* g_file_test:
- * @filename: a filename to test in the GLib file name encoding
+ * @filename: (type filename): a filename to test in the
+ * GLib file name encoding
* @test: bitfield of #GFileTest flags
*
* Returns %TRUE if any of the tests in the bitfield @test are
/**
* g_filename_display_basename:
- * @filename: an absolute pathname in the GLib file name encoding
+ * @filename: (type filename): an absolute pathname in the
+ * GLib file name encoding
*
* Returns the display basename for the particular filename, guaranteed
* to be valid UTF-8. The display name might not be identical to the filename,
/**
* g_filename_display_name:
- * @filename: a pathname hopefully in the GLib file name encoding
+ * @filename: (type filename): a pathname hopefully in the
+ * GLib file name encoding
*
* Converts a filename into a valid UTF-8 string. The conversion is
* not necessarily reversible, so you should keep the original around
/**
* g_filename_to_uri:
- * @filename: an absolute filename specified in the GLib file name encoding,
- * which is the on-disk file name bytes on Unix, and UTF-8 on
- * Windows
+ * @filename: (type filename): an absolute filename specified in the GLib file
+ * name encoding, which is the on-disk file name bytes on Unix, and UTF-8
+ * on Windows
* @hostname: (allow-none): A UTF-8 encoded hostname, or %NULL for none.
* @error: location to store the error occurring, or %NULL to ignore
* errors. Any of the errors in #GConvertError may occur.
/**
* g_filename_to_utf8:
- * @opsysstring: a string in the encoding for filenames
+ * @opsysstring: (type filename): a string in the encoding for filenames
* @len: the length of the string, or -1 if the string is
* nul-terminated (Note that some encodings may allow nul
* bytes to occur inside strings. In that case, using -1
/**
* g_find_program_in_path:
- * @program: a program name in the GLib file name encoding
+ * @program: (type filename): a program name in the GLib file name encoding
*
* Locates the first executable named @program in the user's path, in the
* same way that execvp() would locate it. Returns an allocated string
* the program is found, the return value contains the full name
* including the type suffix.
*
- * Returns: a newly-allocated string with the absolute path, or %NULL
+ * Returns: (type filename): a newly-allocated string with the absolute path,
+ * or %NULL
*/
/**
* g_fopen:
- * @filename: a pathname in the GLib file name encoding (UTF-8 on Windows)
+ * @filename: (type filename): a pathname in the GLib file name encoding
+ * (UTF-8 on Windows)
* @mode: a string describing the mode in which the file should be opened
*
* A wrapper for the stdio fopen() function. The fopen() function
/**
* g_freopen:
- * @filename: a pathname in the GLib file name encoding (UTF-8 on Windows)
+ * @filename: (type filename): a pathname in the GLib file name encoding
+ * (UTF-8 on Windows)
* @mode: a string describing the mode in which the file should be opened
* @stream: (allow-none): an existing stream which will be reused, or %NULL
*
* the current directory. This can make a difference in the case that
* the current directory is the target of a symbolic link.
*
- * Returns: the current directory
+ * Returns: (type filename): the current directory
*/
* and said environment variables have no effect.
*
* `G_FILENAME_ENCODING` may be set to a comma-separated list of
- * character set names. The special token "@locale" is taken
+ * character set names. The special token "\@locale" is taken
* to mean the character set for the [current locale][setlocale].
* If `G_FILENAME_ENCODING` is not set, but `G_BROKEN_FILENAMES` is,
* the character set of the current locale is taken as the filename
* should either directly check the `HOME` environment variable yourself
* or unset it before calling any functions in GLib.
*
- * Returns: the current user's home directory
+ * Returns: (type filename): the current user's home directory
*/
* real user name cannot be determined, the string "Unknown" is
* returned.
*
- * Returns: the user's real name.
+ * Returns: (type filename): the user's real name.
*/
* of clip art, or a log file in the CSIDL_COMMON_APPDATA folder.
* This information will not roam and is available to anyone using the computer.
*
- * Returns: (array zero-terminated=1) (transfer none): a %NULL-terminated array of strings owned by GLib that must
- * not be modified or freed.
+ * Returns: (array zero-terminated=1) (element-type filename) (transfer none):
+ * a %NULL-terminated array of strings owned by GLib that must not be
+ * modified or freed.
* Since: 2.6
*/
* Note that on Windows the returned list can vary depending on where
* this function is called.
*
- * Returns: (array zero-terminated=1) (transfer none): a %NULL-terminated array of strings owned by GLib that must
- * not be modified or freed.
+ * Returns: (array zero-terminated=1) (element-type filename) (transfer none):
+ * a %NULL-terminated array of strings owned by GLib that must not be
+ * modified or freed.
* Since: 2.6
*/
* it is always UTF-8. The return value is never %NULL or the empty
* string.
*
- * Returns: the directory to use for temporary files.
+ * Returns: (type filename): the directory to use for temporary files.
*/
* C:\Documents and Settings\username\Local Settings\Temporary Internet Files.
* See documentation for CSIDL_INTERNET_CACHE.
*
- * Returns: a string owned by GLib that must not be modified
+ * Returns: (type filename): a string owned by GLib that must not be modified
* or freed.
* Since: 2.6
*/
* CSIDL_LOCAL_APPDATA. Note that on Windows it thus is the same as
* what g_get_user_data_dir() returns.
*
- * Returns: a string owned by GLib that must not be modified
+ * Returns: (type filename): a string owned by GLib that must not be modified
* or freed.
* Since: 2.6
*/
* CSIDL_LOCAL_APPDATA. Note that on Windows it thus is the same as
* what g_get_user_config_dir() returns.
*
- * Returns: a string owned by GLib that must not be modified
+ * Returns: (type filename): a string owned by GLib that must not be modified
* or freed.
* Since: 2.6
*/
* encoding, or something else, and there is no guarantee that it is even
* consistent on a machine. On Windows, it is always UTF-8.
*
- * Returns: the user name of the current user.
+ * Returns: (type filename): the user name of the current user.
*/
* CSIDL_LOCAL_APPDATA. Note that on Windows it thus is the same as
* what g_get_user_config_dir() returns.
*
- * Returns: a string owned by GLib that must not be modified or freed.
+ * Returns: (type filename): a string owned by GLib that must not be
+ * modified or freed.
* Since: 2.28
*/
* of the special directory without requiring the session to restart; GLib
* will not reflect any change once the special directories are loaded.
*
- * Returns: the path to the specified special directory, or %NULL
- * if the logical id was not found. The returned string is owned by
+ * Returns: (type filename): the path to the specified special directory, or
+ * %NULL if the logical id was not found. The returned string is owned by
* GLib and should not be modified or freed.
* Since: 2.14
*/
/**
* g_io_channel_new_file:
- * @filename: A string containing the name of a file
+ * @filename: (type filename): A string containing the name of a file
* @mode: One of "r", "w", "a", "r+", "w+", "a+". These have
* the same meaning as in fopen()
* @error: A location to return an error of type %G_FILE_ERROR
/**
+ * g_key_file_load_from_bytes:
+ * @key_file: an empty #GKeyFile struct
+ * @bytes: a #GBytes
+ * @flags: flags from #GKeyFileFlags
+ * @error: return location for a #GError, or %NULL
+ *
+ * Loads a key file from the data in @bytes into an empty #GKeyFile structure.
+ * If the object cannot be created then %error is set to a #GKeyFileError.
+ *
+ * Returns: %TRUE if a key file could be loaded, %FALSE otherwise
+ * Since: 2.50
+ */
+
+
+/**
* g_key_file_load_from_data:
* @key_file: an empty #GKeyFile struct
* @data: key file loaded in memory
* the `G_DEBUG` environment variable (see
* [Running GLib Applications](glib-running.html)).
*
+ * Libraries should not call this function, as it affects all messages logged
+ * by a process, including those from other libraries.
+ *
+ * Structured log messages (using g_log_structured() and
+ * g_log_structured_array()) are fatal only if the default log writer is used;
+ * otherwise it is up to the writer function to determine which log messages
+ * are fatal.
+ *
* Returns: the old fatal mask
*/
* Sets the log levels which are fatal in the given domain.
* %G_LOG_LEVEL_ERROR is always fatal.
*
+ * This has no effect on structured log messages (using g_log_structured() or
+ * g_log_structured_array()). To change the fatal behaviour for specific log
+ * messages, programs must install a custom log writer function using
+ * g_log_set_writer_func().
+ *
* Returns: the old fatal mask for the log domain
*/
/**
+ * g_log_set_writer_func:
+ * @func: log writer function, which must not be %NULL
+ * @user_data: (closure func): user data to pass to @func
+ * @user_data_free: (destroy func): function to free @user_data once it’s
+ * finished with, if non-%NULL
+ *
+ * Set a writer function which will be called to format and write out each log
+ * message. Each program should set a writer function, or the default writer
+ * (g_log_writer_default()) will be used.
+ *
+ * Libraries **must not** call this function — only programs are allowed to
+ * install a writer function, as there must be a single, central point where
+ * log messages are formatted and outputted.
+ *
+ * There can only be one writer function. It is an error to set more than one.
+ *
+ * Since: 2.50
+ */
+
+
+/**
+ * g_log_structured:
+ * @log_domain: log domain, usually %G_LOG_DOMAIN
+ * @log_level: log level, either from #GLogLevelFlags, or a user-defined
+ * level
+ * @...: key-value pairs of structured data to add to the log entry, followed
+ * by the key "MESSAGE", followed by a printf()-style message format,
+ * followed by parameters to insert in the format string
+ *
+ * Log a message with structured data. The message will be passed through to
+ * 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
+ * be aborted at the end of this function.
+ *
+ * The structured data is provided as key–value pairs, where keys are UTF-8
+ * strings, and values are arbitrary pointers — typically pointing to UTF-8
+ * strings, but that is not a requirement. To pass binary (non-nul-terminated)
+ * structured data, use g_log_structured_array(). The keys for structured data
+ * should follow the [systemd journal
+ * fields](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html)
+ * specification. It is suggested that custom keys are namespaced according to
+ * the code which sets them. For example, custom keys from GLib all have a
+ * `GLIB_` prefix.
+ *
+ * The @log_domain will be converted into a `GLIB_DOMAIN` field. @log_level will
+ * be converted into a
+ * [`PRIORITY`](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#PRIORITY=)
+ * field. The format string will have its placeholders substituted for the provided
+ * values and be converted into a
+ * [`MESSAGE`](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#MESSAGE=)
+ * field.
+ *
+ * Other fields you may commonly want to pass into this function:
+ *
+ * * [`MESSAGE_ID`](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#MESSAGE_ID=)
+ * * [`CODE_FILE`](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#CODE_FILE=)
+ * * [`CODE_LINE`](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#CODE_LINE=)
+ * * [`CODE_FUNC`](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#CODE_FUNC=)
+ * * [`ERRNO`](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#ERRNO=)
+ *
+ * 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(),
+ * g_error(), etc, if the symbols `G_LOG_USE_STRUCTURED` is defined before including
+ * glib.h.
+ *
+ * For example:
+ * |[<!-- language="C" -->
+ * g_log_structured (G_LOG_DOMAIN, G_LOG_LEVEL_DEBUG,
+ * "MESSAGE_ID", "06d4df59e6c24647bfe69d2c27ef0b4e",
+ * "MY_APPLICATION_CUSTOM_FIELD", "some debug string",
+ * "MESSAGE", "This is a debug message about pointer %p and integer %u.",
+ * some_pointer, some_integer);
+ * ]|
+ *
+ * Note that each `MESSAGE_ID` must be [uniquely and randomly
+ * generated](https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html#MESSAGE_ID=).
+ * If adding a `MESSAGE_ID`, consider shipping a [message
+ * catalog](https://www.freedesktop.org/wiki/Software/systemd/catalog/) with
+ * your software.
+ *
+ * To pass a user data pointer to the log writer function which is specific to
+ * this logging call, you must use g_log_structured_array() and pass the pointer
+ * as a field with #GLogField.length set to zero, otherwise it will be
+ * interpreted as a string.
+ *
+ * For example:
+ * |[<!-- language="C" -->
+ * const GLogField fields[] = {
+ * { "MESSAGE", "This is a debug message.", -1 },
+ * { "MESSAGE_ID", "fcfb2e1e65c3494386b74878f1abf893", -1 },
+ * { "MY_APPLICATION_CUSTOM_FIELD", "some debug string", -1 },
+ * { "MY_APPLICATION_STATE", state_object, 0 },
+ * };
+ * g_log_structured_array (G_LOG_LEVEL_DEBUG, fields, G_N_ELEMENTS (fields));
+ * ]|
+ *
+ * Note also that, even if no structured fields are specified, the key-value
+ * part of the argument list must be %NULL-terminated.
+ *
+ * The default writer function for `stdout` and `stderr` will automatically
+ * append a new-line character after the message, so you should not add one
+ * manually to the format string.
+ *
+ * Since: 2.50
+ */
+
+
+/**
+ * g_log_structured_array:
+ * @log_level: log level, either from #GLogLevelFlags, or a user-defined
+ * level
+ * @fields: (array length=n_fields): key–value pairs of structured data to add
+ * to the log message
+ * @n_fields: number of elements in the @fields array
+ *
+ * Log a message with structured data. The message will be passed through to 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
+ * be aborted at the end of this function.
+ *
+ * See g_log_structured() for more documentation.
+ *
+ * This assumes that @log_level is already present in @fields (typically as the
+ * `PRIORITY` field).
+ *
+ * Since: 2.50
+ */
+
+
+/**
+ * g_log_writer_default:
+ * @log_level: log level, either from #GLogLevelFlags, or a user-defined
+ * level
+ * @fields: (array length=n_fields): key–value pairs of structured data forming
+ * the log message
+ * @n_fields: number of elements in the @fields array
+ * @user_data: user data passed to g_log_set_writer_func()
+ *
+ * Format a structured log message and output it to the default log destination
+ * for the platform. On Linux, this is typically the systemd journal, falling
+ * back to `stdout` or `stderr` if running from the terminal or if output is
+ * being redirected to a file.
+ *
+ * Support for other platform-specific logging mechanisms may be added in
+ * future. Distributors of GLib may modify this function to impose their own
+ * (documented) platform-specific log writing policies.
+ *
+ * This is suitable for use as a #GLogWriterFunc, and is the default writer used
+ * if no other is set using g_log_set_writer_func().
+ *
+ * Returns: %G_LOG_WRITER_HANDLED on success, %G_LOG_WRITER_UNHANDLED otherwise
+ * Since: 2.50
+ */
+
+
+/**
+ * g_log_writer_format_fields:
+ * @log_level: log level, either from #GLogLevelFlags, or a user-defined
+ * level
+ * @fields: (array length=n_fields): key–value pairs of structured data forming
+ * the log message
+ * @n_fields: number of elements in the @fields array
+ * @use_color: %TRUE to use ANSI color escape sequences when formatting the
+ * message, %FALSE to not
+ *
+ * Format a structured log message as a string suitable for outputting to the
+ * terminal (or elsewhere). This will include the values of all fields it knows
+ * how to interpret, which includes `MESSAGE` and `GLIB_DOMAIN` (see the
+ * documentation for g_log_structured()). It does not include values from
+ * unknown fields.
+ *
+ * The returned string does **not** have a trailing new-line character. It is
+ * encoded in the character set of the current locale, which is not necessarily
+ * UTF-8.
+ *
+ * Returns: (transfer full): string containing the formatted log message, in
+ * the character set of the current locale
+ * Since: 2.50
+ */
+
+
+/**
+ * g_log_writer_is_journald:
+ * @output_fd: output file descriptor to check
+ *
+ * Check whether the given @output_fd file descriptor is a connection to the
+ * systemd journal, or something else (like a log file or `stdout` or
+ * `stderr`).
+ *
+ * Returns: %TRUE if @output_fd points to the journal, %FALSE otherwise
+ * Since: 2.50
+ */
+
+
+/**
+ * g_log_writer_journald:
+ * @log_level: log level, either from #GLogLevelFlags, or a user-defined
+ * level
+ * @fields: (array length=n_fields): key–value pairs of structured data forming
+ * the log message
+ * @n_fields: number of elements in the @fields array
+ * @user_data: user data passed to g_log_set_writer_func()
+ *
+ * Format a structured log message and send it to the systemd journal as a set
+ * of key–value pairs. All fields are sent to the journal, but if a field has
+ * length zero (indicating program-specific data) then only its key will be
+ * sent.
+ *
+ * This is suitable for use as a #GLogWriterFunc.
+ *
+ * If GLib has been compiled without systemd support, this function is still
+ * defined, but will always return %G_LOG_WRITER_UNHANDLED.
+ *
+ * Returns: %G_LOG_WRITER_HANDLED on success, %G_LOG_WRITER_UNHANDLED otherwise
+ * Since: 2.50
+ */
+
+
+/**
+ * g_log_writer_standard_streams:
+ * @log_level: log level, either from #GLogLevelFlags, or a user-defined
+ * level
+ * @fields: (array length=n_fields): key–value pairs of structured data forming
+ * the log message
+ * @n_fields: number of elements in the @fields array
+ * @user_data: user data passed to g_log_set_writer_func()
+ *
+ * Format a structured log message and print it to either `stdout` or `stderr`,
+ * depending on its log level. %G_LOG_LEVEL_INFO and %G_LOG_LEVEL_DEBUG messages
+ * are sent to `stdout`; all other log levels are sent to `stderr`. Only fields
+ * which are understood by this function are included in the formatted string
+ * which is printed.
+ *
+ * If the output stream supports ANSI color escape sequences, they will be used
+ * in the output.
+ *
+ * A trailing new-line character is added to the log message when it is printed.
+ *
+ * This is suitable for use as a #GLogWriterFunc.
+ *
+ * Returns: %G_LOG_WRITER_HANDLED on success, %G_LOG_WRITER_UNHANDLED otherwise
+ * Since: 2.50
+ */
+
+
+/**
+ * g_log_writer_supports_color:
+ * @output_fd: output file descriptor to check
+ *
+ * Check whether the given @output_fd file descriptor supports ANSI color
+ * escape sequences. If so, they can safely be used when formatting log
+ * messages.
+ *
+ * Returns: %TRUE if ANSI color escapes are supported, %FALSE otherwise
+ * Since: 2.50
+ */
+
+
+/**
* g_logv:
* @log_domain: (nullable): the log domain, or %NULL for the default ""
* application domain
/**
* g_lstat:
- * @filename: a pathname in the GLib file name encoding (UTF-8 on Windows)
+ * @filename: (type filename): a pathname in the GLib file name encoding
+ * (UTF-8 on Windows)
* @buf: a pointer to a stat struct, which will be filled with the file
* information
*
* Normally you would call this function shortly after creating a new
* thread, passing it a #GMainContext which will be run by a
* #GMainLoop in that thread, to set a new default context for all
- * async operations in that thread. (In this case, you don't need to
- * ever call g_main_context_pop_thread_default().) In some cases
- * however, you may want to schedule a single operation in a
+ * async operations in that thread. In this case you may not need to
+ * ever call g_main_context_pop_thread_default(), assuming you want the
+ * new #GMainContext to be the default for the whole lifecycle of the
+ * thread.
+ *
+ * If you don't have control over how the new thread was created (e.g.
+ * in the new thread isn't newly created, or if the thread life
+ * cycle is managed by a #GThreadPool), it is always suggested to wrap
+ * the logic that needs to use the new #GMainContext inside a
+ * g_main_context_push_thread_default() / g_main_context_pop_thread_default()
+ * pair, otherwise threads that are re-used will end up never explicitly
+ * releasing the #GMainContext reference they hold.
+ *
+ * In some cases you may want to schedule a single operation in a
* non-default context, or temporarily use a non-default context in
* the main thread. In that case, you can wrap the call to the
* asynchronous operation inside a
/**
* g_mapped_file_new:
- * @filename: The path of the file to load, in the GLib filename encoding
+ * @filename: (type filename): The path of the file to load, in the GLib
+ * filename encoding
* @writable: whether the mapping should be writable
* @error: return location for a #GError, or %NULL
*
/**
* g_mkdir:
- * @filename: a pathname in the GLib file name encoding (UTF-8 on Windows)
+ * @filename: (type filename): a pathname in the GLib file name encoding
+ * (UTF-8 on Windows)
* @mode: permissions to use for the newly created directory
*
* A wrapper for the POSIX mkdir() function. The mkdir() function
/**
* g_mkdir_with_parents:
- * @pathname: a pathname in the GLib file name encoding
+ * @pathname: (type filename): a pathname in the GLib file name encoding
* @mode: permissions to use for newly created directories
*
* Create a directory if it doesn't already exist. Create intermediate
* The string should be in the GLib file name encoding. Most importantly,
* on Windows it should be in UTF-8.
*
- * Returns: A pointer to @tmpl, which has been modified
- * to hold the directory name. In case of errors, %NULL is
+ * Returns: (nullable) (type filename): A pointer to @tmpl, which has been
+ * modified to hold the directory name. In case of errors, %NULL is
* returned and %errno will be set.
* Since: 2.30
*/
* in the GLib file name encoding. Most importantly, on Windows it
* should be in UTF-8.
*
- * Returns: A pointer to @tmpl, which has been modified
- * to hold the directory name. In case of errors, %NULL is
+ * Returns: (nullable) (type filename): A pointer to @tmpl, which has been
+ * modified to hold the directory name. In case of errors, %NULL is
* returned, and %errno will be set.
* Since: 2.30
*/
/**
* g_open:
- * @filename: a pathname in the GLib file name encoding (UTF-8 on Windows)
+ * @filename: (type filename): a pathname in the GLib file name encoding
+ * (UTF-8 on Windows)
* @flags: as in open()
* @mode: as in open()
*
/**
* g_path_get_basename:
- * @file_name: the name of the file
+ * @file_name: (type filename): the name of the file
*
* Gets the last component of the filename.
*
* separators (and on Windows, possibly a drive letter), a single
* separator is returned. If @file_name is empty, it gets ".".
*
- * Returns: a newly allocated string containing the last
+ * Returns: (type filename): a newly allocated string containing the last
* component of the filename
*/
/**
* g_path_get_dirname:
- * @file_name: the name of the file
+ * @file_name: (type filename): the name of the file
*
* Gets the directory components of a file name.
*
* If the file name has no directory components "." is returned.
* The returned string should be freed when no longer needed.
*
- * Returns: the directory components of the file
+ * Returns: (type filename): the directory components of the file
*/
/**
* g_path_is_absolute:
- * @file_name: a file name
+ * @file_name: (type filename): a file name
*
* Returns %TRUE if the given @file_name is an absolute file name.
* Note that this is a somewhat vague concept on Windows.
/**
* g_path_skip_root:
- * @file_name: a file name
+ * @file_name: (type filename): a file name
*
* Returns a pointer into @file_name after the root component,
* i.e. after the "/" in UNIX or "C:\" under Windows. If @file_name
* is not an absolute path it returns %NULL.
*
- * Returns: (nullable): a pointer into @file_name after the root component
+ * Returns: (type filename) (nullable): a pointer into @file_name after the
+ * root component
*/
/**
* g_remove:
- * @filename: a pathname in the GLib file name encoding (UTF-8 on Windows)
+ * @filename: (type filename): a pathname in the GLib file name encoding
+ * (UTF-8 on Windows)
*
* A wrapper for the POSIX remove() function. The remove() function
* deletes a name from the filesystem.
/**
* g_rename:
- * @oldfilename: a pathname in the GLib file name encoding (UTF-8 on Windows)
- * @newfilename: a pathname in the GLib file name encoding
+ * @oldfilename: (type filename): a pathname in the GLib file name encoding
+ * (UTF-8 on Windows)
+ * @newfilename: (type filename): a pathname in the GLib file name encoding
*
* A wrapper for the POSIX rename() function. The rename() function
* renames a file, moving it between directories if required.
/**
* g_rmdir:
- * @filename: a pathname in the GLib file name encoding (UTF-8 on Windows)
+ * @filename: (type filename): a pathname in the GLib file name encoding
+ * (UTF-8 on Windows)
*
* A wrapper for the POSIX rmdir() function. The rmdir() function
* deletes a directory from the filesystem.
/**
* g_spawn_async:
- * @working_directory: (allow-none): child's current working directory, or %NULL to inherit parent's
+ * @working_directory: (type filename) (allow-none): child's current working directory, or %NULL to inherit parent's
* @argv: (array zero-terminated=1): child's argument vector
* @envp: (array zero-terminated=1) (allow-none): child's environment, or %NULL to inherit parent's
* @flags: flags from #GSpawnFlags
/**
* g_spawn_async_with_pipes:
- * @working_directory: (allow-none): child's current working directory, or %NULL to inherit parent's, in the GLib file name encoding
+ * @working_directory: (type filename) (allow-none): child's current working directory, or %NULL to inherit parent's, in the GLib file name encoding
* @argv: (array zero-terminated=1): child's argument vector, in the GLib file name encoding
* @envp: (array zero-terminated=1) (allow-none): child's environment, or %NULL to inherit parent's, in the GLib file name encoding
* @flags: flags from #GSpawnFlags
/**
* g_spawn_sync:
- * @working_directory: (allow-none): child's current working directory, or %NULL to inherit parent's
+ * @working_directory: (type filename) (allow-none): child's current working directory, or %NULL to inherit parent's
* @argv: (array zero-terminated=1): child's argument vector
* @envp: (array zero-terminated=1) (allow-none): child's environment, or %NULL to inherit parent's
* @flags: flags from #GSpawnFlags
/**
* g_stat:
- * @filename: a pathname in the GLib file name encoding (UTF-8 on Windows)
+ * @filename: (type filename): a pathname in the GLib file name encoding
+ * (UTF-8 on Windows)
* @buf: a pointer to a stat struct, which will be filled with the file
* information
*
* @exceptions: (nullable): a string of characters not to escape in @source
*
* Escapes the special characters '\b', '\f', '\n', '\r', '\t', '\v', '\'
- * and '"' in the string @source by inserting a '\' before
+ * and '"' in the string @source by inserting a '\' before
* them. Additionally all characters in the range 0x01-0x1F (everything
* below SPACE) and in the range 0x7F-0xFF (all non-ASCII chars) are
* replaced with a '\' followed by their octal representation.
* optional @separator inserted between each of them. The returned string
* should be freed with g_free().
*
+ * If @str_array has no items, the return value will be an
+ * empty string. If @str_array contains a single item, @separator will not
+ * appear in the resulting string.
+ *
* Returns: a newly-allocated string containing all of the strings joined
* together, with @separator between them
*/
* This is approximately the same as calling g_test_build_filename("."),
* but you don't need to free the return value.
*
- * Returns: the path of the directory, owned by GLib
+ * Returns: (type filename): the path of the directory, owned by GLib
* Since: 2.38
*/
*
* This handler has no effect on g_error messages.
*
+ * This handler also has no effect on structured log messages (using
+ * g_log_structured() or g_log_structured_array()). To change the fatal
+ * behaviour for specific log messages, programs must install a custom log
+ * writer function using g_log_set_writer_func().
+ *
* Since: 2.22
*/
/**
* g_unlink:
- * @filename: a pathname in the GLib file name encoding (UTF-8 on Windows)
+ * @filename: (type filename): a pathname in the GLib file name encoding
+ * (UTF-8 on Windows)
*
* A wrapper for the POSIX unlink() function. The unlink() function
* deletes a name from the filesystem. If this was the last link to the
/**
* g_utime:
- * @filename: a pathname in the GLib file name encoding (UTF-8 on Windows)
+ * @filename: (type filename): a pathname in the GLib file name encoding
+ * (UTF-8 on Windows)
* @utb: a pointer to a struct utimbuf.
*
* A wrapper for the POSIX utime() function. The utime() function
* It is not permissible to use @builder in any way after this call
* except for reference counting operations (in the case of a
* heap-allocated #GVariantBuilder) or by reinitialising it with
- * g_variant_builder_init() (in the case of stack-allocated).
+ * g_variant_builder_init() (in the case of stack-allocated). This
+ * means that for the stack-allocated builders there is no need to
+ * call g_variant_builder_clear() after the call to
+ * g_variant_builder_end().
*
* It is an error to call this function in any way that would create an
* inconsistent value to be constructed (ie: insufficient number of
* the last byte then the returned string is the string, up to the first
* such nul character.
*
+ * g_variant_get_fixed_array() should be used instead if the array contains
+ * arbitrary data that could not be nul-terminated or could contain nul bytes.
+ *
* It is an error to call this function with a @value that is not an
* array of bytes.
*
projects / platform / upstream / gobject-introspection.git / blobdiff