Struct gio::SubprocessLauncher

source ·
#[repr(transparent)]
pub struct SubprocessLauncher { /* private fields */ }
Expand description

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 Subprocess 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.

Implements

glib::ObjectExt

Implementations§

Available on Unix only.

Transfer an arbitrary file descriptor from parent process to the child. This function takes ownership of the source_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.

source_fd

File descriptor in parent process

target_fd

Target descriptor for child process

Available on Unix only.

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 SubprocessLauncher. 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.

fd

a file descriptor, or -1

Available on Unix only.

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 SubprocessFlags::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.

fd

a file descriptor, or -1

Available on Unix only.

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.

fd

a file descriptor, or -1

Creates a new SubprocessLauncher.

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.

flags

SubprocessFlags

Available on Unix and crate feature v2_68 only.

Closes all the file descriptors previously passed to the object with take_fd(), take_stderr_fd(), etc.

After calling this method, any subsequent calls to g_subprocess_launcher_spawn() or spawn() will return IOErrorEnum::Closed. This method is idempotent if called more than once.

This function is called automatically when the SubprocessLauncher is disposed, but is provided separately so that garbage collected language bindings can call it earlier to guarantee when FDs are closed.

Returns the value of the environment variable variable in the environment of processes launched from this launcher.

On UNIX, the returned string can be an arbitrary byte string. On Windows, it will be UTF-8.

variable

the environment variable to get

Returns

the value of the environment variable, None if unset

Available on Unix only.

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 SubprocessLauncher is dropped or when a new child setup function is given.

None can be given as child_setup to disable the functionality.

Child setup functions are only available on UNIX.

child_setup

a GSpawnChildSetupFunc to use as the child setup function

destroy_notify

a GDestroyNotify for user_data

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.

cwd

the cwd for launched processes

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 setenv(), unsetenv(), etc.

Pass an empty array to set an empty environment. Pass None to inherit the parent process’ environment. As of GLib 2.54, the parent process’ environment will be copied when set_environ() is called. Previously, it was copied when the subprocess was executed. This means the copied environment may now be modified (using setenv(), etc.) before launching the subprocess.

On UNIX, all strings in this array can be arbitrary byte strings. On Windows, they should be in UTF-8.

env

the replacement environment

Sets the flags on the launcher.

The default flags are SubprocessFlags::NONE.

You may not set flags that specify conflicting options for how to handle a particular stdio stream (eg: specifying both SubprocessFlags::STDIN_PIPE and SubprocessFlags::STDIN_INHERIT).

You may also not set a flag that conflicts with a previous call to a function like set_stdin_file_path() or take_stdout_fd().

flags

SubprocessFlags

Available on Unix only.

Sets the file path to use as the stderr for spawned processes.

If path is None 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 SubprocessFlags::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.

path

a filename or None

Available on Unix only.

Sets the file path to use as the stdin for spawned processes.

If path is None 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.

Available on Unix only.

Sets the file path to use as the stdout for spawned processes.

If path is None 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.

path

a filename or None

Sets the environment variable variable in the environment of processes launched from this launcher.

On UNIX, both the variable’s name and value can be arbitrary byte strings, except that the variable’s name cannot contain ‘=’. On Windows, they should be in UTF-8.

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

Creates a Subprocess given a provided varargs list of arguments.

argv0

Command line arguments

Returns

A new Subprocess, or None on error (and error will be set)

Removes the environment variable variable from the environment of processes launched from this launcher.

On UNIX, the variable’s name can be an arbitrary byte string not containing ‘=’. On Windows, it should be in UTF-8.

variable

the environment variable to unset, must not contain ‘=’

Trait Implementations§

Returns a copy of the value. Read more
Performs copy-assignment from source. Read more
Formats the value using the given formatter. Read more
Formats the value using the given formatter. Read more
Feeds this value into the given Hasher. Read more
Feeds a slice of this type into the given Hasher. Read more
This method returns an Ordering between self and other. Read more
Compares and returns the maximum of two values. Read more
Compares and returns the minimum of two values. Read more
Restrict a value to a certain interval. Read more
This method tests for self and other values to be equal, and is used by ==. Read more
This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason. Read more
This method returns an ordering between self and other values if one exists. Read more
This method tests less than (for self and other) and is used by the < operator. Read more
This method tests less than or equal to (for self and other) and is used by the <= operator. Read more
This method tests greater than (for self and other) and is used by the > operator. Read more
This method tests greater than or equal to (for self and other) and is used by the >= operator. Read more
Returns the type identifier of Self.

