Class SubprocessLauncher

java.lang.Object

org.javagi.base.ProxyInstance

org.gnome.gobject.TypeInstance

org.gnome.gobject.GObject

org.gnome.gio.SubprocessLauncher

All Implemented Interfaces:

Proxy

@Generated("org.javagi.JavaGI")
public class SubprocessLauncher
extends GObject

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.

Since:

2.40

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	SubprocessLauncher.Builder<B extends SubprocessLauncher.Builder<B>>	Inner class implementing a builder pattern to construct a GObject with properties.

Nested classes/interfaces inherited from class GObject

GObject.NotifyCallback, GObject.ObjectClass

Constructor Summary

Constructors

Constructor	Description
SubprocessLauncher()	Create a new SubprocessLauncher.
SubprocessLauncher(MemorySegment address)	Create a SubprocessLauncher instance for the provided memory address.
SubprocessLauncher(Set<SubprocessFlags> flags)	Creates a new GSubprocessLauncher.
SubprocessLauncher(SubprocessFlags... flags)	Creates a new GSubprocessLauncher.

Method Summary

Modifier and Type	Method	Description
protected SubprocessLauncher	asParent()	Return this instance as if it were its parent type.
static SubprocessLauncher.Builder<? extends SubprocessLauncher.Builder>	builder()	A SubprocessLauncher.Builder object constructs a SubprocessLauncher with the specified properties.
void	close()	Closes all the file descriptors previously passed to the object with g_subprocess_launcher_take_fd(), g_subprocess_launcher_take_stderr_fd(), etc.
@Nullable String	getenv(String variable)	Returns the value of the environment variable variable in the environment of processes launched from this launcher.
static MemoryLayout	getMemoryLayout()	The memory layout of the native struct.
static @Nullable Type	getType()	Get the GType of the SubprocessLauncher class.
void	setChildSetup(@Nullable SpawnChildSetupFunc childSetup)	Sets up a child setup function.
void	setCwd(String cwd)	Sets the current working directory that processes will be launched with.
void	setenv(String variable, String value, boolean overwrite)	Sets the environment variable variable in the environment of processes launched from this launcher.
void	setEnviron(@Nullable String @Nullable [] env)	Replace the entire environment of processes launched from this launcher with the given 'environ' variable.
void	setFlags(Set<SubprocessFlags> flags)	Sets the flags on the launcher.
void	setFlags(SubprocessFlags... flags)	Sets the flags on the launcher.
void	setStderrFilePath(@Nullable String path)	Sets the file path to use as the stderr for spawned processes.
void	setStdinFilePath(@Nullable String path)	Sets the file path to use as the stdin for spawned processes.
void	setStdoutFilePath(@Nullable String path)	Sets the file path to use as the stdout for spawned processes.
Subprocess	spawn(GError[] error, String argv0, Object... varargs)	Creates a GSubprocess given a provided varargs list of arguments.
Subprocess	spawnv(@Nullable String @Nullable [] argv)	Creates a GSubprocess given a provided array of arguments.
void	takeFd(int sourceFd, int targetFd)	Transfer an arbitrary file descriptor from parent process to the child.
void	takeStderrFd(int fd)	Sets the file descriptor to use as the stderr for spawned processes.
void	takeStdinFd(int fd)	Sets the file descriptor to use as the stdin for spawned processes.
void	takeStdoutFd(int fd)	Sets the file descriptor to use as the stdout for spawned processes.
void	unsetenv(String variable)	Removes the environment variable variable from the environment of processes launched from this launcher.

Methods inherited from class GObject

addToggleRef, addWeakPointer, bindProperty, bindProperty, bindProperty, bindPropertyFull, bindPropertyFull, bindPropertyWithClosures, bindPropertyWithClosures, compatControl, connect, connect, connect, constructed, disconnect, dispatchPropertiesChanged, dispose, dupData, dupQdata, emit, emitNotify, finalize_, forceFloating, freezeNotify, get, getData, getProperty, getProperty, getProperty, getQdata, getv, interfaceFindProperty, interfaceInstallProperty, interfaceListProperties, isFloating, newInstance, newInstance, newv, notify, notify, notifyByPspec, onNotify, ref, refSink, removeToggleRef, removeWeakPointer, replaceData, replaceQdata, runDispose, set, setData, setDataFull, setProperty, setProperty, setProperty, setQdata, setQdataFull, setv, stealData, stealQdata, takeRef, thawNotify, unref, watchClosure, weakRef, weakUnref, withProperties

Methods inherited from class TypeInstance

callParent, callParent, cast, getPrivate, readGClass, writeGClass

Methods inherited from class ProxyInstance

equals, handle, hashCode

Methods inherited from class Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Details

SubprocessLauncher

public SubprocessLauncher(MemorySegment address)

Create a SubprocessLauncher instance for the provided memory address.

Parameters:

address - the memory address of the native object

SubprocessLauncher

public SubprocessLauncher(Set<SubprocessFlags> flags)

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.

Parameters:

