diff options
author | Jasper St. Pierre <jstpierre@mecheye.net> | 2013-10-21 15:36:17 -0400 |
---|---|---|
committer | Jasper St. Pierre <jstpierre@mecheye.net> | 2013-10-21 15:36:27 -0400 |
commit | 79dd24a4375ab6497aec193a8505dea555b33023 (patch) | |
tree | 0adab7aa91715f80df7e662544606498adf5a815 /gir | |
parent | 77a65ba33b737fe19de928ccf8c3196dfcd0726f (diff) | |
download | gobject-introspection-79dd24a4375ab6497aec193a8505dea555b33023.tar.gz |
Update glib annotations from git master
Diffstat (limited to 'gir')
-rw-r--r-- | gir/gio-2.0.c | 1140 | ||||
-rw-r--r-- | 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 8d90789e..92ba5c01 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 a6fd04b8..9ecdace0 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. */ |