Auto Trait Implementations§

Blanket Implementations§

Gets the TypeId of self. Read more
Immutably borrows from an owned value. Read more
Mutably borrows from an owned value. Read more
Upcasts an object to a superclass or interface T. Read more
Upcasts an object to a reference of its superclass or interface T. Read more
Tries to downcast to a subclass or interface implementor T. Read more
Tries to downcast to a reference of its subclass or interface implementor T. Read more
Tries to cast to an object of type T. This handles upcasting, downcasting and casting between interface and interface implementors. All checks are performed at runtime, while downcast and upcast will do many checks at compile-time already. Read more
Tries to cast to reference to an object of type T. This handles upcasting, downcasting and casting between interface and interface implementors. All checks are performed at runtime, while downcast and upcast will do many checks at compile-time already. Read more
Casts to T unconditionally. Read more
Casts to &T unconditionally. Read more

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Returns true if the object is an instance of (can be cast to) T.
Returns the type of the object.
Returns the ObjectClass of the object. Read more
Returns the class of the object.
Returns the class of the object in the given type T. Read more
Returns the interface T of the object. Read more
Sets the property property_name of the object to value value. Read more
Sets the property property_name of the object to value value. Read more
Sets multiple properties of the object at once. Read more
Sets multiple properties of the object at once. Read more
Gets the property property_name of the object and cast it to the type V. Read more
Gets the property property_name of the object. Read more
Check if the object has a property property_name of the given type_. Read more
Get the type of the property property_name of this object. Read more
Get the ParamSpec of the property property_name of this object.
Return all ParamSpec of the properties of this object.
Freeze all property notifications until the return guard object is dropped. Read more
Set arbitrary data on this object with the given key. Read more
Return previously set arbitrary data of this object with the given key. Read more
Retrieve previously set arbitrary data of this object with the given key. Read more
Set arbitrary data on this object with the given key. Read more
Return previously set arbitrary data of this object with the given key. Read more
Retrieve previously set arbitrary data of this object with the given key. Read more
Block a given signal handler. Read more
Unblock a given signal handler.
Stop emission of the currently emitted signal.
Stop emission of the currently emitted signal by the (possibly detailed) signal name.
Connect to the signal signal_name on this object. Read more
Connect to the signal signal_id on this object. Read more
Connect to the signal signal_name on this object. Read more
Connect to the signal signal_id on this object. Read more
Connect to the signal signal_name on this object. Read more
Connect to the signal signal_id on this object. Read more
Connect a closure to the signal signal_name on this object. Read more
Connect a closure to the signal signal_id on this object. Read more
Limits the lifetime of closure to the lifetime of the object. When the object’s reference count drops to zero, the closure will be invalidated. An invalidated closure will ignore any calls to invoke_with_values, or invoke when using Rust closures. Read more
Emit signal by signal id. Read more
Same as Self::emit but takes Value for the arguments.
Emit signal by its name. Read more
Emit signal by its name. Read more
Emit signal by its name with details. Read more
Emit signal by its name with details. Read more
Emit signal by signal id with details. Read more
Emit signal by signal id with details. Read more
Disconnect a previously connected signal handler.
Connect to the notify signal of the object. Read more
Connect to the notify signal of the object. Read more
Connect to the notify signal of the object. Read more
Notify that the given property has changed its value. Read more
Notify that the given property has changed its value. Read more
Downgrade this object to a weak reference.
Add a callback to be notified when the Object is disposed.
Add a callback to be notified when the Object is disposed. Read more
Bind property source_property on this object to the target_property on the target object. Read more
Returns the strong reference count of this object.
Runs the dispose mechanism of the object. Read more
Ensures that the type has been registered with the type system.
The resulting type after obtaining ownership.
Creates owned data from borrowed data, usually by cloning. Read more
Uses borrowed data to replace owned data, usually by cloning. Read more
Converts the given value to a String. Read more
The type returned in the event of a conversion error.
Performs the conversion.
The type returned in the event of a conversion error.
Performs the conversion.