[gobject-introspection] Update glib annotations from git master

[Jasper St. Pierre <jstpierre src gnome org>]

commit 79dd24a4375ab6497aec193a8505dea555b33023
Author: Jasper St. Pierre <jstpierre mecheye net>
Date:   Mon Oct 21 15:36:17 2013 -0400

    Update glib annotations from git master

 gir/gio-2.0.c  | 1140 +++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 gir/glib-2.0.c |  149 +++++++-
 2 files changed, 1269 insertions(+), 20 deletions(-)
---
diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c
index 8d90789..92ba5c0 100644
--- a/gir/gio-2.0.c
+++ b/gir/gio-2.0.c
@@ -1883,6 +1883,16 @@
 
 
 /**
+ * GNotification:
+ *
+ * This structure type is private and should only be accessed using the
+ * public APIs.
+ *
+ * Since: 2.40
+ */
+
+
+/**
  * GPermission:
  *
  * #GPermission is an opaque data structure and can only be accessed
@@ -5947,6 +5957,36 @@
 
 
 /**
+ * SECTION:gnotification
+ * @short_description: User Notifications (pop up messages)
+ *
+ * #GNotification is a mechanism for creating a notification to be shown
+ * to the user -- typically as a pop-up notification presented by the
+ * desktop environment shell.
+ *
+ * The key difference between #GNotification and other similar APIs is
+ * that, if supported by the desktop environment, notifications sent
+ * with #GNotification will persist after the application has exited,
+ * and even across system reboots.
+ *
+ * Since the user may click on a notification while the application is
+ * not running, applications using #GNotification should be able to be
+ * started as a D-Bus service, using #GApplication.
+ *
+ * User interaction with a notification (either the default action, or
+ * buttons) must be associated with actions on the application (ie:
+ * "app." actions).  It is not possible to route user interaction
+ * through the notification itself, because the object will not exist if
+ * the application is autostarted as a result of a notification being
+ * clicked.
+ *
+ * A notification can be sent with g_application_send_notification().
+ *
+ * Since: 2.40
+ */
+
+
+/**
  * SECTION:goutputstream
  * @short_description: Base class for implementing streaming output
  * @include: gio/gio.h
@@ -7127,6 +7167,90 @@
 
 
 /**
+ * SECTION:gsubprocess
+ * @title: GSubprocess
+ * @short_description: Child processes
+ * @see_also: #GSubprocessLauncher
+ *
+ * #GSubprocess allows the creation of and interaction with child
+ * processes.
+ *
+ * Processes can be communicated with using standard GIO-style APIs (ie:
+ * #GInputStream, #GOutputStream).  There are GIO-style APIs to wait for
+ * process termination (ie: cancellable and with an asynchronous
+ * variant).
+ *
+ * There is an API to force a process to terminate, as well as a
+ * race-free API for sending UNIX signals to a subprocess.
+ *
+ * One major advantage that GIO brings over the core GLib library is
+ * comprehensive API for asynchronous I/O, such
+ * g_output_stream_splice_async().  This makes GSubprocess
+ * significantly more powerful and flexible than equivalent APIs in
+ * some other languages such as the <literal>subprocess.py</literal>
+ * included with Python.  For example, using #GSubprocess one could
+ * create two child processes, reading standard output from the first,
+ * processing it, and writing to the input stream of the second, all
+ * without blocking the main loop.
+ *
+ * A powerful g_subprocess_communicate() API is provided similar to the
+ * <literal>communicate()</literal> method of
+ * <literal>subprocess.py</literal>.  This enables very easy interaction
+ * with a subprocess that has been opened with pipes.
+ *
+ * #GSubprocess defaults to tight control over the file descriptors open
+ * in the child process, avoiding dangling-fd issues that are caused by
+ * a simple fork()/exec().  The only open file descriptors in the
+ * spawned process are ones that were explicitly specified by the
+ * #GSubprocess API (unless %G_SUBPROCESS_FLAGS_INHERIT_FDS was
+ * specified).
+ *
+ * #GSubprocess will quickly reap all child processes as they exit,
+ * avoiding "zombie processes" remaining around for long periods of
+ * time.  g_subprocess_wait() can be used to wait for this to happen,
+ * but it will happen even without the call being explicitly made.
+ *
+ * As a matter of principle, #GSubprocess has no API that accepts
+ * shell-style space-separated strings.  It will, however, match the
+ * typical shell behaviour of searching the PATH for executables that do
+ * not contain a directory separator in their name.
+ *
+ * #GSubprocess attempts to have a very simple API for most uses (ie:
+ * spawning a subprocess with arguments and support for most typical
+ * kinds of input and output redirection).  See g_subprocess_new(). The
+ * #GSubprocessLauncher API is provided for more complicated cases
+ * (advanced types of redirection, environment variable manipulation,
+ * change of working directory, child setup functions, etc).
+ *
+ * A typical use of #GSubprocess will involve calling
+ * g_subprocess_new(), followed by g_subprocess_wait() or
+ * g_subprocess_wait_sync().  After the process exits, the status can be
+ * checked using functions such as g_subprocess_get_if_exited() (which
+ * are similar to the familiar WIFEXITED-style POSIX macros).
+ *
+ * Since: 2.40
+ */
+
+
+/**
+ * SECTION:gsubprocesslauncher
+ * @title: GSubprocess Launcher
+ * @short_description: Environment options for launching a child process
+ *
+ * This class contains a set of options for launching child processes,
+ * such as where its standard input and output will be directed, the
+ * argument list, the environment, and more.
+ *
+ * While the #GSubprocess class has high level functions covering
+ * popular cases, use of this class allows access to more advanced
+ * options.  It can also be used to launch multiple subprocesses with
+ * a similar configuration.
+ *
+ * Since: 2.40
+ */
+
+
+/**
  * SECTION:gtask
  * @short_description: Cancellable synchronous or asynchronous task and result
  * @include: gio/gio.h
@@ -7192,7 +7316,7 @@
  *           return;
  *         }
  *
- *       g_task_return_pointer (result, cake, g_object_unref);
+ *       g_task_return_pointer (task, cake, g_object_unref);
  *       g_object_unref (task);
  *     }
  *
@@ -11531,6 +11655,43 @@
 
 
 /**
+ * g_application_send_notification:
+ * @application: a #GApplication
+ * @id: (allow-none): id of the notification, or %NULL
+ * @notification: the #GNotification to send
+ *
+ * Sends a notification on behalf of @application to the desktop shell.
+ * There is no guarantee that the notification is displayed immediately,
+ * or even at all.
+ *
+ * Notifications may persist after the application exits. It will be
+ * D-Bus-activated when the notification or one of its actions is
+ * activated.
+ *
+ * Modifying @notification after this call has no effect. However, the
+ * object can be reused for a later call to this function.
+ *
+ * @id may be any string that uniquely identifies the event for the
+ * application. It does not need to be in any special format. For
+ * example, "new-message" might be appropriate for a notification about
+ * new messages.
+ *
+ * If a previous notification was sent with the same @id, it will be
+ * replaced with @notification and shown again as if it was a new
+ * notification. This works even for notifications sent from a previous
+ * execution of the application, as long as @id is the same string.
+ *
+ * @id may be %NULL, but it is impossible to replace or withdraw
+ * notifications without an id.
+ *
+ * If @notification is no longer relevant, it can be withdrawn with
+ * g_application_withdraw_notification().
+ *
+ * Since: 2.40
+ */
+
+
+/**
  * g_application_set_action_group:
  * @application: a #GApplication
  * @action_group: (allow-none): a #GActionGroup, or %NULL
@@ -11630,6 +11791,25 @@
 
 
 /**
+ * g_application_withdraw_notification:
+ * @application: a #GApplication
+ * @id: id of a previously sent notification
+ *
+ * Withdraws a notification that was sent with
+ * g_application_send_notification().
+ *
+ * This call does nothing if a notification with @id doesn't exist or
+ * the notification was never sent.
+ *
+ * This function works even for notifications sent in previous
+ * executions of this application, as long @id is the same as it was for
+ * the sent notification.
+ *
+ * Since: 2.40
+ */
+
+
+/**
  * g_async_initable_init_async:
  * @initable: a #GAsyncInitable.
  * @io_priority: the <link linkend="io-priority">I/O priority</link>
@@ -26650,6 +26830,190 @@
 
 
 /**
+ * g_notification_add_button:
+ * @notification: a #GNotification
+ * @label: label of the button
+ * @detailed_action: a detailed action name
+ *
+ * Adds a button to @notification that activates the action in
+ * @detailed_action when clicked. That action must be an
+ * application-wide action (starting with "app."). If @detailed_action
+ * contains a target, the action will be activated with that target as
+ * its parameter.
+ *
+ * See g_action_parse_detailed_name() for a description of the format
+ * for @detailed_action.
+ *
+ * Since: 2.40
+ */
+
+
+/**
+ * g_notification_add_button_with_target: (skip)
+ * @notification: a #GNotification
+ * @label: label of the button
+ * @action: an action name
+ * @target_format: (allow-none): a GVariant format string, or %NULL
+ * @...: positional parameters, as determined by @format_string
+ *
+ * Adds a button to @notification that activates @action when clicked.
+ * @action must be an application-wide action (it must start with "app.").
+ *
+ * If @target_format is given, it is used to collect remaining
+ * positional parameters into a GVariant instance, similar to
+ * g_variant_new(). @action will be activated with that GVariant as its
+ * parameter.
+ *
+ * Since: 2.40
+ */
+
+
+/**
+ * g_notification_add_button_with_target_value: (rename-to g_notification_add_button_with_target)
+ * @notification: a #GNotification
+ * @label: label of the button
+ * @action: an action name
+ * @target: (allow-none): a GVariant to use as @action's parameter, or %NULL
+ *
+ * Adds a button to @notification that activates @action when clicked.
+ * @action must be an application-wide action (it must start with "app.").
+ *
+ * If @target is non-%NULL, @action will be activated with @target as
+ * its parameter.
+ *
+ * Since: 2.40
+ */
+
+
+/**
+ * g_notification_new:
+ * @title: the title of the notification
+ *
+ * Creates a new #GNotification with @title as its title.
+ *
+ * After populating @notification with more details, it can be sent to
+ * the desktop shell with g_application_send_notification(). Changing
+ * any properties after this call will not have any effect until
+ * resending @notification.
+ *
+ * Returns: a new #GNotification instance
+ * Since: 2.40
+ */
+
+
+/**
+ * g_notification_set_body:
+ * @notification: a #GNotification
+ * @body: (allow-none): the new body for @notification, or %NULL
+ *
+ * Sets the body of @notification to @body.
+ *
+ * Since: 2.40
+ */
+
+
+/**
+ * g_notification_set_default_action:
+ * @notification: a #GNotification
+ * @detailed_action: a detailed action name
+ *
+ * Sets the default action of @notification to @detailed_action. This
+ * action is activated when the notification is clicked on.
+ *
+ * The action in @detailed_action must be an application-wide action (it
+ * must start with "app."). If @detailed_action contains a target, the
+ * given action will be activated with that target as its parameter.
+ * See g_action_parse_detailed_name() for a description of the format
+ * for @detailed_action.
+ *
+ * When no default action is set, the application that the notification
+ * was sent on is activated.
+ *
+ * Since: 2.40
+ */
+
+
+/**
+ * g_notification_set_default_action_and_target: (skip)
+ * @notification: a #GNotification
+ * @action: an action name
+ * @target_format: (allow-none): a GVariant format string, or %NULL
+ * @...: positional parameters, as determined by @format_string
+ *
+ * Sets the default action of @notification to @action. This action is
+ * activated when the notification is clicked on. It must be an
+ * application-wide action (it must start with "app.").
+ *
+ * If @target_format is given, it is used to collect remaining
+ * positional parameters into a GVariant instance, similar to
+ * g_variant_new(). @action will be activated with that GVariant as its
+ * parameter.
+ *
+ * When no default action is set, the application that the notification
+ * was sent on is activated.
+ *
+ * Since: 2.40
+ */
+
+
+/**
+ * g_notification_set_default_action_and_target_value: (rename-to 
g_notification_set_default_action_and_target)
+ * @notification: a #GNotification
+ * @action: an action name
+ * @target: (allow-none): a GVariant to use as @action's parameter, or %NULL
+ *
+ * Sets the default action of @notification to @action. This action is
+ * activated when the notification is clicked on. It must be an
+ * application-wide action (start with "app.").
+ *
+ * If @target_format is given, it is used to collect remaining
+ * positional parameters into a GVariant instance, similar to
+ * g_variant_new().
+ *
+ * If @target is non-%NULL, @action will be activated with @target as
+ * its parameter.
+ *
+ * When no default action is set, the application that the notification
+ * was sent on is activated.
+ *
+ * Since: 2.40
+ */
+
+
+/**
+ * g_notification_set_icon:
+ * @notification: a #GNotification
+ * @icon: the icon to be shown in @notification, as a #GIcon
+ *
+ * Sets the icon of @notification to @icon.
+ *
+ * Since: 2.40
+ */
+
+
+/**
+ * g_notification_set_title:
+ * @notification: a #GNotification
+ * @title: the new title for @notification
+ *
+ * Sets the title of @notification to @title.
+ *
+ * Since: 2.40
+ */
+
+
+/**
+ * g_notification_set_urgent:
+ * @notification: a #GNotification
+ * @urgent: %TRUE if @notification is urgent
+ *
+ * Sets or unsets whether @notification is marked as urgent.
+ *
+ * Since: 2.40
+ */
+
+
+/**
  * g_null_settings_backend_new:
  *
  * Creates a readonly #GSettingsBackend.
@@ -32926,6 +33290,780 @@
 
 
 /**
+ * g_subprocess_communicate:
+ * @subprocess: a #GSubprocess
+ * @stdin_buf: data to send to the stdin of the subprocess, or %NULL
+ * @cancellable: a #GCancellable
+ * @stdout_buf: (out): data read from the subprocess stdout
+ * @stderr_buf: (out): data read from the subprocess stderr
+ * @error: a pointer to a %NULL #GError pointer, or %NULL
+ *
+ * Communicate with the subprocess until it terminates, and all input
+ * and output has been completed.
+ *
+ * If @stdin is given, the subprocess must have been created with
+ * %G_SUBPROCESS_FLAGS_STDIN_PIPE.  The given data is fed to the
+ * stdin of the subprocess and the pipe is closed (ie: EOF).
+ *
+ * At the same time (as not to cause blocking when dealing with large
+ * amounts of data), if %G_SUBPROCESS_FLAGS_STDOUT_PIPE or
+ * %G_SUBPROCESS_FLAGS_STDERR_PIPE were used, reads from those
+ * streams.  The data that was read is returned in @stdout and/or
+ * the @stderr.
+ *
+ * If the subprocess was created with %G_SUBPROCESS_FLAGS_STDOUT_PIPE,
+ * @stdout_buf will contain the data read from stdout.  Otherwise, for
+ * subprocesses not created with %G_SUBPROCESS_FLAGS_STDOUT_PIPE,
+ * @stdout_buf will be set to %NULL.  Similar provisions apply to
+ * @stderr_buf and %G_SUBPROCESS_FLAGS_STDERR_PIPE.
+ *
+ * As usual, any output variable may be given as %NULL to ignore it.
+ *
+ * If you desire the stdout and stderr data to be interleaved, create
+ * the subprocess with %G_SUBPROCESS_FLAGS_STDOUT_PIPE and
+ * %G_SUBPROCESS_FLAGS_STDERR_MERGE.  The merged result will be returned
+ * in @stdout_buf and @stderr_buf will be set to %NULL.
+ *
+ * In case of any error (including cancellation), %FALSE will be
+ * returned with @error set.  Some or all of the stdin data may have
+ * been written.  Any stdout or stderr data that has been read will be
+ * discarded. None of the out variables (aside from @error) will have
+ * been set to anything in particular and should not be inspected.
+ *
+ * In the case that %TRUE is returned, the subprocess has exited and the
+ * exit status inspection APIs (eg: g_subprocess_get_if_exited(),
+ * g_subprocess_get_exit_status()) may be used.
+ *
+ * You should not attempt to use any of the subprocess pipes after
+ * starting this function, since they may be left in strange states,
+ * even if the operation was cancelled.  You should especially not
+ * attempt to interact with the pipes while the operation is in progress
+ * (either from another thread or if using the asynchronous version).
+ *
+ * Returns: %TRUE if successful
+ * Since: 2.40
+ */
+
+
+/**
+ * g_subprocess_communicate_async:
+ * @subprocess: Self
+ * @stdin_buf: Input data
+ * @cancellable: Cancellable
+ * @callback: Callback
+ * @user_data: User data
+ *
+ * Asynchronous version of g_subprocess_communicate().  Complete
+ * invocation with g_subprocess_communicate_finish().
+ */
+
+
+/**
+ * g_subprocess_communicate_finish:
+ * @subprocess: Self
+ * @result: Result
+ * @stdout_buf: (out): Return location for stdout data
+ * @stderr_buf: (out): Return location for stderr data
+ * @error: Error
+ *
+ * Complete an invocation of g_subprocess_communicate_async().
+ */
+
+
+/**
+ * g_subprocess_communicate_utf8:
+ * @subprocess: a #GSubprocess
+ * @stdin_buf: data to send to the stdin of the subprocess, or %NULL
+ * @cancellable: a #GCancellable
+ * @stdout_buf: (out): data read from the subprocess stdout
+ * @stderr_buf: (out): data read from the subprocess stderr
+ * @error: a pointer to a %NULL #GError pointer, or %NULL
+ *
+ * Like g_subprocess_communicate(), but validates the output of the
+ * process as UTF-8, and returns it as a regular NUL terminated string.
+ */
+
+
+/**
+ * g_subprocess_communicate_utf8_async:
+ * @subprocess: Self
+ * @stdin_buf: Input data
+ * @cancellable: Cancellable
+ * @callback: Callback
+ * @user_data: User data
+ *
+ * Asynchronous version of g_subprocess_communicate_utf().  Complete
+ * invocation with g_subprocess_communicate_utf8_finish().
+ */
+
+
+/**
+ * g_subprocess_communicate_utf8_finish:
+ * @subprocess: Self
+ * @result: Result
+ * @stdout_buf: (out): Return location for stdout data
+ * @stderr_buf: (out): Return location for stderr data
+ * @error: Error
+ *
+ * Complete an invocation of g_subprocess_communicate_utf8_async().
+ */
+
+
+/**
+ * g_subprocess_force_exit:
+ * @subprocess: a #GSubprocess
+ *
+ * Use an operating-system specific method to attempt an immediate,
+ * forceful termination of the process.  There is no mechanism to
+ * determine whether or not the request itself was successful;
+ * however, you can use g_subprocess_wait() to monitor the status of
+ * the process after calling this function.
+ *
+ * On Unix, this function sends %SIGKILL.
+ *
+ * Since: 2.40
+ */
+
+
+/**
+ * g_subprocess_get_exit_status:
+ * @subprocess: a #GSubprocess
+ *
+ * Check the exit status of the subprocess, given that it exited
+ * normally.  This is the value passed to the exit() system call or the
+ * return value from main.
+ *
+ * This is equivalent to the system WEXITSTATUS macro.
+ *
+ * It is an error to call this function before g_subprocess_wait() and
+ * unless g_subprocess_get_if_exited() returned %TRUE.
+ *
+ * Returns: the exit status
+ * Since: 2.40
+ */
+
+
+/**
+ * g_subprocess_get_if_exited:
+ * @subprocess: a #GSubprocess
+ *
+ * Check if the given subprocess exited normally (ie: by way of exit()
+ * or return from main()).
+ *
+ * This is equivalent to the system WIFEXITED macro.
+ *
+ * It is an error to call this function before g_subprocess_wait() has
+ * returned.
+ *
+ * Returns: %TRUE if the case of a normal exit
+ * Since: 2.40
+ */
+
+
+/**
+ * g_subprocess_get_if_signaled:
+ * @subprocess: a #GSubprocess
+ *
+ * Check if the given subprocess terminated in response to a signal.
+ *
+ * This is equivalent to the system WIFSIGNALED macro.
+ *
+ * It is an error to call this function before g_subprocess_wait() has
+ * returned.
+ *
+ * Returns: %TRUE if the case of termination due to a signal
+ * Since: 2.40
+ */
+
+
+/**
+ * g_subprocess_get_status:
+ * @subprocess: a #GSubprocess
+ *
+ * Gets the raw status code of the process, as from waitpid().
+ *
+ * This value has no particular meaning, but it can be used with the
+ * macros defined by the system headers such as WIFEXITED.  It can also
+ * be used with g_spawn_check_exit_status().
+ *
+ * It is more likely that you want to use g_subprocess_get_if_exited()
+ * followed by g_subprocess_get_exit_status().
+ *
+ * It is an error to call this function before g_subprocess_wait() has
+ * returned.
+ *
+ * Returns: the (meaningless) waitpid() exit status from the kernel
+ * Since: 2.40
+ */
+
+
+/**
+ * g_subprocess_get_stderr_pipe:
+ * @subprocess: a #GSubprocess
+ *
+ * Gets the #GInputStream from which to read the stderr output of
+ * @subprocess.
+ *
+ * The process must have been created with
+ * %G_SUBPROCESS_FLAGS_STDERR_PIPE.
+ *
+ * Returns: the stderr pipe
+ * Since: 2.40
+ */
+
+
+/**
+ * g_subprocess_get_stdin_pipe:
+ * @subprocess: a #GSubprocess
+ *
+ * Gets the #GOutputStream that you can write to in order to give data
+ * to the stdin of @subprocess.
+ *
+ * The process must have been created with
+ * %G_SUBPROCESS_FLAGS_STDIN_PIPE.
+ *
+ * Returns: the stdout pipe
+ * Since: 2.40
+ */
+
+
+/**
+ * g_subprocess_get_stdout_pipe:
+ * @subprocess: a #GSubprocess
+ *
+ * Gets the #GInputStream from which to read the stdout output of
+ * @subprocess.
+ *
+ * The process must have been created with
+ * %G_SUBPROCESS_FLAGS_STDOUT_PIPE.
+ *
+ * Returns: the stdout pipe
+ * Since: 2.40
+ */
+
+
+/**
+ * g_subprocess_get_successful:
+ * @subprocess: a #GSubprocess
+ *
+ * Checks if the process was "successful".  A process is considered
+ * successful if it exited cleanly with an exit status of 0, either by
+ * way of the exit() system call or return from main().
+ *
+ * It is an error to call this function before g_subprocess_wait() has
+ * returned.
+ *
+ * Returns: %TRUE if the process exited cleanly with a exit status of 0
+ * Since: 2.40
+ */
+
+
+/**
+ * g_subprocess_get_term_sig:
+ * @subprocess: a #GSubprocess
+ *
+ * Get the signal number that caused the subprocess to terminate, given
+ * that it terminated due to a signal.
+ *
+ * This is equivalent to the system WTERMSIG macro.
+ *
+ * It is an error to call this function before g_subprocess_wait() and
+ * unless g_subprocess_get_if_signaled() returned %TRUE.
+ *
+ * Returns: the signal causing termination
+ * Since: 2.40
+ */
+
+
+/**
+ * g_subprocess_launcher_getenv:
+ * @self: a #GSubprocess
+ * @variable: the environment variable to get
+ *
+ * Returns the value of the environment variable @variable in the
+ * environment of processes launched from this launcher.
+ *
+ * The returned string is in the GLib file name encoding.  On UNIX, this
+ * means that it can be an arbitrary byte string.  On Windows, it will
+ * be UTF-8.
+ *
+ * Returns: the value of the environment variable, %NULL if unset
+ * Since: 2.40
+ */
+
+
+/**
+ * g_subprocess_launcher_new:
+ * @flags: #GSubprocessFlags
+ *
+ * Creates a new #GSubprocessLauncher.
+ *
+ * The launcher is created with the default options.  A copy of the
+ * environment of the calling process is made at the time of this call
+ * and will be used as the environment that the process is launched in.
+ *
+ * Since: 2.40
+ */
+
+
+/**
+ * g_subprocess_launcher_set_child_setup:
+ * @self: a #GSubprocessLauncher
+ * @child_setup: a #GSpawnChildSetupFunc to use as the child setup function
+ * @user_data: user data for @child_setup
+ * @destroy_notify: a #GDestroyNotify for @user_data
+ *
+ * Sets up a child setup function.
+ *
+ * The child setup function will be called after fork() but before
+ * exec() on the child's side.
+ *
+ * @destroy_notify will not be automatically called on the child's side
+ * of the fork().  It will only be called when the last reference on the
+ * #GSubprocessLauncher is dropped or when a new child setup function is
+ * given.
+ *
+ * %NULL can be given as @child_setup to disable the functionality.
+ *
+ * Child setup functions are only available on UNIX.
+ *
+ * Since: 2.40
+ */
+
+
+/**
+ * g_subprocess_launcher_set_cwd:
+ * @self: a #GSubprocess
+ * @cwd: the cwd for launched processes
+ *
+ * Sets the current working directory that processes will be launched
+ * with.
+ *
+ * By default processes are launched with the current working directory
+ * of the launching process at the time of launch.
+ *
+ * Since: 2.40
+ */
+
+
+/**
+ * g_subprocess_launcher_set_environ:
+ * @self: a #GSubprocess
+ * @environ: the replacement environment
+ *
+ * Replace the entire environment of processes launched from this
+ * launcher with the given 'environ' variable.
+ *
+ * Typically you will build this variable by using g_listenv() to copy
+ * the process 'environ' and using the functions g_environ_setenv(),
+ * g_environ_unsetenv(), etc.
+ *
+ * As an alternative, you can use g_subprocess_launcher_setenv(),
+ * g_subprocess_launcher_unsetenv(), etc.
+ *
+ * All strings in this array are expected to be in the GLib file name
+ * encoding.  On UNIX, this means that they can be arbitrary byte
+ * strings.  On Windows, they should be in UTF-8.
+ *
+ * Since: 2.40
+ */
+
+
+/**
+ * g_subprocess_launcher_set_flags:
+ * @self: a #GSubprocessLauncher
+ * @flags: #GSubprocessFlags
+ *
+ * Sets the flags on the launcher.
+ *
+ * The default flags are %G_SUBPROCESS_FLAGS_NONE.
+ *
+ * You may not set flags that specify conflicting options for how to
+ * handle a particular stdio stream (eg: specifying both
+ * %G_SUBPROCESS_FLAGS_STDIN_PIPE and
+ * %G_SUBPROCESS_FLAGS_STDIN_INHERIT).
+ *
+ * You may also not set a flag that conflicts with a previous call to a
+ * function like g_subprocess_launcher_set_stdin_file_path() or
+ * g_subprocess_launcher_take_stdout_fd().
+ *
+ * Since: 2.40
+ */
+
+
+/**
+ * g_subprocess_launcher_set_stderr_file_path:
+ * @self: a #GSubprocessLauncher
+ * @path: a filename or %NULL
+ *
+ * Sets the file path to use as the stderr for spawned processes.
+ *
+ * If @path is %NULL then any previously given path is unset.
+ *
+ * The file will be created or truncated when the process is spawned, as
+ * would be the case if using '2>' at the shell.
+ *
+ * If you want to send both stdout and stderr to the same file then use
+ * %G_SUBPROCESS_FLAGS_STDERR_MERGE.
+ *
+ * You may not set a stderr file path if a stderr fd is already set or
+ * if the launcher flags contain any flags directing stderr elsewhere.
+ *
+ * This feature is only available on UNIX.
+ *
+ * Since: 2.40
+ */
+
+
+/**
+ * g_subprocess_launcher_set_stdin_file_path:
+ * @self: a #GSubprocessLauncher
+ * @path: a filename or %NULL
+ *
+ * Sets the file path to use as the stdin for spawned processes.
+ *
+ * If @path is %NULL then any previously given path is unset.
+ *
+ * The file must exist or spawning the process will fail.
+ *
+ * You may not set a stdin file path if a stdin fd is already set or if
+ * the launcher flags contain any flags directing stdin elsewhere.
+ *
+ * This feature is only available on UNIX.
+ *
+ * Since: 2.40
+ */
+
+
+/**
+ * g_subprocess_launcher_set_stdout_file_path:
+ * @self: a #GSubprocessLauncher
+ * @path: a filename or %NULL
+ *
+ * Sets the file path to use as the stdout for spawned processes.
+ *
+ * If @path is %NULL then any previously given path is unset.
+ *
+ * The file will be created or truncated when the process is spawned, as
+ * would be the case if using '>' at the shell.
+ *
+ * You may not set a stdout file path if a stdout fd is already set or
+ * if the launcher flags contain any flags directing stdout elsewhere.
+ *
+ * This feature is only available on UNIX.
+ *
+ * Since: 2.40
+ */
+
+
+/**
+ * g_subprocess_launcher_setenv:
+ * @self: a #GSubprocess
+ * @variable: the environment variable to set, must not contain '='
+ * @value: 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
+ * processes launched from this launcher.
+ *
+ * Both the variable's name and value should be in the GLib file name
+ * encoding. On UNIX, this means that they can be arbitrary byte
+ * strings. On Windows, they should be in UTF-8.
+ *
+ * Since: 2.40
+ */
+
+
+/**
+ * g_subprocess_launcher_spawn:
+ * @self: a #GSubprocessLauncher
+ * @error: Error
+ * @argv0: Command line arguments
+ * @...: Continued arguments, %NULL terminated
+ *
+ * A convenience helper for creating a #GSubprocess given a provided
+ * varargs list of arguments.
+ *
+ * Since: 2.40
+ * Returns: (transfer full): A new #GSubprocess, or %NULL on error (and @error will be set)
+ */
+
+
+/**
+ * g_subprocess_launcher_spawnv:
+ * @self: a #GSubprocessLauncher
+ * @argv: Command line arguments
+ * @error: Error
+ *
+ * A convenience helper for creating a #GSubprocess given a provided
+ * array of arguments.
+ *
+ * Since: 2.40
+ * Returns: (transfer full): A new #GSubprocess, or %NULL on error (and @error will be set)
+ */
+
+
+/**
+ * g_subprocess_launcher_take_fd:
+ * @self: a #GSubprocessLauncher
+ * @source_fd: File descriptor in parent process
+ * @target_fd: Target descriptor for child process
+ *
+ * Transfer an arbitrary file descriptor from parent process to the
+ * child.  This function takes "ownership" of the fd; it will be closed
+ * in the parent when @self is freed.
+ *
+ * By default, all file descriptors from the parent will be closed.
+ * This function allows you to create (for example) a custom pipe() or
+ * socketpair() before launching the process, and choose the target
+ * descriptor in the child.
+ *
+ * An example use case is GNUPG, which has a command line argument
+ * --passphrase-fd providing a file descriptor number where it expects
+ * the passphrase to be written.
+ */
+
+
+/**
+ * g_subprocess_launcher_take_stderr_fd:
+ * @self: a #GSubprocessLauncher
+ * @fd: a file descriptor, or -1
+ *
+ * Sets the file descriptor to use as the stderr for spawned processes.
+ *
+ * If @fd is -1 then any previously given fd is unset.
+ *
+ * Note that the default behaviour is to pass stderr through to the
+ * stderr of the parent process.
+ *
+ * The passed @fd belongs to the #GSubprocessLauncher.  It will be
+ * automatically closed when the launcher is finalized.  The file
+ * descriptor will also be closed on the child side when executing the
+ * spawned process.
+ *
+ * You may not set a stderr fd if a stderr file path is already set or
+ * if the launcher flags contain any flags directing stderr elsewhere.
+ *
+ * This feature is only available on UNIX.
+ *
+ * Since: 2.40
+ */
+
+
+/**
+ * g_subprocess_launcher_take_stdin_fd:
+ * @self: a #GSubprocessLauncher
+ * @fd: a file descriptor, or -1
+ *
+ * Sets the file descriptor to use as the stdin for spawned processes.
+ *
+ * If @fd is -1 then any previously given fd is unset.
+ *
+ * Note that if your intention is to have the stdin of the calling
+ * process inherited by the child then %G_SUBPROCESS_FLAGS_STDIN_INHERIT
+ * is a better way to go about doing that.
+ *
+ * The passed @fd is noted but will not be touched in the current
+ * process.  It is therefore necessary that it be kept open by the
+ * caller until the subprocess is spawned.  The file descriptor will
+ * also not be explicitly closed on the child side, so it must be marked
+ * O_CLOEXEC if that's what you want.
+ *
+ * You may not set a stdin fd if a stdin file path is already set or if
+ * the launcher flags contain any flags directing stdin elsewhere.
+ *
+ * This feature is only available on UNIX.
+ *
+ * Since: 2.40
+ */
+
+
+/**
+ * g_subprocess_launcher_take_stdout_fd:
+ * @self: a #GSubprocessLauncher
+ * @fd: a file descriptor, or -1
+ *
+ * Sets the file descriptor to use as the stdout for spawned processes.
+ *
+ * If @fd is -1 then any previously given fd is unset.
+ *
+ * Note that the default behaviour is to pass stdout through to the
+ * stdout of the parent process.
+ *
+ * The passed @fd is noted but will not be touched in the current
+ * process.  It is therefore necessary that it be kept open by the
+ * caller until the subprocess is spawned.  The file descriptor will
+ * also not be explicitly closed on the child side, so it must be marked
+ * O_CLOEXEC if that's what you want.
+ *
+ * You may not set a stdout fd if a stdout file path is already set or
+ * if the launcher flags contain any flags directing stdout elsewhere.
+ *
+ * This feature is only available on UNIX.
+ *
+ * Since: 2.40
+ */
+
+
+/**
+ * g_subprocess_launcher_unsetenv:
+ * @self: a #GSubprocess
+ * @variable: the environment variable to unset, must not contain '='
+ *
+ * Removes the environment variable @variable from the environment of
+ * processes launched from this launcher.
+ *
+ * The variable name should be in the GLib file name encoding.  On UNIX,
+ * this means that they can be arbitrary byte strings.  On Windows, they
+ * should be in UTF-8.
+ *
+ * Since: 2.40
+ */
+
+
+/**
+ * g_subprocess_new: (skip)
+ * @flags: flags that define the behaviour of the subprocess
+ * @error: (allow-none): return location for an error, or %NULL
+ * @argv0: first commandline argument to pass to the subprocess,
+ *     followed by more arguments, followed by %NULL
+ *
+ * Create a new process with the given flags and varargs argument list.
+ *
+ * The argument list must be terminated with %NULL.
+ *
+ * Returns: A newly created #GSubprocess, or %NULL on error (and @error
+ *   will be set)
+ * Since: 2.40
+ */
+
+
+/**
+ * g_subprocess_newv: (rename-to g_subprocess_new)
+ * @argv: commandline arguments for the subprocess
+ * @flags: flags that define the behaviour of the subprocess
+ * @error: (allow-none): return location for an error, or %NULL
+ *
+ * Create a new process with the given flags and argument list.
+ *
+ * The argument list is expected to be %NULL-terminated.
+ *
+ * Returns: A newly created #GSubprocess, or %NULL on error (and @error
+ *   will be set)
+ * Since: 2.40
+ */
+
+
+/**
+ * g_subprocess_send_signal:
+ * @subprocess: a #GSubprocess
+ * @signal_num: the signal number to send
+ *
+ * Sends the UNIX signal @signal_num to the subprocess, if it is still
+ * running.
+ *
+ * This API is race-free.  If the subprocess has terminated, it will not
+ * be signalled.
+ *
+ * This API is not available on Windows.
+ *
+ * Since: 2.40
+ */
+
+
+/**
+ * g_subprocess_wait:
+ * @subprocess: a #GSubprocess
+ * @cancellable: a #GCancellable
+ * @error: a #GError
+ *
+ * Synchronously wait for the subprocess to terminate.
+ *
+ * After the process terminates you can query its exit status with
+ * functions such as g_subprocess_get_if_exited() and
+ * g_subprocess_get_exit_status().
+ *
+ * This function does not fail in the case of the subprocess having
+ * abnormal termination.  See g_subprocess_wait_check() for that.
+ *
+ * Returns: %TRUE on success, %FALSE if @cancellable was cancelled
+ * Since: 2.40
+ */
+
+
+/**
+ * g_subprocess_wait_async:
+ * @subprocess: a #GSubprocess
+ * @cancellable: a #GCancellable, or %NULL
+ * @callback: a #GAsyncReadyCallback to call when the operation is complete
+ * @user_data: user_data for @callback
+ *
+ * Wait for the subprocess to terminate.
+ *
+ * This is the asynchronous version of g_subprocess_wait().
+ *
+ * Since: 2.40
+ */
+
+
+/**
+ * g_subprocess_wait_check:
+ * @subprocess: a #GSubprocess
+ * @cancellable: a #GCancellable
+ * @error: a #GError
+ *
+ * Combines g_subprocess_wait() with g_spawn_check_exit_status().
+ *
+ * Returns: %TRUE on success, %FALSE if process exited abnormally, or
+ * @cancellable was cancelled
+ * Since: 2.40
+ */
+
+
+/**
+ * g_subprocess_wait_check_async:
+ * @subprocess: a #GSubprocess
+ * @cancellable: a #GCancellable, or %NULL
+ * @callback: a #GAsyncReadyCallback to call when the operation is complete
+ * @user_data: user_data for @callback
+ *
+ * Combines g_subprocess_wait_async() with g_spawn_check_exit_status().
+ *
+ * This is the asynchronous version of g_subprocess_wait_check().
+ *
+ * Since: 2.40
+ */
+
+
+/**
+ * g_subprocess_wait_check_finish:
+ * @subprocess: a #GSubprocess
+ * @result: the #GAsyncResult passed to your #GAsyncReadyCallback
+ * @error: a pointer to a %NULL #GError, or %NULL
+ *
+ * Collects the result of a previous call to
+ * g_subprocess_wait_check_async().
+ *
+ * Returns: %TRUE if successful, or %FALSE with @error set
+ * Since: 2.40
+ */
+
+
+/**
+ * g_subprocess_wait_finish:
+ * @subprocess: a #GSubprocess
+ * @result: the #GAsyncResult passed to your #GAsyncReadyCallback
+ * @error: a pointer to a %NULL #GError, or %NULL
+ *
+ * Collects the result of a previous call to
+ * g_subprocess_wait_async().
+ *
+ * Returns: %TRUE if successful, or %FALSE with @error set
+ * Since: 2.40
+ */
+
+
+/**
  * g_task_attach_source:
  * @task: a #GTask
  * @source: the source to attach
diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c
index a6fd04b..9ecdace 100644
--- a/gir/glib-2.0.c
+++ b/gir/glib-2.0.c
@@ -1237,6 +1237,12 @@
  * @user_data: user data, set in g_log_set_handler()
  *
  * Specifies the prototype of log handler functions.
+ *
+ * The default log handler, g_log_default_handler(), automatically appends a
+ * new-line character to @message when printing it. It is advised that any
+ * custom log handler functions behave similarly, so that logging calls in user
+ * code do not need modifying to add a new-line character to the message if the
+ * log handler is changed.
  */
 
 