flags - GSubprocessFlags

Since:

2.40

SubprocessLauncher

public SubprocessLauncher(SubprocessFlags... flags)

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.

Parameters:

flags - GSubprocessFlags

Since:

2.40

SubprocessLauncher

public SubprocessLauncher()

Create a new SubprocessLauncher.

Method Details

getType

public static @Nullable Type getType()

Get the GType of the SubprocessLauncher class.

Returns:

the GType

getMemoryLayout

public static MemoryLayout getMemoryLayout()

The memory layout of the native struct.

Returns:

the memory layout

asParent

protected SubprocessLauncher asParent()

Return this instance as if it were its parent type. Comparable to the Java super keyword, but ensures the parent typeclass is also used in native code.

Overrides:

asParent in class GObject

Returns:

the instance as if it were its parent type

close

public void close()

Closes all the file descriptors previously passed to the object with g_subprocess_launcher_take_fd(), g_subprocess_launcher_take_stderr_fd(), etc.

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

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

Since:

2.68

getenv

public @Nullable String getenv(String variable)

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.

Parameters:

variable - the environment variable to get

Returns:

the value of the environment variable, null if unset

Since:

2.40

setChildSetup

public void setChildSetup(@Nullable SpawnChildSetupFunc childSetup)

Sets up a child setup function.

The child setup function will be called after fork() but before exec() on the child's side.

destroyNotify 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 childSetup to disable the functionality.

Child setup functions are only available on UNIX.

Parameters:

childSetup - a GSpawnChildSetupFunc to use as the child setup function

Since:

2.40

setCwd

public void setCwd(String cwd)

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.

Parameters:

cwd - the cwd for launched processes

Since:

2.40

setEnviron

public void setEnviron(@Nullable String @Nullable [] env)

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.

Pass an empty array to set an empty environment. Pass null to inherit the parent process’ environment. As of GLib 2.54, the parent process’ environment will be copied when g_subprocess_launcher_set_environ() is called. Previously, it was copied when the subprocess was executed. This means the copied environment may now be modified (using g_subprocess_launcher_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.

Parameters:

env - the replacement environment

Since:

2.40

setFlags

public void setFlags(Set<SubprocessFlags> flags)

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 g_subprocess_launcher_set_stdin_file_path() or g_subprocess_launcher_take_stdout_fd().

Parameters:

flags - GSubprocessFlags

Since:

2.40

setFlags

public void setFlags(SubprocessFlags... flags)

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 g_subprocess_launcher_set_stdin_file_path() or g_subprocess_launcher_take_stdout_fd().

Parameters:

flags - GSubprocessFlags

Since:

2.40

setStderrFilePath

public void setStderrFilePath(@Nullable String path)

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

Parameters:

path - a filename or null

Since:

2.40

setStdinFilePath

public void setStdinFilePath(@Nullable String path)

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.

Parameters:

path - a filename or null

Since:

2.40

setStdoutFilePath

public void setStdoutFilePath(@Nullable String path)

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.

Parameters:

path - a filename or null

Since:

2.40

setenv

public void setenv(String variable,
 String value,
 boolean overwrite)

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.

Parameters:

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

Since:

2.40

spawn

public Subprocess spawn(GError[] error,
 String argv0,
 Object... varargs)

Creates a GSubprocess given a provided varargs list of arguments.

Parameters:

error - Error

argv0 - Command line arguments

varargs - Continued arguments, null terminated

Returns:

A new GSubprocess, or null on error (and error will be set)

Since:

2.40

spawnv

public Subprocess spawnv(@Nullable String @Nullable [] argv)
                  throws GErrorException

Creates a GSubprocess given a provided array of arguments.

Parameters:

argv - Command line arguments

Returns:

A new GSubprocess, or null on error (and error will be set)

Throws:

GErrorException - see GError

Since:

2.40

takeFd

public void takeFd(int sourceFd,
 int targetFd)

Transfer an arbitrary file descriptor from parent process to the child. This function takes ownership of the sourceFd; it will be closed in the parent when this SubprocessLauncher 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.

Parameters:

sourceFd - File descriptor in parent process

targetFd - Target descriptor for child process

takeStderrFd

public void takeStderrFd(int fd)

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.

Parameters:

fd - a file descriptor, or -1

Since:

2.40

takeStdinFd

public void takeStdinFd(int fd)

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.

Parameters:

fd - a file descriptor, or -1

Since:

2.40

takeStdoutFd

public void takeStdoutFd(int fd)

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.

Parameters:

fd - a file descriptor, or -1

Since:

2.40

unsetenv

public void unsetenv(String variable)

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.

Parameters:

variable - the environment variable to unset, must not contain '='

Since:

2.40

builder

public static SubprocessLauncher.Builder<? extends SubprocessLauncher.Builder> builder()

A SubprocessLauncher.Builder object constructs a SubprocessLauncher with the specified properties. Use the various set...() methods to set properties, and finish construction with SubprocessLauncher.Builder.build().

Returns:

the builder object