glibmm: Gio::SubprocessLauncher Class Reference

Environment options for launching a child process. More...

#include <giomm/subprocesslauncher.h>

Inheritance diagram for Gio::SubprocessLauncher:

[legend]

Public Member Functions
	SubprocessLauncher (SubprocessLauncher && src) noexcept

SubprocessLauncher &	operator= (SubprocessLauncher && src) noexcept

	~SubprocessLauncher () noexcept override

GSubprocessLauncher *	gobj ()
	Provides access to the underlying C GObject. More...

const GSubprocessLauncher *	gobj () const
	Provides access to the underlying C GObject. More...

GSubprocessLauncher *	gobj_copy ()
	Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs. More...

Glib::RefPtr< Subprocess >	spawn (const std::vector< std::string > & argv)
	Creates a Subprocess given a provided array of arguments. More...

void	inherit_environ ()
	Inherit the parent process’ environment. More...

void	set_environ (const std::vector< std::string > & env)
	Replace the entire environment of processes launched from this launcher with the given 'environ' variable. More...

void	setenv (const std::string & variable, const std::string & value, bool overwrite)
	Sets the environment variable variable in the environment of processes launched from this launcher. More...

void	unsetenv (const std::string & variable)
	Removes the environment variable variable from the environment of processes launched from this launcher. More...

std::string	getenv (const std::string & variable)
	Returns the value of the environment variable variable in the environment of processes launched from this launcher. More...

void	set_cwd (const std::string & cwd)
	Sets the current working directory that processes will be launched with. More...

void	set_flags (Subprocess::Flags flags)
	Sets the flags on the launcher. More...

void	set_stdin_file_path (const std::string & path)
	Sets the file path to use as the stdin for spawned processes. More...

void	take_stdin_fd (int fd)
	Sets the file descriptor to use as the stdin for spawned processes. More...

void	set_stdout_file_path (const std::string & path)
	Sets the file path to use as the stdout for spawned processes. More...

void	take_stdout_fd (int fd)
	Sets the file descriptor to use as the stdout for spawned processes. More...

void	set_stderr_file_path (const std::string & path)
	Sets the file path to use as the stderr for spawned processes. More...

void	take_stderr_fd (int fd)
	Sets the file descriptor to use as the stderr for spawned processes. More...

void	take_fd (int source_fd, int target_fd)
	Transfer an arbitrary file descriptor from parent process to the child. More...

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

void	set_child_setup (const Glib::SlotSpawnChildSetup & child_setup={})
	Sets up a child setup function. More...

Public Member Functions inherited from Glib::Object
	Object (const Object &)=delete

Object &	operator= (const Object &)=delete

	Object (Object && src) noexcept

Object &	operator= (Object && src) noexcept

void *	get_data (const QueryQuark & key)

void	set_data (const Quark & key, void *data)

void	set_data_with_c_callback (const Quark & key, void *data, GDestroyNotify notify)

void	set_data (const Quark & key, void *data, DestroyNotify notify)
	Prefer set_data_with_c_callback() with a callback with C linkage. More...

void	remove_data (const QueryQuark & quark)

void *	steal_data (const QueryQuark & quark)

Public Member Functions inherited from Glib::ObjectBase
	ObjectBase (const ObjectBase &)=delete

ObjectBase &	operator= (const ObjectBase &)=delete

void	set_property_value (const Glib::ustring & property_name, const Glib::ValueBase & value)
	You probably want to use a specific property_*() accessor method instead. More...

void	get_property_value (const Glib::ustring & property_name, Glib::ValueBase & value) const
	You probably want to use a specific property_*() accessor method instead. More...

template<class PropertyType >
void	set_property (const Glib::ustring & property_name, const PropertyType & value)
	You probably want to use a specific property_*() accessor method instead. More...

template<class PropertyType >
void	get_property (const Glib::ustring & property_name, PropertyType & value) const
	You probably want to use a specific property_*() accessor method instead. More...

template<class PropertyType >
PropertyType	get_property (const Glib::ustring & property_name) const
	You probably want to use a specific property_*() accessor method instead. More...

sigc::connection	connect_property_changed (const Glib::ustring & property_name, const sigc::slot< void()> & slot)
	You can use the signal_changed() signal of the property proxy instead. More...

sigc::connection	connect_property_changed (const Glib::ustring & property_name, sigc::slot< void()> && slot)
	You can use the signal_changed() signal of the property proxy instead. More...

void	freeze_notify ()
	Increases the freeze count on object. More...

void	thaw_notify ()
	Reverts the effect of a previous call to freeze_notify(). More...

