@gtkx/ffi 0.1.45 → 0.1.46

package/dist/generated/gio/subprocess.js

@@ -3,6 +3,71 @@ import { NativeError, getObject } from "@gtkx/ffi";
 import { InputStream } from "./input-stream.js";
 import { OutputStream } from "./output-stream.js";
 import * as GObject from "../gobject/index.js";
+/**
+ * `GSubprocess` allows the creation of and interaction with child
+ * processes.
+ *
+ * Processes can be communicated with using standard GIO-style APIs (ie:
+ * [class@Gio.InputStream], [class@Gio.OutputStream]). 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
+ * [method@Gio.OutputStream.splice_async].  This makes `GSubprocess`
+ * significantly more powerful and flexible than equivalent APIs in
+ * some other languages such as the `subprocess.py`
+ * 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 [method@Gio.Subprocess.communicate] API is provided similar to the
+ * `communicate()` method of `subprocess.py`. 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.  [method@Gio.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. By default, the `PATH`
+ * of the current process is used.  You can specify
+ * `G_SUBPROCESS_FLAGS_SEARCH_PATH_FROM_ENVP` to use the `PATH` of the
+ * launcher environment instead.
+ *
+ * `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 [ctor@Gio.Subprocess.new]. The
+ * [class@Gio.SubprocessLauncher] 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
+ * [ctor@Gio.Subprocess.new], followed by [method@Gio.Subprocess.wait_async] or
+ * [method@Gio.Subprocess.wait].  After the process exits, the status can be
+ * checked using functions such as [method@Gio.Subprocess.get_if_exited] (which
+ * are similar to the familiar `WIFEXITED`-style POSIX macros).
+ *
+ * Note that as of GLib 2.82, creating a `GSubprocess` causes the signal
+ * `SIGPIPE` to be ignored for the remainder of the program. If you are writing
+ * a command-line utility that uses `GSubprocess`, you may need to take into
+ * account the fact that your program will not automatically be killed
+ * if it tries to write to `stdout` after it has been closed.
+ */
 export class Subprocess extends GObject.GObject {
     constructor(...args) {
         super(...args);
@@ -20,6 +85,53 @@ export class Subprocess extends GObject.GObject {
             },
         ], { type: "gobject", borrowed: false });
     }