@@ -12035,6 +12041,10 @@
  * You can also make critical warnings fatal at runtime by
  * setting the <envar>G_DEBUG</envar> environment variable (see
  * <ulink url="glib-running.html">Running GLib Applications</ulink>).
+ *
+ * If g_log_default_handler() is used as the log handler function, a new-line
+ * character will automatically be appended to @..., and need not be entered
+ * manually.
  */
 
 
@@ -14094,6 +14104,10 @@
  *
  * A convenience function/macro to log a debug message.
  *
+ * If g_log_default_handler() is used as the log handler function, a new-line
+ * character will automatically be appended to @..., and need not be entered
+ * manually.
+ *
  * Since: 2.6
  */
 
@@ -14385,13 +14399,6 @@
  * Returns the value of the environment variable @variable in the
  * provided list @envp.
  *
- * The name and value are in the GLib file name encoding.
- * On UNIX, this means the actual bytes which might or might not
- * be in some consistent character set and encoding. On Windows,
- * it is in UTF-8. 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
  *     the environment variable is not set in @envp. The returned
  *     string is owned by @envp, and will be freed if @variable is
@@ -14402,9 +14409,10 @@
 
 /**
  * g_environ_setenv:
- * @envp: (allow-none) (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
+ * @envp: (allow-none) (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 set, must not contain '='
  * @value: the value for to set the variable to
  * @overwrite: whether to change the variable if it already exists
@@ -14412,10 +14420,6 @@
  * Sets the environment variable @variable in the provided list
  * @envp to @value.
  *
- * Both the variable's name and value should be in the GLib
- * file name encoding. On UNIX, this means that they can be
- * arbitrary byte strings. On Windows, they should be in UTF-8.
- *
  * Returns: (array zero-terminated=1) (transfer full): the
  *     updated environment list. Free it using g_strfreev().
  * Since: 2.32
@@ -14450,6 +14454,10 @@
  * result in a core dump; don't use it for errors you expect.
  * Using this function indicates a bug in your program, i.e.
  * an assertion failure.
+ *
+ * If g_log_default_handler() is used as the log handler function, a new-line
+ * character will automatically be appended to @..., and need not be entered
+ * manually.
  */
 
 