virtual void	reference () const
	Increment the reference count for this object. More...

virtual void	unreference () const
	Decrement the reference count for this object. More...

GObject *	gobj ()
	Provides access to the underlying C GObject. More...

const GObject *	gobj () const
	Provides access to the underlying C GObject. More...

GObject *	gobj_copy () const
	Give a ref-ed copy to someone. Use for direct struct access. More...

Static Public Member Functions
static GType	get_type ()
	Get the GType for this class, for use with the underlying GObject type system. More...

static Glib::RefPtr< SubprocessLauncher >	create (Subprocess::Flags flags=Subprocess::Flags::NONE)
	Creates a new SubprocessLauncher. More...

Related Functions
(Note that these are not member functions.)
Glib::RefPtr< Gio::SubprocessLauncher >	wrap (GSubprocessLauncher * object, bool take_copy=false)
	A Glib::wrap() method for this object. More...

Related Functions inherited from Glib::Object
Glib::RefPtr< Glib::Object >	wrap (GObject * object, bool take_copy=false)

Additional Inherited Members
Public Types inherited from Glib::Object
using	DestroyNotify = void(*)(gpointer data)

Protected Member Functions inherited from Glib::Object
	Object ()

	Object (const Glib::ConstructParams & construct_params)

	Object (GObject * castitem)

	~Object () noexcept override

Protected Member Functions inherited from Glib::ObjectBase
	ObjectBase ()
	This default constructor is called implicitly from the constructor of user-derived classes, even if, for instance, Gtk::Button calls a different ObjectBase constructor. More...

	ObjectBase (const char * custom_type_name)
	A derived constructor always overrides this choice. More...

	ObjectBase (const std::type_info & custom_type_info)
	This constructor is a special feature to allow creation of derived types on the fly, without having to use g_object_new() manually. More...

	ObjectBase (ObjectBase && src) noexcept

ObjectBase &	operator= (ObjectBase && src) noexcept

virtual	~ObjectBase () noexcept=0

void	initialize (GObject * castitem)

void	initialize_move (GObject * castitem, Glib::ObjectBase * previous_wrapper)

Detailed 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 Gio::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.

See also: Subprocess

Since glibmm 2.78:

Constructor & Destructor Documentation

◆ SubprocessLauncher()

Gio::SubprocessLauncher::SubprocessLauncher ( SubprocessLauncher && src )

noexcept

◆ ~SubprocessLauncher()

Gio::SubprocessLauncher::~SubprocessLauncher ( )

overridenoexcept

Member Function Documentation

◆ close()

void Gio::SubprocessLauncher::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 Gio::Error::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.

Since glibmm 2.78:

◆ create()

static Glib::RefPtr< SubprocessLauncher > Gio::SubprocessLauncher::create ( Subprocess::Flags flags = Subprocess::Flags::NONE )

static

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.

Since glibmm 2.78:

Parameters

flags SubprocessFlags.

◆ get_type()

static GType Gio::SubprocessLauncher::get_type ( )

static

Get the GType for this class, for use with the underlying GObject type system.

◆ getenv()

