From 1db35a9f754920ba67514ff904178fb0e5a98e22 Mon Sep 17 00:00:00 2001 From: Rico Tzschichholz Date: Mon, 13 Nov 2017 09:09:12 +0100 Subject: gir: Update annotations from GLib git master --- gir/gio-2.0.c | 277 ++++++++++++++++++++++++++++++++++++++--------------- gir/glib-2.0.c | 279 ++++++++++++++++++++++++++++++++++++++++-------------- gir/gobject-2.0.c | 4 +- 3 files changed, 412 insertions(+), 148 deletions(-) diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c index 615e4966..24bbb321 100644 --- a/gir/gio-2.0.c +++ b/gir/gio-2.0.c @@ -1654,7 +1654,7 @@ * * The certificate database to use when verifying this TLS connection. * If no certificate database is set, then the default database will be - * used. See g_dtls_backend_get_default_database(). + * used. See g_tls_backend_get_default_database(). * * Since: 2.48 */ @@ -5454,13 +5454,16 @@ * which are chained together by a #GAsyncReadyCallback. To begin * an asynchronous operation, provide a #GAsyncReadyCallback to the * asynchronous function. This callback will be triggered when the - * operation has completed, and will be passed a #GAsyncResult instance - * filled with the details of the operation's success or failure, the - * object the asynchronous function was started for and any error codes - * returned. The asynchronous callback function is then expected to call - * the corresponding "_finish()" function, passing the object the - * function was called for, the #GAsyncResult instance, and (optionally) - * an @error to grab any error conditions that may have occurred. + * operation has completed, and must be run in a later iteration of + * the [thread-default main context][g-main-context-push-thread-default] + * from where the operation was initiated. It will be passed a + * #GAsyncResult instance filled with the details of the operation's + * success or failure, the object the asynchronous function was + * started for and any error codes returned. The asynchronous callback + * function is then expected to call the corresponding "_finish()" + * function, passing the object the function was called for, the + * #GAsyncResult instance, and (optionally) an @error to grab any + * error conditions that may have occurred. * * The "_finish()" function for an operation takes the generic result * (of type #GAsyncResult) and returns the specific result that the @@ -6487,6 +6490,7 @@ * - g_file_new_for_commandline_arg() for a command line argument. * - g_file_new_tmp() to create a temporary file from a template. * - g_file_parse_name() from a UTF-8 string gotten from g_file_get_parse_name(). + * - g_file_new_build_filename() to create a file from path elements. * * One way to think of a #GFile is as an abstraction of a pathname. For * normal files the system pathname is what is stored internally, but as @@ -7393,9 +7397,9 @@ * g_mount_unmount_with_operation() with (at least) the #GMount instance and a * #GAsyncReadyCallback. The callback will be fired when the * operation has resolved (either with success or failure), and a - * #GAsyncReady structure will be passed to the callback. That + * #GAsyncResult structure will be passed to the callback. That * callback should then call g_mount_unmount_with_operation_finish() with the #GMount - * and the #GAsyncReady data to see if the operation was completed + * and the #GAsyncResult data to see if the operation was completed * successfully. If an @error is present when g_mount_unmount_with_operation_finish() * is called, then it will be filled with any error information. */ @@ -8251,12 +8255,12 @@ * implementations must carefully adhere to the expectations of * callers that are documented on each of the interface methods. * - * Some of the GSettingsBackend functions accept or return a #GTree. + * Some of the #GSettingsBackend functions accept or return a #GTree. * These trees always have strings as keys and #GVariant as values. * g_settings_backend_create_tree() is a convenience function to create * suitable trees. * - * The GSettingsBackend API is exported to allow third-party + * The #GSettingsBackend API is exported to allow third-party * implementations, but does not carry the same stability guarantees * as the public GIO API. For this reason, you have to define the * C preprocessor symbol %G_SETTINGS_ENABLE_BACKEND before including @@ -8444,9 +8448,10 @@ * from the point where it is called. g_simple_async_result_complete_in_idle() * will finish it from an idle handler in the * [thread-default main context][g-main-context-push-thread-default] - * . g_simple_async_result_run_in_thread() will run the - * job in a separate thread and then deliver the result to the - * thread-default main context. + * where the #GSimpleAsyncResult was created. + * g_simple_async_result_run_in_thread() will run the job in a + * separate thread and then use + * g_simple_async_result_complete_in_idle() to deliver the result. * * To set the results of an asynchronous function, * g_simple_async_result_set_op_res_gpointer(), @@ -9021,11 +9026,13 @@ * Eventually, you will call a method such as * g_task_return_pointer() or g_task_return_error(), which will * save the value you give it and then invoke the task's callback - * function (waiting until the next iteration of the main - * loop first, if necessary). The caller will pass the #GTask back - * to the operation's finish function (as a #GAsyncResult), and - * you can use g_task_propagate_pointer() or the like to extract - * the return value. + * function in the + * [thread-default main context][g-main-context-push-thread-default] + * where it was created (waiting until the next iteration of the main + * loop first, if necessary). The caller will pass the #GTask back to + * the operation's finish function (as a #GAsyncResult), and you can + * can use g_task_propagate_pointer() or the like to extract the + * return value. * * Here is an example for using GTask as a GAsyncResult: * |[ @@ -9264,9 +9271,10 @@ * ## Asynchronous operations from synchronous ones * * You can use g_task_run_in_thread() to turn a synchronous - * operation into an asynchronous one, by running it in a thread - * which will then dispatch the result back to the caller's - * #GMainContext when it completes. + * operation into an asynchronous one, by running it in a thread. + * When it completes, the result will be dispatched to the + * [thread-default main context][g-main-context-push-thread-default] + * where the #GTask was created. * * Running a task in a thread: * |[ @@ -9478,7 +9486,7 @@ * whether the task's callback can be invoked directly, or * if it needs to be sent to another #GMainContext, or delayed * until the next iteration of the current #GMainContext.) - * - The "finish" functions for #GTask-based operations are generally + * - The "finish" functions for #GTask based operations are generally * much simpler than #GSimpleAsyncResult ones, normally consisting * of only a single call to g_task_propagate_pointer() or the like. * Since g_task_propagate_pointer() "steals" the return value from @@ -12500,7 +12508,7 @@ /** * g_app_info_create_from_commandline: - * @commandline: the commandline to use + * @commandline: (type filename): the commandline to use * @application_name: (nullable): the application name, or %NULL to use @commandline * @flags: flags that can specify details of the created #GAppInfo * @error: a #GError location to store the error occurring, %NULL to ignore. @@ -12549,9 +12557,9 @@ * * Checks if two #GAppInfos are equal. * - * Note that the check may not compare each individual field, and - * only does an identity check. In case detecting changes in the contents - * is needed, program code must additionally compare relevant fields. + * Note that the check may not compare each individual + * field, and only does an identity check. In case detecting changes in the + * contents is needed, program code must additionally compare relevant fields. * * Returns: %TRUE if @appinfo1 is equal to @appinfo2. %FALSE otherwise. */ @@ -12750,11 +12758,11 @@ * g_app_info_launch: * @appinfo: a #GAppInfo * @files: (nullable) (element-type GFile): a #GList of #GFile objects - * @launch_context: (nullable): a #GAppLaunchContext or %NULL + * @context: (nullable): a #GAppLaunchContext or %NULL * @error: a #GError * * Launches the application. Passes @files to the launched application - * as arguments, using the optional @launch_context to get information + * as arguments, using the optional @context to get information * about the details of the launcher (like what screen it is on). * On error, @error will be set accordingly. * @@ -12779,7 +12787,7 @@ * process. This can be used to ignore `GIO_LAUNCHED_DESKTOP_FILE`, * should it be inherited by further processes. The `DISPLAY` and * `DESKTOP_STARTUP_ID` environment variables are also set, based - * on information provided in @launch_context. + * on information provided in @context. * * Returns: %TRUE on successful launch, %FALSE otherwise. */ @@ -12788,7 +12796,7 @@ /** * g_app_info_launch_default_for_uri: * @uri: the uri to show - * @launch_context: (nullable): an optional #GAppLaunchContext + * @context: (nullable): an optional #GAppLaunchContext * @error: (nullable): return location for an error, or %NULL * * Utility function that launches the default application @@ -12804,7 +12812,7 @@ * g_app_info_launch_default_for_uri_async: * @uri: the uri to show * @context: (nullable): an optional #GAppLaunchContext - * cancellable: (nullable): a #GCancellable + * @cancellable: (nullable): a #GCancellable * @callback: (nullable): a #GASyncReadyCallback to call when the request is done * @user_data: (nullable): data to pass to @callback * @@ -12835,11 +12843,11 @@ * g_app_info_launch_uris: * @appinfo: a #GAppInfo * @uris: (nullable) (element-type utf8): a #GList containing URIs to launch. - * @launch_context: (nullable): a #GAppLaunchContext or %NULL + * @context: (nullable): a #GAppLaunchContext or %NULL * @error: a #GError * * Launches the application. This passes the @uris to the launched application - * as arguments, using the optional @launch_context to get information + * as arguments, using the optional @context to get information * about the details of the launcher (like what screen it is on). * On error, @error will be set accordingly. * @@ -12991,8 +12999,8 @@ * This is a %NULL-terminated array of strings, where each string has * the form `KEY=VALUE`. * - * Returns: (array zero-terminated=1) (transfer full): the - * child's environment + * Returns: (array zero-terminated=1) (element-type filename) (transfer full): + * the child's environment * Since: 2.32 */ @@ -13037,8 +13045,8 @@ /** * g_app_launch_context_setenv: * @context: a #GAppLaunchContext - * @variable: the environment variable to set - * @value: the value for to set the variable to. + * @variable: (type filename): the environment variable to set + * @value: (type filename): the value for to set the variable to. * * Arranges for @variable to be set to @value in the child's * environment when @context is used to launch an application. @@ -13050,7 +13058,7 @@ /** * g_app_launch_context_unsetenv: * @context: a #GAppLaunchContext - * @variable: the environment variable to remove + * @variable: (type filename): the environment variable to remove * * Arranges for @variable to be unset in the child's environment * when @context is used to launch an application. @@ -13223,7 +13231,7 @@ /** * g_application_command_line_create_file_for_arg: * @cmdline: a #GApplicationCommandLine - * @arg: an argument from @cmdline + * @arg: (type filename): an argument from @cmdline * * Creates a #GFile corresponding to a filename that was given as part * of the invocation of @cmdline. @@ -13254,8 +13262,8 @@ * The return value is %NULL-terminated and should be freed using * g_strfreev(). * - * Returns: (array length=argc) (transfer full): the string array - * containing the arguments (the argv) + * Returns: (array length=argc) (element-type filename) (transfer full): + * the string array containing the arguments (the argv) * Since: 2.28 */ @@ -13298,8 +13306,8 @@ * See g_application_command_line_getenv() if you are only interested * in the value of a single environment variable. * - * Returns: (array zero-terminated=1) (transfer none): the environment - * strings, or %NULL if they were not sent + * Returns: (array zero-terminated=1) (element-type filename) (transfer none): + * the environment strings, or %NULL if they were not sent * Since: 2.28 */ @@ -13387,7 +13395,7 @@ /** * g_application_command_line_getenv: * @cmdline: a #GApplicationCommandLine - * @name: the environment variable to get + * @name: (type filename): the environment variable to get * * Gets the value of a particular environment variable of the command * line invocation, as would be returned by g_getenv(). The strings may @@ -13818,7 +13826,8 @@ * g_application_run: * @application: a #GApplication * @argc: the argc from main() (or 0 if @argv is %NULL) - * @argv: (array length=argc) (nullable): the argv from main(), or %NULL + * @argv: (array length=argc) (element-type filename) (nullable): + * the argv from main(), or %NULL * * Runs the application. * @@ -14389,7 +14398,7 @@ * * Finishes an asynchronous read. * - * Returns: a #gssize of the read stream, or %-1 on an error. + * Returns: a #gssize of the read stream, or `-1` on an error. */ @@ -14964,7 +14973,7 @@ /** * g_cancellable_disconnect: * @cancellable: (nullable): A #GCancellable or %NULL. - * @handler_id: Handler id of the handler to be disconnected, or %0. + * @handler_id: Handler id of the handler to be disconnected, or `0`. * * Disconnects a handler from a cancellable instance similar to * g_signal_handler_disconnect(). Additionally, in the event that a @@ -14978,7 +14987,7 @@ * signal handler is removed. See #GCancellable::cancelled for * details on how to use this. * - * If @cancellable is %NULL or @handler_id is %0 this function does + * If @cancellable is %NULL or @handler_id is `0` this function does * nothing. * * Since: 2.22 @@ -16524,10 +16533,10 @@ * Escape @string so it can appear in a D-Bus address as the value * part of a key-value pair. * - * For instance, if @string is "/run/bus-for-:0", - * this function would return "/run/bus-for-%3A0", + * For instance, if @string is `/run/bus-for-:0`, + * this function would return `/run/bus-for-%3A0`, * which could be used in a D-Bus address like - * "unix:nonce-tcp:host=127.0.0.1,port=42,noncefile=/run/bus-for-%3A0". + * `unix:nonce-tcp:host=127.0.0.1,port=42,noncefile=/run/bus-for-%3A0`. * * Returns: (transfer full): a copy of @string with all * non-optionally-escaped bytes escaped @@ -21880,7 +21889,7 @@ * * Sets the certificate database that is used to verify peer certificates. * This is set to the default database by default. See - * g_dtls_backend_get_default_database(). If set to %NULL, then + * g_tls_backend_get_default_database(). If set to %NULL, then * peer certificate validation will always set the * %G_TLS_CERTIFICATE_UNKNOWN_CA error (meaning * #GDtlsConnection::accept-certificate will always be emitted on @@ -24923,9 +24932,25 @@ */ +/** + * g_file_new_build_filename: + * @first_element: (type filename): the first element in the path + * @...: remaining elements in path, terminated by %NULL + * + * Constructs a #GFile from a series of elements using the correct + * separator for filenames. + * + * Using this function is equivalent to calling g_build_filename(), + * followed by g_file_new_for_path() on the result. + * + * Returns: (transfer full): a new #GFile + * Since: 2.56 + */ + + /** * g_file_new_for_commandline_arg: - * @arg: a command line string + * @arg: (type filename): a command line string * * Creates a #GFile with the given argument from the command line. * The value of @arg can be either a URI, an absolute path or a @@ -24949,7 +24974,7 @@ /** * g_file_new_for_commandline_arg_and_cwd: - * @arg: a command line string + * @arg: (type filename): a command line string * @cwd: (type filename): the current working directory of the commandline * * Creates a #GFile with the given argument from the command line. @@ -32705,7 +32730,8 @@ * g_seekable_can_truncate: * @seekable: a #GSeekable. * - * Tests if the stream can be truncated. + * Tests if the length of the stream can be adjusted with + * g_seekable_truncate(). * * Returns: %TRUE if the stream can be truncated, %FALSE otherwise. */ @@ -32754,12 +32780,14 @@ /** * g_seekable_truncate: (virtual truncate_fn) * @seekable: a #GSeekable. - * @offset: a #goffset. + * @offset: new length for @seekable, in bytes. * @cancellable: (nullable): optional #GCancellable object, %NULL to ignore. * @error: a #GError location to store the error occurring, or %NULL to * ignore. * - * Truncates a stream with a given #offset. + * Sets the length of the stream to @offset. If the stream was previously + * larger than @offset, the extra data is discarded. If the stream was + * previouly shorter than @offset, it is extended with NUL ('\0') bytes. * * If @cancellable is not %NULL, then the operation can be cancelled by * triggering the cancellable object from another thread. If the operation @@ -32984,7 +33012,7 @@ * a boolean property by that name). See g_settings_bind_writable() * for more details about writable bindings. * - * Note that the lifecycle of the binding is tied to the object, + * Note that the lifecycle of the binding is tied to @object, * and that you can have only one binding per object property. * If you bind the same property twice on the same object, the second * binding overrides the first one. @@ -33013,7 +33041,7 @@ * The binding uses the provided mapping functions to map between * settings and property values. * - * Note that the lifecycle of the binding is tied to the object, + * Note that the lifecycle of the binding is tied to @object, * and that you can have only one binding per object property. * If you bind the same property twice on the same object, the second * binding overrides the first one. @@ -33043,7 +33071,7 @@ * value as it passes from the setting to the object, i.e. @property * will be set to %TRUE if the key is not writable. * - * Note that the lifecycle of the binding is tied to the object, + * Note that the lifecycle of the binding is tied to @object, * and that you can have only one binding per object property. * If you bind the same property twice on the same object, the second * binding overrides the first one. @@ -36508,11 +36536,44 @@ * in RFC 4604 is used. Note that on older platforms this may fail * with a %G_IO_ERROR_NOT_SUPPORTED error. * + * To bind to a given source-specific multicast address, use + * g_socket_join_multicast_group_ssm() instead. + * * Returns: %TRUE on success, %FALSE on error. * Since: 2.32 */ +/** + * g_socket_join_multicast_group_ssm: + * @socket: a #GSocket. + * @group: a #GInetAddress specifying the group address to join. + * @source_specific: (nullable): a #GInetAddress specifying the + * source-specific multicast address or %NULL to ignore. + * @iface: (nullable): Name of the interface to use, or %NULL + * @error: #GError for error reporting, or %NULL to ignore. + * + * Registers @socket to receive multicast messages sent to @group. + * @socket must be a %G_SOCKET_TYPE_DATAGRAM socket, and must have + * been bound to an appropriate interface and port with + * g_socket_bind(). + * + * If @iface is %NULL, the system will automatically pick an interface + * to bind to based on @group. + * + * If @source_specific is not %NULL, use source-specific multicast as + * defined in RFC 4604. Note that on older platforms this may fail + * with a %G_IO_ERROR_NOT_SUPPORTED error. + * + * Note that this function can be called multiple times for the same + * @group with different @source_specific in order to receive multicast + * packets from more than one source. + * + * Returns: %TRUE on success, %FALSE on error. + * Since: 2.56 + */ + + /** * g_socket_leave_multicast_group: * @socket: a #GSocket. @@ -36528,11 +36589,35 @@ * @socket remains bound to its address and port, and can still receive * unicast messages after calling this. * + * To unbind to a given source-specific multicast address, use + * g_socket_leave_multicast_group_ssm() instead. + * * Returns: %TRUE on success, %FALSE on error. * Since: 2.32 */ +/** + * g_socket_leave_multicast_group_ssm: + * @socket: a #GSocket. + * @group: a #GInetAddress specifying the group address to leave. + * @source_specific: (nullable): a #GInetAddress specifying the + * source-specific multicast address or %NULL to ignore. + * @iface: (nullable): Name of the interface to use, or %NULL + * @error: #GError for error reporting, or %NULL to ignore. + * + * Removes @socket from the multicast group defined by @group, @iface, + * and @source_specific (which must all have the same values they had + * when you joined the group). + * + * @socket remains bound to its address and port, and can still receive + * unicast messages after calling this. + * + * Returns: %TRUE on success, %FALSE on error. + * Since: 2.56 + */ + + /** * g_socket_listen: * @socket: a #GSocket. @@ -37998,7 +38083,7 @@ /** * g_subprocess_launcher_getenv: * @self: a #GSubprocess - * @variable: the environment variable to get + * @variable: (type filename): the environment variable to get * * Returns the value of the environment variable @variable in the * environment of processes launched from this launcher. @@ -38006,7 +38091,8 @@ * On UNIX, the returned string can be an arbitrary byte string. * On Windows, it will be UTF-8. * - * Returns: the value of the environment variable, %NULL if unset + * Returns: (type filename): the value of the environment variable, + * %NULL if unset * Since: 2.40 */ @@ -38068,7 +38154,8 @@ /** * g_subprocess_launcher_set_environ: * @self: a #GSubprocess - * @env: (array zero-terminated=1) (transfer none): the replacement environment + * @env: (array zero-terminated=1) (element-type filename) (transfer none): + * the replacement environment * * Replace the entire environment of processes launched from this * launcher with the given 'environ' variable. @@ -38184,8 +38271,9 @@ /** * g_subprocess_launcher_setenv: * @self: a #GSubprocess - * @variable: the environment variable to set, must not contain '=' - * @value: the new value for the variable + * @variable: (type filename): the environment variable to set, + * must not contain '=' + * @value: (type filename): the new value for the variable * @overwrite: whether to change the variable if it already exists * * Sets the environment variable @variable in the environment of @@ -38216,7 +38304,7 @@ /** * g_subprocess_launcher_spawnv: * @self: a #GSubprocessLauncher - * @argv: (array zero-terminated=1) (element-type utf8): Command line arguments + * @argv: (array zero-terminated=1) (element-type filename): Command line arguments * @error: Error * * Creates a #GSubprocess given a provided array of arguments. @@ -38331,7 +38419,8 @@ /** * g_subprocess_launcher_unsetenv: * @self: a #GSubprocess - * @variable: the environment variable to unset, must not contain '=' + * @variable: (type filename): the environment variable to unset, + * must not contain '=' * * Removes the environment variable @variable from the environment of * processes launched from this launcher. @@ -38366,7 +38455,7 @@ /** * g_subprocess_newv: (rename-to g_subprocess_new) - * @argv: (array zero-terminated=1) (element-type utf8): commandline arguments for the subprocess + * @argv: (array zero-terminated=1) (element-type filename): commandline arguments for the subprocess * @flags: flags that define the behaviour of the subprocess * @error: (nullable): return location for an error, or %NULL * @@ -40094,7 +40183,7 @@ * @error: a #GError pointer, or %NULL * * Finish an asynchronous lookup of a certificate by its handle. See - * g_tls_database_lookup_certificate_handle() for more information. + * g_tls_database_lookup_certificate_by_handle() for more information. * * If the handle is no longer valid, or does not point to a certificate in * this database, then %NULL will be returned. @@ -40232,7 +40321,7 @@ * adding any missing certificates to the chain. * * @chain is a chain of #GTlsCertificate objects each pointing to the next - * certificate in the chain by its %issuer property. The chain may initially + * certificate in the chain by its #GTlsCertificate:issuer property. The chain may initially * consist of one or more certificates. After the verification process is * complete, @chain may be modified by adding missing certificates, or removing * extra certificates. If a certificate anchor was found, then it is added to @@ -41197,6 +41286,41 @@ */ +/** + * g_unix_is_system_device_path: + * @device_path: a device path, e.g. `/dev/loop0` or `nfsd` + * + * Determines if @device_path is considered a block device path which is only + * used in implementation of the OS. This is primarily used for hiding + * mounted volumes that are intended as APIs for programs to read, and system + * administrators at a shell; rather than something that should, for example, + * appear in a GUI. For example, the Linux `/proc` filesystem. + * + * The list of device paths considered ‘system’ ones may change over time. + * + * Returns: %TRUE if @device_path is considered an implementation detail of + * the OS. + * Since: 2.56 + */ + + +/** + * g_unix_is_system_fs_type: + * @fs_type: a file system type, e.g. `procfs` or `tmpfs` + * + * Determines if @fs_type is considered a type of file system which is only + * used in implementation of the OS. This is primarily used for hiding + * mounted volumes that are intended as APIs for programs to read, and system + * administrators at a shell; rather than something that should, for example, + * appear in a GUI. For example, the Linux `/proc` filesystem. + * + * The list of file system types considered ‘system’ ones may change over time. + * + * Returns: %TRUE if @fs_type is considered an implementation detail of the OS. + * Since: 2.56 + */ + + /** * g_unix_mount_at: * @mount_path: (type filename): path for a possible unix mount. @@ -41363,7 +41487,12 @@ * g_unix_mount_is_system_internal: * @mount_entry: a #GUnixMount. * - * Checks if a unix mount is a system path. + * Checks if a Unix mount is a system mount. This is the Boolean OR of + * g_unix_is_system_fs_type(), g_unix_is_system_device_path() and + * g_unix_is_mount_path_system_internal() on @mount_entry’s properties. + * + * The definition of what a ‘system’ mount entry is may change over time as new + * file system types and device paths are ignored. * * Returns: %TRUE if the unix mount is for a system path. */ @@ -42062,7 +42191,7 @@ * then the expression * |[ * (g_file_has_prefix (volume_activation_root, mount_root) || - * g_file_equal (volume_activation_root, mount_root)) + * g_file_equal (volume_activation_root, mount_root)) * ]| * will always be %TRUE. * diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c index ce126e04..23509cf5 100644 --- a/gir/glib-2.0.c +++ b/gir/glib-2.0.c @@ -532,6 +532,8 @@ * suffixes. IEC units should only be used for reporting things with * a strong "power of 2" basis, like RAM sizes or RAID stripe sizes. * Network and storage sizes should be reported in the normal SI units. + * @G_FORMAT_SIZE_BITS: set the size as a quantity in bits, rather than + * bytes, and return units in bits. For example, ‘Mb’ rather than ‘MB’. * * Flags to modify the format of the string returned by g_format_size_full(). */ @@ -2016,7 +2018,7 @@ * * Deprecated: #GTestTrapFlags is used only with g_test_trap_fork(), * which is deprecated. g_test_trap_subprocess() uses - * #GTestTrapSubprocessFlags. + * #GTestSubprocessFlags. */ @@ -3207,6 +3209,8 @@ /** * G_GNUC_CHECK_VERSION: + * @major: major version to check against + * @minor: minor version to check against * * Expands to a a check for a compiler with __GNUC__ defined and a version * greater than or equal to the major and minor numbers provided. For example, @@ -4569,7 +4573,7 @@ * A macro to assist with the static initialisation of a #GPrivate. * * This macro is useful for the case that a #GDestroyNotify function - * should be associated the key. This is needed when the key will be + * should be associated with the key. This is needed when the key will be * used to point at memory that should be deallocated when the thread * exits. * @@ -5491,7 +5495,6 @@ * ## Checklist for Application Writers * * This section is a practical summary of the detailed - * * things to do to make sure your applications process file * name encodings correctly. * @@ -6861,6 +6864,58 @@ * multiple groups with the same name; they are merged together. * Another difference is that keys and group names in key files are not * restricted to ASCII characters. + * + * Here is an example of loading a key file and reading a value: + * |[ + * g_autoptr(GError) error = NULL; + * g_autoptr(GKeyFile) key_file = g_key_file_new (); + * + * if (!g_key_file_load_from_file (key_file, "key-file.ini", flags, &error)) + * { + * if (!g_error_matches (error, G_FILE_ERROR, G_FILE_ERROR_NOENT)) + * g_warning ("Error loading key file: %s", error->message); + * return; + * } + * + * g_autofree gchar *val = g_key_file_get_string (key_file, "Group Name", "SomeKey", &error); + * if (val == NULL && + * !g_error_matches (error, G_KEY_FILE_ERROR, G_KEY_FILE_ERROR_KEY_NOT_FOUND)) + * { + * g_warning ("Error finding key in key file: %s", error->message); + * return; + * } + * else if (val == NULL) + * { + * // Fall back to a default value. + * val = g_strdup ("default-value"); + * } + * ]| + * + * Here is an example of creating and saving a key file: + * |[ + * g_autoptr(GKeyFile) key_file = g_key_file_new (); + * const gchar *val = …; + * g_autoptr(GError) error = NULL; + * + * g_key_file_set_string (key_file, "Group Name", "SomeKey", val); + * + * // Save as a file. + * if (!g_key_file_save_to_file (key_file, "key-file.ini", &error)) + * { + * g_warning ("Error saving key file: %s", error->message); + * return; + * } + * + * // Or store to a GBytes for use elsewhere. + * gsize data_len; + * g_autofree guint8 *data = (guint8 *) g_key_file_to_data (key_file, &data_len, &error); + * if (data == NULL) + * { + * g_warning ("Error saving key file: %s", error->message); + * return; + * } + * g_autoptr(GBytes) bytes = g_bytes_new_take (g_steal_pointer (&data), data_len); + * ]| */ @@ -11594,6 +11649,20 @@ */ +/** + * g_build_filename_valist: + * @first_element: (type filename): the first element in the path + * @args: va_list of remaining elements in path + * + * Behaves exactly like g_build_filename(), but takes the path elements + * as a va_list. This function is mainly meant for language bindings. + * + * Returns: (type filename): a newly-allocated string that must be freed + * with g_free(). + * Since: 2.56 + */ + + /** * g_build_filenamev: * @args: (array zero-terminated=1) (element-type filename): %NULL-terminated @@ -11975,7 +12044,7 @@ /** * g_bytes_new_static: (skip) * @data: (transfer full) (array length=size) (element-type guint8) (nullable): - * the data to be used for the bytes + * the data to be used for the bytes * @size: the size of @data * * Creates a new #GBytes from static data. @@ -11991,7 +12060,7 @@ /** * g_bytes_new_take: * @data: (transfer full) (array length=size) (element-type guint8) (nullable): - * the data to be used for the bytes + * the data to be used for the bytes * @size: the size of @data * * Creates a new #GBytes from @data. @@ -12015,7 +12084,7 @@ /** * g_bytes_new_with_free_func: (skip) * @data: (array length=size) (element-type guint8) (nullable): - * the data to be used for the bytes + * the data to be used for the bytes * @size: the size of @data * @free_func: the function to call to release the data * @user_data: data to pass to @free_func @@ -12248,6 +12317,8 @@ * g_spawn_close_pid() in the callback function for the source. * * GLib supports only a single callback per process id. + * On POSIX platforms, the same restrictions mentioned for + * g_child_watch_source_new() apply to this function. * * This internally creates a main loop source using * g_child_watch_source_new() and attaches it to the main loop context @@ -12286,6 +12357,8 @@ * in the callback function for the source. * * GLib supports only a single callback per process id. + * On POSIX platforms, the same restrictions mentioned for + * g_child_watch_source_new() apply to this function. * * This internally creates a main loop source using * g_child_watch_source_new() and attaches it to the main loop context @@ -12316,14 +12389,24 @@ * source is still active. Typically, you will want to call * g_spawn_close_pid() in the callback function for the source. * - * Note further that using g_child_watch_source_new() is not - * compatible with calling `waitpid` with a nonpositive first - * argument in the application. Calling waitpid() for individual - * pids will still work fine. + * On POSIX platforms, the following restrictions apply to this API + * due to limitations in POSIX process interfaces: + * + * * @pid must be a child of this process + * * @pid must be positive + * * the application must not call `waitpid` with a non-positive + * first argument, for instance in another thread + * * the application must not wait for @pid to exit by any other + * mechanism, including `waitpid(pid, ...)` or a second child-watch + * source for the same @pid + * * the application must not ignore SIGCHILD * - * Similarly, on POSIX platforms, the @pid passed to this function must - * be greater than 0 (i.e. this function must wait for a specific child, - * and cannot wait for one of many children by using a nonpositive argument). + * If any of those conditions are not met, this and related APIs will + * not work correctly. This can often be diagnosed via a GLib warning + * stating that `ECHILD` was received by `waitpid`. + * + * Calling `waitpid` for specific processes other than @pid remains a + * valid thing to do. * * Returns: the newly-created child watch source * Since: 2.4 @@ -12361,6 +12444,26 @@ */ +/** + * g_clear_handle_id: (skip) + * @tag_ptr: (not nullable): a pointer to the handler ID + * @clear_func: (not nullable): the function to call to clear the handler + * + * Clears a numeric handler, such as a #GSource ID. + * + * @tag_ptr must be a valid pointer to the variable holding the handler. + * + * If the ID is zero then this function does nothing. + * Otherwise, clear_func() is called with the ID as a parameter, and the tag is + * set to zero. + * + * A macro is also included that allows this function to be used without + * pointer casts. + * + * Since: 2.56 + */ + + /** * g_clear_pointer: (skip) * @pp: (not nullable): a pointer to a variable, struct member etc. holding a @@ -12703,8 +12806,8 @@ * @fallback: UTF-8 string to use in place of character not * present in the target encoding. (The string must be * representable in the target encoding). - * If %NULL, characters not in the target encoding will - * be represented as Unicode escapes \uxxxx or \Uxxxxyyyy. + * If %NULL, characters not in the target encoding will + * be represented as Unicode escapes \uxxxx or \Uxxxxyyyy. * @bytes_read: location to store the number of bytes in the * input string that were successfully converted, or %NULL. * Even if the conversion was successful, this may be @@ -12825,7 +12928,14 @@ * * You can also make critical warnings fatal at runtime by * setting the `G_DEBUG` environment variable (see - * [Running GLib Applications](glib-running.html)). + * [Running GLib Applications](glib-running.html)): + * + * |[ + * G_DEBUG=fatal-warnings gdb ./my-program + * ]| + * + * Any unrelated failures can be skipped over in + * [gdb](https://www.gnu.org/software/gdb/) using the `continue` command. * * The message should typically *not* be translated to the * user's language. @@ -15073,15 +15183,15 @@ /** * g_environ_getenv: - * @envp: (nullable) (array zero-terminated=1) (transfer none): an environment - * list (eg, as returned from g_get_environ()), or %NULL + * @envp: (nullable) (array zero-terminated=1) (transfer none) (element-type filename): + * an environment list (eg, as returned from g_get_environ()), or %NULL * for an empty environment list - * @variable: the environment variable to get + * @variable: (type filename): the environment variable to get * * Returns the value of the environment variable @variable in the * provided list @envp. * - * Returns: the value of the environment variable, or %NULL if + * Returns: (type filename): the value of the environment variable, or %NULL if * the environment variable is not set in @envp. The returned * string is owned by @envp, and will be freed if @variable is * set or unset again. @@ -15091,35 +15201,37 @@ /** * g_environ_setenv: - * @envp: (nullable) (array zero-terminated=1) (transfer full): an - * environment list that can be freed using g_strfreev() (e.g., as + * @envp: (nullable) (array zero-terminated=1) (element-type filename) (transfer full): + * an environment list that can be freed using g_strfreev() (e.g., as * returned from g_get_environ()), or %NULL for an empty * environment list - * @variable: the environment variable to set, must not contain '=' - * @value: the value for to set the variable to + * @variable: (type filename): the environment variable to set, must not + * contain '=' + * @value: (type filename): the value for to set the variable to * @overwrite: whether to change the variable if it already exists * * Sets the environment variable @variable in the provided list * @envp to @value. * - * Returns: (array zero-terminated=1) (transfer full): the - * updated environment list. Free it using g_strfreev(). + * Returns: (array zero-terminated=1) (element-type filename) (transfer full): + * the updated environment list. Free it using g_strfreev(). * Since: 2.32 */ /** * g_environ_unsetenv: - * @envp: (nullable) (array zero-terminated=1) (transfer full): an environment - * list that can be freed using g_strfreev() (e.g., as returned from g_get_environ()), - * or %NULL for an empty environment list - * @variable: the environment variable to remove, must not contain '=' + * @envp: (nullable) (array zero-terminated=1) (element-type filename) (transfer full): + * an environment list that can be freed using g_strfreev() (e.g., as + * returned from g_get_environ()), or %NULL for an empty environment list + * @variable: (type filename): the environment variable to remove, must not + * contain '=' * * Removes the environment variable @variable from the provided * environment @envp. * - * Returns: (array zero-terminated=1) (transfer full): the - * updated environment list. Free it using g_strfreev(). + * Returns: (array zero-terminated=1) (element-type filename) (transfer full): + * the updated environment list. Free it using g_strfreev(). * Since: 2.32 */ @@ -15810,8 +15922,8 @@ * The return value is freshly allocated and it should be freed with * g_strfreev() when it is no longer needed. * - * Returns: (array zero-terminated=1) (transfer full): the list of - * environment variables + * Returns: (array zero-terminated=1) (element-type filename) (transfer full): + * the list of environment variables * Since: 2.28 */ @@ -15894,6 +16006,8 @@ * name can be determined, a default fixed string "localhost" is * returned. * + * The encoding of the returned string is UTF-8. + * * Returns: the host name of the machine. * Since: 2.8 */ @@ -16241,7 +16355,7 @@ /** * g_getenv: - * @variable: the environment variable to get + * @variable: (type filename): the environment variable to get * * Returns the value of an environment variable. * @@ -16251,7 +16365,7 @@ * On Windows, in case the environment variable's value contains * references to other environment variables, they are expanded. * - * Returns: the value of the environment variable, or %NULL if + * Returns: (type filename): the value of the environment variable, or %NULL if * the environment variable is not found. The returned string * may be overwritten by the next call to g_getenv(), g_setenv() * or g_unsetenv(). @@ -19580,8 +19694,9 @@ * use cases for environment variables in GLib-using programs you want * the UTF-8 encoding that this function and g_getenv() provide. * - * Returns: (array zero-terminated=1) (transfer full): a %NULL-terminated - * list of strings which must be freed with g_strfreev(). + * Returns: (array zero-terminated=1) (element-type filename) (transfer full): + * a %NULL-terminated list of strings which must be freed with + * g_strfreev(). * Since: 2.8 */ @@ -22738,7 +22853,7 @@ /** * g_option_context_get_strict_posix: - * @context: a #GoptionContext + * @context: a #GOptionContext * * Returns whether strict POSIX code is enabled. * @@ -22921,7 +23036,7 @@ /** * g_option_context_set_strict_posix: - * @context: a #GoptionContext + * @context: a #GOptionContext * @strict_posix: the new value * * Sets strict POSIX mode. @@ -23382,9 +23497,9 @@ * don't want to run the full main loop. * * Each element of @fds is a #GPollFD describing a single file - * descriptor to poll. The %fd field indicates the file descriptor, - * and the %events field indicates the events to poll for. On return, - * the %revents fields will be filled with the events that actually + * descriptor to poll. The @fd field indicates the file descriptor, + * and the @events field indicates the events to poll for. On return, + * the @revents fields will be filled with the events that actually * occurred. * * On POSIX systems, the file descriptors in @fds can be any sort of @@ -23393,7 +23508,7 @@ * Windows, the easiest solution is to construct all of your * #GPollFDs with g_io_channel_win32_make_pollfd(). * - * Returns: the number of entries in @fds whose %revents fields + * Returns: the number of entries in @fds whose @revents fields * were filled in, or 0 if the operation timed out, or -1 on error or * if the call was interrupted. * Since: 2.20 @@ -25586,7 +25701,8 @@ * thread will block. Read locks can be taken recursively. * * It is implementation-defined how many threads are allowed to - * hold read locks on the same lock simultaneously. + * hold read locks on the same lock simultaneously. If the limit is hit, + * or if a deadlock is detected, a critical warning will be emitted. * * Since: 2.32 */ @@ -26688,8 +26804,9 @@ /** * g_setenv: - * @variable: the environment variable to set, must not contain '='. - * @value: the value for to set the variable to. + * @variable: (type filename): the environment variable to set, must not + * contain '='. + * @value: (type filename): the value for to set the variable to. * @overwrite: whether to change the variable if it already exists. * * Sets an environment variable. On UNIX, both the variable's name and @@ -26719,10 +26836,10 @@ /** * g_shell_parse_argv: - * @command_line: command line to parse + * @command_line: (type filename): command line to parse * @argcp: (out) (optional): return location for number of args - * @argvp: (out) (optional) (array length=argcp zero-terminated=1): return - * location for array of args + * @argvp: (out) (optional) (array length=argcp zero-terminated=1) (element-type filename): + * return location for array of args * @error: (optional): return location for error * * Parses a command line into an argument vector, in much the same way @@ -26741,7 +26858,7 @@ /** * g_shell_quote: - * @unquoted_string: a literal string + * @unquoted_string: (type filename): a literal string * * Quotes a string so that the shell (/bin/sh) will interpret the * quoted string to mean @unquoted_string. If you pass a filename to @@ -26750,13 +26867,13 @@ * quoting style used is undefined (single or double quotes may be * used). * - * Returns: quoted string + * Returns: (type filename): quoted string */ /** * g_shell_unquote: - * @quoted_string: shell-quoted string + * @quoted_string: (type filename): shell-quoted string * @error: error return location or NULL * * Unquotes a string as the shell (/bin/sh) would. Only handles @@ -26781,7 +26898,7 @@ * be escaped with backslash. Otherwise double quotes preserve things * literally. * - * Returns: an unquoted string + * Returns: (type filename): an unquoted string */ @@ -28158,9 +28275,12 @@ /** * g_spawn_async: - * @working_directory: (type filename) (nullable): 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) (nullable): child's environment, or %NULL to inherit parent's + * @working_directory: (type filename) (nullable): child's current working + * directory, or %NULL to inherit parent's + * @argv: (array zero-terminated=1) (element-type filename): + * child's argument vector + * @envp: (array zero-terminated=1) (element-type filename) (nullable): + * child's environment, or %NULL to inherit parent's * @flags: flags from #GSpawnFlags * @child_setup: (scope async) (nullable): function to run in the child just before exec() * @user_data: (closure): user data for @child_setup @@ -28176,7 +28296,7 @@ * 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 * 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. * * Note that the returned @child_pid on Windows is a handle to the child * process and not its identifier. Process handles and process identifiers @@ -28188,9 +28308,13 @@ /** * g_spawn_async_with_pipes: - * @working_directory: (type filename) (nullable): 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) (nullable): child's environment, or %NULL to inherit parent's, in the GLib file name encoding + * @working_directory: (type filename) (nullable): child's current working + * directory, or %NULL to inherit parent's, in the GLib file name encoding + * @argv: (array zero-terminated=1) (element-type filename): child's argument + * vector, in the GLib file name encoding + * @envp: (array zero-terminated=1) (element-type filename) (nullable): + * child's environment, or %NULL to inherit parent's, in the GLib file + * name encoding * @flags: flags from #GSpawnFlags * @child_setup: (scope async) (nullable): function to run in the child just before exec() * @user_data: (closure): user data for @child_setup @@ -28349,7 +28473,7 @@ * 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 * 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. * * Returns: %TRUE on success, %FALSE if an error was set */ @@ -28416,7 +28540,7 @@ /** * g_spawn_command_line_async: - * @command_line: a command line + * @command_line: (type filename): a command line * @error: return location for errors * * A simple version of g_spawn_async() that parses a command line with @@ -28435,7 +28559,7 @@ /** * g_spawn_command_line_sync: - * @command_line: a command line + * @command_line: (type filename): a command line * @standard_output: (out) (array zero-terminated=1) (element-type guint8) (optional): return location for child output * @standard_error: (out) (array zero-terminated=1) (element-type guint8) (optional): return location for child errors * @exit_status: (out) (optional): return location for child exit status, as returned by waitpid() @@ -28470,9 +28594,12 @@ /** * g_spawn_sync: - * @working_directory: (type filename) (nullable): 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) (nullable): child's environment, or %NULL to inherit parent's + * @working_directory: (type filename) (nullable): child's current working + * directory, or %NULL to inherit parent's + * @argv: (array zero-terminated=1) (element-type filename): + * child's argument vector + * @envp: (array zero-terminated=1) (element-type filename) (nullable): + * child's environment, or %NULL to inherit parent's * @flags: flags from #GSpawnFlags * @child_setup: (scope async) (nullable): function to run in the child just before exec() * @user_data: (closure): user data for @child_setup @@ -28491,7 +28618,8 @@ * the child is stored there; see the documentation of * g_spawn_check_exit_status() for how to use and interpret this. * Note that it is invalid to pass %G_SPAWN_DO_NOT_REAP_CHILD in - * @flags. + * @flags, and on POSIX platforms, the same restrictions as for + * g_child_watch_source_new() apply. * * If an error occurs, no data is returned in @standard_output, * @standard_error, or @exit_status. @@ -30684,7 +30812,6 @@ * g_test_init(). See the g_test_run() documentation for more * information on the order that tests are run in. * - * * g_test_run_suite() or g_test_run() may only be called once * in a program. * @@ -33117,7 +33244,7 @@ * g_unix_fd_add: * @fd: a file descriptor * @condition: IO conditions to watch for on @fd - * @function: a #GPollFDFunc + * @function: a #GUnixFDSourceFunc * @user_data: data to pass to @function * * Sets a function to be called when the IO condition, as specified by @@ -33298,7 +33425,8 @@ /** * g_unsetenv: - * @variable: the environment variable to remove, must not contain '=' + * @variable: (type filename): the environment variable to remove, must + * not contain '=' * * Removes an environment variable from the environment. * @@ -37292,7 +37420,14 @@ * * You can make warnings fatal at runtime by setting the `G_DEBUG` * environment variable (see - * [Running GLib Applications](glib-running.html)). + * [Running GLib Applications](glib-running.html)): + * + * |[ + * G_DEBUG=fatal-warnings gdb ./my-program + * ]| + * + * Any unrelated failures can be skipped over in + * [gdb](https://www.gnu.org/software/gdb/) using the `continue` command. * * If g_log_default_handler() is used as the log handler function, * a newline character will automatically be appended to @..., and diff --git a/gir/gobject-2.0.c b/gir/gobject-2.0.c index 4eaeb195..f94bdb49 100644 --- a/gir/gobject-2.0.c +++ b/gir/gobject-2.0.c @@ -671,7 +671,7 @@ * 4. Invocation of user provided signal handlers (where the @after flag is set) * * 5. Invocation of the object method handler for %G_SIGNAL_RUN_CLEANUP signals - * + * * The user-provided signal handlers are called in the order they were * connected in. * @@ -3634,7 +3634,7 @@ * * Gets the default value of @pspec as a pointer to a #GValue. * - * The #GValue will remain value for the life of @pspec. + * The #GValue will remain valid for the life of @pspec. * * Returns: a pointer to a #GValue which must not be modified * Since: 2.38 -- cgit v1.2.1