@@ -18740,7 +18748,8 @@
  * system) in the <link linkend="setlocale">current locale</link>. On
  * Windows this means the system codepage.
  *
- * Returns: The converted string, or %NULL on an error.
+ * Returns: A newly-allocated buffer containing the converted string,
+ *               or %NULL on an error, and error will be set.
  */
 
 
@@ -18768,7 +18777,8 @@
  * system) in the <link linkend="setlocale">current locale</link> into a
  * UTF-8 string.
  *
- * Returns: The converted string, or %NULL on an error.
+ * Returns: A newly-allocated buffer containing the converted string,
+ *               or %NULL on an error, and error will be set.
  */
 
 
@@ -18784,6 +18794,10 @@
  *
  * If the log level has been set as fatal, the abort()
  * function is called to terminate the program.
+ *
+ * If g_log_default_handler() is used as the log handler function, a new-line
+ * character will automatically be appended to @..., and need not be entered
+ * manually.
  */
 
 
@@ -18798,7 +18812,9 @@
  * allows to install an alternate default log handler.
  * This is used if no log handler has been set for the particular log
  * domain and log level combination. It outputs the message to stderr
- * or stdout and if the log level is fatal it calls abort().
+ * or stdout and if the log level is fatal it calls abort(). It automatically
+ * prints a new-line character after the message, so one does not need to be
+ * manually included in @message.
  *
  * The behavior of this log handler can be influenced by a number of
  * environment variables:
@@ -18942,6 +18958,10 @@
  *
  * If the log level has been set as fatal, the abort()
  * function is called to terminate the program.
+ *
+ * If g_log_default_handler() is used as the log handler function, a new-line
+ * character will automatically be appended to @..., and need not be entered
+ * manually.
  */
 
 
@@ -20611,6 +20631,10 @@
  *     into the format string (as with printf())
  *
  * A convenience function/macro to log a normal message.
+ *
+ * If g_log_default_handler() is used as the log handler function, a new-line
+ * character will automatically be appended to @..., and need not be entered
+ * manually.
  */
 
 
@@ -22071,7 +22095,9 @@
  * @...: the parameters to insert into the format string
  *
  * Outputs a formatted message via the print handler.
- * The default print handler simply outputs the message to stdout.
+ * The default print handler simply outputs the message to stdout, without
+ * appending a trailing new-line character. Typically, @format should end with
+ * its own new-line character.
  *
  * g_print() should not be used from within libraries for debugging
  * messages, since it may be redirected by applications to special
@@ -22087,7 +22113,9 @@
  * @...: the parameters to insert into the format string
  *
  * Outputs a formatted message via the error message handler.
- * The default handler simply outputs the message to stderr.
+ * The default handler simply outputs the message to stderr, without appending
+ * a trailing new-line character. Typically, @format should end with its own
+ * new-line character.
  *
  * g_printerr() should not be used from within libraries.
  * Instead g_log() should be used, or the convenience functions