std::string Gio::SubprocessLauncher::getenv ( const std::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.

Since glibmm 2.78:

Parameters

variable The environment variable to get.

Returns: The value of the environment variable, nullptr if unset.

◆ gobj() [1/2]

GSubprocessLauncher * Gio::SubprocessLauncher::gobj ( )

inline

Provides access to the underlying C GObject.

◆ gobj() [2/2]

const GSubprocessLauncher * Gio::SubprocessLauncher::gobj ( ) const

inline

Provides access to the underlying C GObject.

◆ gobj_copy()

GSubprocessLauncher * Gio::SubprocessLauncher::gobj_copy ( )

Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.

◆ inherit_environ()

void Gio::SubprocessLauncher::inherit_environ ( )

Inherit the parent process’ environment.

Since glibmm 2.78:

◆ operator=()

SubprocessLauncher & Gio::SubprocessLauncher::operator= ( SubprocessLauncher && src )

noexcept

◆ set_child_setup()

void Gio::SubprocessLauncher::set_child_setup ( const Glib::SlotSpawnChildSetup & child_setup = {} )

Sets up a child setup function.

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

A copy of the child_setup slot is stored. The copy will not be automatically deleted on the child's side of the fork(). It will only be deleted when the last reference on the SubprocessLauncher is dropped or when a new child setup slot is given.

An empty slot can be given as child_setup to disable the functionality.

Child setup functions are only available on UNIX.

Since glibmm 2.78:

Parameters

child_setup A Glib::SlotSpawnChildSetup to use as the child setup function.

◆ set_cwd()

void Gio::SubprocessLauncher::set_cwd ( const std::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.

Since glibmm 2.78:

Parameters

cwd	The cwd for launched processes.

◆ set_environ()

void Gio::SubprocessLauncher::set_environ ( const std::vector< std::string > & env )

Replace the entire environment of processes launched from this launcher with the given 'environ' variable.

Typically you will build this variable by using Glib::listenv() to copy the process 'environ' and using the functions Glib::environ_setenv(), Glib::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 nullptr 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.

Since glibmm 2.78:

Parameters

env	The replacement environment.

◆ set_flags()

void Gio::SubprocessLauncher::set_flags ( Subprocess::Flags flags )

Sets the flags on the launcher.

The default flags are Gio::Subprocess::Flags::NONE.

You may not set flags that specify conflicting options for how to handle a particular stdio stream (eg: specifying both Gio::Subprocess::Flags::STDIN_PIPE and Gio::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 glibmm 2.78:

Parameters

flags SubprocessFlags.

◆ set_stderr_file_path()

void Gio::SubprocessLauncher::set_stderr_file_path ( const std::string & path )

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

If path is nullptr 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 Gio::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 glibmm 2.78:

Parameters

path	A filename or `nullptr`.

◆ set_stdin_file_path()

void Gio::SubprocessLauncher::set_stdin_file_path ( const std::string & path )

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

If path is nullptr 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 glibmm 2.78:

Parameters

path	A filename or `nullptr`.

◆ set_stdout_file_path()

void Gio::SubprocessLauncher::set_stdout_file_path ( const std::string & path )

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

If path is nullptr 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 glibmm 2.78:

Parameters

path	A filename or `nullptr`.

◆ setenv()

void Gio::SubprocessLauncher::setenv	(	const std::string &	variable,
		const std::string &	value,
		bool	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.

Since glibmm 2.78:

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.

◆ spawn()

Glib::RefPtr< Subprocess > Gio::SubprocessLauncher::spawn ( const std::vector< std::string > & argv )

Creates a Subprocess given a provided array of arguments.

Since glibmm 2.78:

Parameters

argv	Command line arguments.

Returns: A new Subprocess, or nullptr on error (and error will be set).

Exceptions

Glib::Error

◆ take_fd()

void Gio::SubprocessLauncher::take_fd	(	int	source_fd,
		int	target_fd
	)

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.

Since glibmm 2.78:

Parameters

source_fd	File descriptor in parent process.
target_fd	Target descriptor for child process.

◆ take_stderr_fd()

void Gio::SubprocessLauncher::take_stderr_fd ( 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 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.

Since glibmm 2.78:

Parameters

fd	A file descriptor, or -1.

◆ take_stdin_fd()

void Gio::SubprocessLauncher::take_stdin_fd ( 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 Gio::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 glibmm 2.78:

Parameters

fd	A file descriptor, or -1.

◆ take_stdout_fd()

void Gio::SubprocessLauncher::take_stdout_fd ( 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.

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 glibmm 2.78:

Parameters

fd	A file descriptor, or -1.

◆ unsetenv()

void Gio::SubprocessLauncher::unsetenv ( const std::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.

Since glibmm 2.78:

Parameters

variable The environment variable to unset, must not contain '='.

Friends And Related Function Documentation

◆ wrap()

Glib::RefPtr< Gio::SubprocessLauncher > wrap	(	GSubprocessLauncher *	object,
		bool	take_copy = `false`
	)

A Glib::wrap() method for this object.

Parameters

object	The C instance.
take_copy	False if the result should take ownership of the C instance. True if it should take a new copy or ref.

Returns: A C++ instance that wraps this C instance.

Public Member Functions

Static Public Member Functions

Related Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ SubprocessLauncher()

◆ ~SubprocessLauncher()

Member Function Documentation

◆ close()

◆ create()

◆ get_type()

◆ getenv()

◆ gobj() [1/2]

◆ gobj() [2/2]

◆ gobj_copy()

◆ inherit_environ()

◆ operator=()

◆ set_child_setup()

◆ set_cwd()

◆ set_environ()

◆ set_flags()

◆ set_stderr_file_path()

◆ set_stdin_file_path()

◆ set_stdout_file_path()

◆ setenv()

◆ spawn()

◆ take_fd()

◆ take_stderr_fd()

◆ take_stdin_fd()

◆ take_stdout_fd()

◆ unsetenv()

Friends And Related Function Documentation

◆ wrap()