+    /**
+     * Communicate with the subprocess until it terminates, and all input
+     * and output has been completed.
+     *
+     * If `stdin_buf` 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).
+     * @param stdinBuf - data to send to the stdin of the subprocess, or %NULL
+     * @param cancellable - a #GCancellable
+     * @param stdoutBuf - data read from the subprocess stdout
+     * @param stderrBuf - data read from the subprocess stderr
+     */
     communicate(stdinBuf, cancellable, stdoutBuf, stderrBuf) {
         const error = { value: null };
         const result = call("libgio-2.0.so.0", "g_subprocess_communicate", [
@@ -83,6 +195,14 @@ export class Subprocess extends GObject.GObject {
         }
         return result;
     }
+    /**
+     * Asynchronous version of g_subprocess_communicate().  Complete
+     * invocation with g_subprocess_communicate_finish().
+     * @param stdinBuf - Input data, or %NULL
+     * @param cancellable - Cancellable
+     * @param callback - Callback
+     * @param userData - User data
+     */
     communicateAsync(stdinBuf, cancellable, callback, userData) {
         call("libgio-2.0.so.0", "g_subprocess_communicate_async", [
             {
@@ -116,6 +236,12 @@ export class Subprocess extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Complete an invocation of g_subprocess_communicate_async().
+     * @param result - Result
+     * @param stdoutBuf - Return location for stdout data
+     * @param stderrBuf - Return location for stderr data
+     */
     communicateFinish(result, stdoutBuf, stderrBuf) {
         const error = { value: null };
         const _result = call("libgio-2.0.so.0", "g_subprocess_communicate_finish", [
@@ -168,6 +294,17 @@ export class Subprocess extends GObject.GObject {
         }
         return _result;
     }
+    /**
+     * Like g_subprocess_communicate(), but validates the output of the
+     * process as UTF-8, and returns it as a regular NUL terminated string.
+     *
+     * On error, `stdout_buf` and `stderr_buf` will be set to undefined values and
+     * should not be used.
+     * @param stdinBuf - data to send to the stdin of the subprocess, or %NULL
+     * @param cancellable - a #GCancellable
+     * @param stdoutBuf - data read from the subprocess stdout
+     * @param stderrBuf - data read from the subprocess stderr
+     */
     communicateUtf8(stdinBuf, cancellable, stdoutBuf, stderrBuf) {
         const error = { value: null };
         const result = call("libgio-2.0.so.0", "g_subprocess_communicate_utf8", [
@@ -212,6 +349,14 @@ export class Subprocess extends GObject.GObject {
         }
         return result;
     }
+    /**
+     * Asynchronous version of g_subprocess_communicate_utf8().  Complete
+     * invocation with g_subprocess_communicate_utf8_finish().
+     * @param stdinBuf - Input data, or %NULL
+     * @param cancellable - Cancellable
+     * @param callback - Callback
+     * @param userData - User data
+     */
     communicateUtf8Async(stdinBuf, cancellable, callback, userData) {
         call("libgio-2.0.so.0", "g_subprocess_communicate_utf8_async", [
             {
@@ -240,6 +385,12 @@ export class Subprocess extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Complete an invocation of g_subprocess_communicate_utf8_async().
+     * @param result - Result
+     * @param stdoutBuf - Return location for stdout data
+     * @param stderrBuf - Return location for stderr data
+     */
     communicateUtf8Finish(result, stdoutBuf, stderrBuf) {
         const error = { value: null };
         const _result = call("libgio-2.0.so.0", "g_subprocess_communicate_utf8_finish", [
@@ -278,6 +429,15 @@ export class Subprocess extends GObject.GObject {
         }
         return _result;
     }
+    /**
+     * 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.
+     */
     forceExit() {
         call("libgio-2.0.so.0", "g_subprocess_force_exit", [
             {
@@ -286,6 +446,16 @@ export class Subprocess extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * 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.
+     */
     getExitStatus() {
         return call("libgio-2.0.so.0", "g_subprocess_get_exit_status", [
             {
@@ -294,6 +464,11 @@ export class Subprocess extends GObject.GObject {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * On UNIX, returns the process ID as a decimal string.
+     * On Windows, returns the result of GetProcessId() also as a string.
+     * If the subprocess has terminated, this will return %NULL.
+     */
     getIdentifier() {
         return call("libgio-2.0.so.0", "g_subprocess_get_identifier", [
             {
@@ -302,6 +477,15 @@ export class Subprocess extends GObject.GObject {
             },
         ], { type: "string", borrowed: true });
     }
+    /**
+     * 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.
+     */
     getIfExited() {
         return call("libgio-2.0.so.0", "g_subprocess_get_if_exited", [
             {
@@ -310,6 +494,14 @@ export class Subprocess extends GObject.GObject {
             },
         ], { type: "boolean" });
     }
+    /**
+     * 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.
+     */
     getIfSignaled() {
         return call("libgio-2.0.so.0", "g_subprocess_get_if_signaled", [
             {
@@ -318,6 +510,19 @@ export class Subprocess extends GObject.GObject {
             },
         ], { type: "boolean" });
     }
+    /**
+     * 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_wait_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.
+     */
     getStatus() {
         return call("libgio-2.0.so.0", "g_subprocess_get_status", [
             {
@@ -326,6 +531,13 @@ export class Subprocess extends GObject.GObject {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * Gets the #GInputStream from which to read the stderr output of
+     * @subprocess.
+     *
+     * The process must have been created with %G_SUBPROCESS_FLAGS_STDERR_PIPE,
+     * otherwise %NULL will be returned.
+     */
     getStderrPipe() {
         const ptr = call("libgio-2.0.so.0", "g_subprocess_get_stderr_pipe", [
             {
@@ -337,6 +549,13 @@ export class Subprocess extends GObject.GObject {
             return null;
         return getObject(ptr, InputStream);
     }
+    /**
+     * 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 and
+     * not %G_SUBPROCESS_FLAGS_STDIN_INHERIT, otherwise %NULL will be returned.
+     */
     getStdinPipe() {
         const ptr = call("libgio-2.0.so.0", "g_subprocess_get_stdin_pipe", [
             {
@@ -348,6 +567,13 @@ export class Subprocess extends GObject.GObject {
             return null;
         return getObject(ptr, OutputStream);
     }
+    /**
+     * Gets the #GInputStream from which to read the stdout output of
+     * @subprocess.
+     *
+     * The process must have been created with %G_SUBPROCESS_FLAGS_STDOUT_PIPE,
+     * otherwise %NULL will be returned.
+     */
     getStdoutPipe() {
         const ptr = call("libgio-2.0.so.0", "g_subprocess_get_stdout_pipe", [
             {
@@ -359,6 +585,14 @@ export class Subprocess extends GObject.GObject {
             return null;
         return getObject(ptr, InputStream);
     }
+    /**
+     * 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.
+     */
     getSuccessful() {
         return call("libgio-2.0.so.0", "g_subprocess_get_successful", [
             {
@@ -367,6 +601,15 @@ export class Subprocess extends GObject.GObject {
             },
         ], { type: "boolean" });
     }
+    /**
+     * 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.
+     */
     getTermSig() {
         return call("libgio-2.0.so.0", "g_subprocess_get_term_sig", [
             {
@@ -375,6 +618,16 @@ export class Subprocess extends GObject.GObject {
             },
         ], { type: "int", size: 32, unsigned: false });
     }
+    /**
+     * 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.
+     * @param signalNum - the signal number to send
+     */
     sendSignal(signalNum) {
         call("libgio-2.0.so.0", "g_subprocess_send_signal", [
             {
@@ -387,6 +640,20 @@ export class Subprocess extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * 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.
+     *
+     * Cancelling `cancellable` doesn't kill the subprocess.  Call
+     * g_subprocess_force_exit() if it is desirable.
+     * @param cancellable - a #GCancellable
+     */
     wait(cancellable) {
         const error = { value: null };
         const result = call("libgio-2.0.so.0", "g_subprocess_wait", [
@@ -416,6 +683,14 @@ export class Subprocess extends GObject.GObject {
         }
         return result;
     }
+    /**
+     * Wait for the subprocess to terminate.
+     *
+     * This is the asynchronous version of g_subprocess_wait().
+     * @param cancellable - a #GCancellable, or %NULL
+     * @param callback - a #GAsyncReadyCallback to call when the operation is complete
+     * @param userData - user_data for @callback
+     */
     waitAsync(cancellable, callback, userData) {
         call("libgio-2.0.so.0", "g_subprocess_wait_async", [
             {
@@ -439,6 +714,10 @@ export class Subprocess extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Combines g_subprocess_wait() with g_spawn_check_wait_status().
+     * @param cancellable - a #GCancellable
+     */
     waitCheck(cancellable) {
         const error = { value: null };
         const result = call("libgio-2.0.so.0", "g_subprocess_wait_check", [
@@ -468,6 +747,14 @@ export class Subprocess extends GObject.GObject {
         }
         return result;
     }
+    /**
+     * Combines g_subprocess_wait_async() with g_spawn_check_wait_status().
+     *
+     * This is the asynchronous version of g_subprocess_wait_check().
+     * @param cancellable - a #GCancellable, or %NULL
+     * @param callback - a #GAsyncReadyCallback to call when the operation is complete
+     * @param userData - user_data for @callback
+     */
     waitCheckAsync(cancellable, callback, userData) {
         call("libgio-2.0.so.0", "g_subprocess_wait_check_async", [
             {
@@ -491,6 +778,11 @@ export class Subprocess extends GObject.GObject {
             },
         ], { type: "undefined" });
     }
+    /**
+     * Collects the result of a previous call to
+     * g_subprocess_wait_check_async().
+     * @param result - the #GAsyncResult passed to your #GAsyncReadyCallback
+     */
     waitCheckFinish(result) {
         const error = { value: null };
         const _result = call("libgio-2.0.so.0", "g_subprocess_wait_check_finish", [
@@ -519,6 +811,11 @@ export class Subprocess extends GObject.GObject {
         }
         return _result;
     }
+    /**
+     * Collects the result of a previous call to
+     * g_subprocess_wait_async().
+     * @param result - the #GAsyncResult passed to your #GAsyncReadyCallback
+     */
     waitFinish(result) {
         const error = { value: null };
         const _result = call("libgio-2.0.so.0", "g_subprocess_wait_finish", [
@@ -547,6 +844,47 @@ export class Subprocess extends GObject.GObject {
         }
         return _result;
     }
+    /**
+     * Initializes the object implementing the interface.
+     *
+     * This method is intended for language bindings. If writing in C,
+     * g_initable_new() should typically be used instead.
+     *
+     * The object must be initialized before any real use after initial
+     * construction, either with this function or g_async_initable_init_async().
+     *
+     * Implementations may also support cancellation. If `cancellable` is not %NULL,
+     * then initialization can be cancelled by triggering the cancellable object
+     * from another thread. If the operation was cancelled, the error
+     * %G_IO_ERROR_CANCELLED will be returned. If `cancellable` is not %NULL and
+     * the object doesn't support cancellable initialization the error
+     * %G_IO_ERROR_NOT_SUPPORTED will be returned.
+     *
+     * If the object is not initialized, or initialization returns with an
+     * error, then all operations on the object except g_object_ref() and
+     * g_object_unref() are considered to be invalid, and have undefined
+     * behaviour. See the [description][iface@Gio.Initable#description] for more details.
+     *
+     * Callers should not assume that a class which implements #GInitable can be
+     * initialized multiple times, unless the class explicitly documents itself as
+     * supporting this. Generally, a class’ implementation of init() can assume
+     * (and assert) that it will only be called once. Previously, this documentation
+     * recommended all #GInitable implementations should be idempotent; that
+     * recommendation was relaxed in GLib 2.54.
+     *
+     * If a class explicitly supports being initialized multiple times, it is
+     * recommended that the method is idempotent: multiple calls with the same
+     * arguments should return the same results. Only the first call initializes
+     * the object; further calls return the result of the first call.
+     *
+     * One reason why a class might need to support idempotent initialization is if
+     * it is designed to be used via the singleton pattern, with a
+     * #GObjectClass.constructor that sometimes returns an existing instance.
+     * In this pattern, a caller would expect to be able to call g_initable_init()
+     * on the result of g_object_new(), regardless of whether it is in fact a new
+     * instance.
+     * @param cancellable - optional #GCancellable object, %NULL to ignore.
+     */
     init(cancellable) {
         const error = { value: null };
         const result = call("libgio-2.0.so.0", "g_initable_init", [