@@ -22104,6 +22132,10 @@
  * An implementation of the standard printf() function which supports
  * positional parameters, as specified in the Single Unix Specification.
  *
+ * As with the standard printf(), this does not automatically append a trailing
+ * new-line character to the message, so typically @format should end with its
+ * own new-line character.
+ *
  * Returns: the number of bytes printed.
  * Since: 2.2
  */
@@ -27089,6 +27121,81 @@
 
 
 /**
+ * g_str_is_ascii:
+ * @string: a string.
+ *
+ * Determines if a string is pure ASCII.  A string is pure ASCII if it
+ * contains no bytes with the high bit set.
+ *
+ * Returns: %TRUE if @string is ascii
+ * Since: 2.40
+ */
+
+
+/**
+ * g_str_match_string:
+ * @search_term: the search term from the user
+ * @potential_hit: the text that may be a hit
+ * @accept_alternates: %TRUE to accept ASCII alternates
+ *
+ * Checks if a search conducted for @search_term should match
+ * @potential_hit.
+ *
+ * This function calls g_str_tokenize_and_fold() on both
+ * @search_term and @potential_hit.  ASCII alternates are never taken
+ * for @search_term but will be taken for @potential_hit according to
+ * the value of @accept_alternates.
+ *
+ * A hit occurs when each folded token in @search_term is a prefix of a
+ * folded token from @potential_hit.
+ *
+ * Depending on how you're performing the search, it will typically be
+ * faster to call g_str_tokenize_and_fold() on each string in
+ * your corpus and build an index on the returned folded tokens, then
+ * call g_str_tokenize_and_fold() on the search term and
+ * perform lookups into that index.
+ *
+ * As some examples, searching for "fred" would match the potential hit
+ * "Smith, Fred" and also "Frédéric".  Searching for "Fréd" would match
+ * "Frédéric" but not "Frederic" (due to the one-directional nature of
+ * accent matching).  Searching "fo" would match "Foo" and "Bar Foo
+ * Baz", but not "SFO" (because no word as "fo" as a prefix).
+ *
+ * Returns: %TRUE if @potential_hit is a hit
+ * Since: 2.40
+ */
+
+
+/**
+ * g_str_tokenize_and_fold:
+ * @string: a string
+ * @translit_locale: (allow-none): the language code (like 'de' or
+ *   'en_GB') from which @string originates
+ * @ascii_alternates: (out) (transfer full) (array zero-terminated=1): a
+ *   return location for ASCII alternates
+ *
+ * Tokenises @string and performs folding on each token.
+ *
+ * A token is a non-empty sequence of alphanumeric characters in the
+ * source string, separated by non-alphanumeric characters.  An
+ * "alphanumeric" character for this purpose is one that matches
+ * g_unichar_isalnum() or g_unichar_ismark().
+ *
+ * Each token is then (Unicode) normalised and case-folded.  If
+ * @ascii_alternates is non-%NULL and some of the returned tokens
+ * contain non-ASCII characters, ASCII alternatives will be generated.
+ *
+ * The number of ASCII alternatives that are generated and the method
+ * for doing so is unspecified, but @translit_locale (if specified) may
+ * improve the transliteration if the language of the source string is
+ * known.
+ *
+ * Returns: the folded tokens
+ * Since: 2.40
+ */
+
+
+/**
  * g_strcanon:
  * @string: a nul-terminated array of bytes
  * @valid_chars: bytes permitted in @string
@@ -35089,6 +35196,10 @@
  * You can make warnings fatal at runtime by setting the
  * <envar>G_DEBUG</envar> environment variable (see
  * <ulink url="glib-running.html">Running GLib Applications</ulink>).
+ *
+ * If g_log_default_handler() is used as the log handler function, a new-line
+ * character will automatically be appended to @..., and need not be entered
+ * manually.
  */