execute an external command More...

#include <system_exec.h>

Inheritance diagram for PBD::SystemExec:

Public Types
enum	StdErrMode { ShareWithParent = 0 , IgnoreAndClose = 1 , MergeWithStdin = 2 }

Public Member Functions
	SystemExec (std::string cmd, std::string argv="", bool supress_ld_env=false)

	SystemExec (std::string cmd, char **argv, bool supress_ld_env=false)

	SystemExec (std::string command, const std::map< char, std::string > subs, bool supress_ld_env=false)

virtual	~SystemExec ()

std::string	to_s () const

int	start (StdErrMode stderr_mode, const char *_vfork_exec_wrapper)

void	terminate ()

bool	is_running ()

int	wait (int options=0)

void	close_stdin ()

size_t	write_to_stdin (std::string const &d, size_t len=0)

size_t	write_to_stdin (const char *d, size_t len=0)

size_t	write_to_stdin (const void *data, size_t bytes=0)

void	output_interposer ()

Static Public Member Functions
static char *	format_key_value_parameter (std::string, std::string)

Public Attributes
PBD::Signal< void(std::string, size_t)>	ReadStdout

PBD::Signal< void()>	Terminated

Protected Member Functions
void	make_argp (std::string)

void	make_argp_escaped (std::string command, const std::map< char, std::string > subs)

void	make_envp (bool supress_ld_env)

Protected Attributes
std::string	cmd
	path to command - set when creating the class More...

int	nicelevel
	process nice level - defaults to 0 More...

char **	argp

char **	envp

Private Member Functions
void	init ()

Private Attributes
pid_t	pid

char **	argx

pthread_mutex_t	write_lock

int	pok [2]

int	pin [2]

int	pout [2]

pthread_t	thread_id_tt

bool	thread_active

Detailed Description

execute an external command

This class allows launche an external command-line application opening a full-duplex connection to its standard I/O.

In Ardour context it is used to launch xjadeo and ffmpeg.

The write_to_stdin function provides for injecting data into STDIN of the child-application while output of the program to STDOUT/STDERR is forwarded using the ReadStdout signal. Terminated is sent if the child application exits.

Definition at line 72 of file pbd/pbd/system_exec.h.

Member Enumeration Documentation

◆ StdErrMode

enum PBD::SystemExec::StdErrMode

Enumerator
ShareWithParent
IgnoreAndClose
MergeWithStdin

Definition at line 125 of file pbd/pbd/system_exec.h.

Constructor & Destructor Documentation

◆ SystemExec() [1/3]

PBD::SystemExec::SystemExec	(	std::string	cmd,
		std::string	argv = `""`,
		bool	supress_ld_env = `false`
	)

prepare execution of a program with 'execve'

This function takes over the existing environment variable and provides an easy way to speciy command-line arguments for the new process.

Note: The argument parser does not interpret quotation-marks and splits arugments on whitespace. The argument string can be empty. The alternative constructor below allows to specify quoted parameters incl. whitespace.

Parameters

cmd	program pathname that identifies the new process image file.
argv	string of commandline-arguments to be passed to the new program.
supress_ld_env	On Linux, unset LD_LIBRARY_PATH environment variable

◆ SystemExec() [2/3]

PBD::SystemExec::SystemExec	(	std::string	cmd,
		char **	argv,
		bool	supress_ld_env = `false`
	)

similar to SystemExec but allows to specify custom arguments

Parameters

cmd	program pathname that identifies the new process image file.
argv	array of argument strings passed to the new program as 'argv'. it must be terminated by a null pointer (see the 'evecve' POSIX-C documentation for more information) The array must be dynamically allocated using malloc or strdup. Unless they're NULL, the array itself and each of its content memory is freed() in the destructor.
supress_ld_env	On Linux, unset LD_LIBRARY_PATH environment variable

◆ SystemExec() [3/3]

PBD::SystemExec::SystemExec	(	std::string	command,
		const std::map< char, std::string >	subs,
		bool	supress_ld_env = `false`
	)

similar to SystemExec but expects a whole command line, and handles some simple escape sequences.

Parameters

command	complete command-line to be executed
subs	a map of <char, std::string> listing the % substitutions to be made.

creates an argv array from the given command string, splitting into parameters at spaces. "\ " is non-splitting space, "\\" (and "\" at end of command) as "\", for "%<char>", <char> is looked up in subs and the corresponding string substituted. "%%" (and "%" at end of command)

Parameters

supress_ld_env On Linux, unset LD_LIBRARY_PATH environment variable

◆ ~SystemExec()

virtual PBD::SystemExec::~SystemExec ( )

virtual

Reimplemented in ARDOUR::SystemExec.

Member Function Documentation

◆ close_stdin()

void PBD::SystemExec::close_stdin ( )

closes both STDIN and STDOUT connections to/from the child-program. With the output-interposer thread gone, the program should terminate. used by terminate()

◆ format_key_value_parameter()

static char* PBD::SystemExec::format_key_value_parameter	(	std::string	,
		std::string
	)

static

◆ init()

void PBD::SystemExec::init ( )

private

◆ is_running()

bool PBD::SystemExec::is_running ( )

check if the child programm is (still) running.

This function calls waitpid(WNOHANG) to check the state of the child-process.

Returns: true if the program is (still) running.

◆ make_argp()

void PBD::SystemExec::make_argp ( std::string )

protected

◆ make_argp_escaped()

void PBD::SystemExec::make_argp_escaped	(	std::string	command,
		const std::map< char, std::string >	subs
	)

protected

◆ make_envp()

void PBD::SystemExec::make_envp ( bool supress_ld_env )

protected

◆ output_interposer()

void PBD::SystemExec::output_interposer ( )

interposer to emit signal for writes to STDOUT/ERR.

Thread that reads the stdout of the forked process and signal-sends it to the main thread. It also emits the Terminated() signal once the the forked process closes it's stdout.

Note: it's actually 'private' function but used by the internal pthread, which only has a pointer to this instance and thus can only access public fn.

◆ start()

int PBD::SystemExec::start	(	StdErrMode	stderr_mode,
		const char *	_vfork_exec_wrapper
	)

fork and execute the given program

Parameters

stderr_mode	select what to do with program's standard error output: '0': keep STDERR; mix it with parent-process' STDERR '1': ignore STDERR of child-program '2': merge STDERR into STDOUT and send it with the ReadStdout signal.
_vfork_exec_wrapper	path to vfork-wrapper binary

Returns: If the process is already running or was launched successfully the function returns zero (0). A negative number indicates an error.

◆ terminate()

void PBD::SystemExec::terminate ( )

kill running child-process

if a child process exists trt to shut it down by closing its STDIN. if the program dies not react try SIGTERM and eventually SIGKILL

◆ to_s()

std::string PBD::SystemExec::to_s ( ) const

◆ wait()

int PBD::SystemExec::wait ( int options = 0 )

call the waitpid system-call with the pid of the child-program

Basically what terminate uses internally.

This function is only useful if you want to control application termination yourself (eg timeouts or progress-dialog).

Parameters

options flags - see waitpid manual

Returns: status info from waitpid call (not waitpid's return value) or -1 if the child-program is not running.

◆ write_to_stdin() [1/3]

size_t PBD::SystemExec::write_to_stdin	(	const char *	d,
		size_t	len = `0`
	)

write into child-program's STDIN

Parameters

d	text to write
len	length of data to write, if it is 0 (zero), d.length() is used to determine the number of bytes to transmit.

Returns: number of bytes written.

◆ write_to_stdin() [2/3]

size_t PBD::SystemExec::write_to_stdin	(	const void *	data,
		size_t	bytes = `0`
	)

write into child-program's STDIN

Parameters

data	data to write
bytes	length of data to write

Returns: number of bytes written.

◆ write_to_stdin() [3/3]

size_t PBD::SystemExec::write_to_stdin	(	std::string const &	d,
		size_t	len = `0`
	)

write into child-program's STDIN

Parameters

d	text to write
len	length of data to write, if it is 0 (zero), d.length() is used to determine the number of bytes to transmit.

Returns: number of bytes written.

Member Data Documentation

◆ argp

char** PBD::SystemExec::argp

protected

Definition at line 236 of file pbd/pbd/system_exec.h.

◆ argx

char** PBD::SystemExec::argx

private

Definition at line 249 of file pbd/pbd/system_exec.h.

◆ cmd

std::string PBD::SystemExec::cmd

protected

path to command - set when creating the class

Definition at line 229 of file pbd/pbd/system_exec.h.

◆ envp

char** PBD::SystemExec::envp

protected

Definition at line 237 of file pbd/pbd/system_exec.h.

◆ nicelevel

int PBD::SystemExec::nicelevel

protected

process nice level - defaults to 0

Definition at line 230 of file pbd/pbd/system_exec.h.

◆ pid

pid_t PBD::SystemExec::pid

private

Definition at line 248 of file pbd/pbd/system_exec.h.

◆ pin

int PBD::SystemExec::pin[2]

private

Definition at line 255 of file pbd/pbd/system_exec.h.

◆ pok

int PBD::SystemExec::pok[2]

private

Definition at line 254 of file pbd/pbd/system_exec.h.

◆ pout

int PBD::SystemExec::pout[2]

private

Definition at line 256 of file pbd/pbd/system_exec.h.

◆ ReadStdout

PBD::Signal<void(std::string,size_t)> PBD::SystemExec::ReadStdout

The ReadStdout signal is emitted when the application writes to STDOUT. it passes the written data and its length in bytes as arguments to the bound slot(s).

Definition at line 205 of file pbd/pbd/system_exec.h.

◆ Terminated

PBD::Signal<void()> PBD::SystemExec::Terminated

The Terminated signal is emitted when application terminates.

Definition at line 212 of file pbd/pbd/system_exec.h.

◆ thread_active

bool PBD::SystemExec::thread_active

private

Definition at line 259 of file pbd/pbd/system_exec.h.

◆ thread_id_tt

pthread_t PBD::SystemExec::thread_id_tt

private

Definition at line 258 of file pbd/pbd/system_exec.h.

◆ write_lock

pthread_mutex_t PBD::SystemExec::write_lock

private

Definition at line 252 of file pbd/pbd/system_exec.h.

The documentation for this class was generated from the following file:

pbd/pbd/system_exec.h

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Protected Member Functions

Protected Attributes

Private Member Functions

Private Attributes

Detailed Description

Member Enumeration Documentation

◆ StdErrMode

Constructor & Destructor Documentation

◆ SystemExec() [1/3]

◆ SystemExec() [2/3]

◆ SystemExec() [3/3]

◆ ~SystemExec()

Member Function Documentation

◆ close_stdin()

◆ format_key_value_parameter()

◆ init()

◆ is_running()

◆ make_argp()

◆ make_argp_escaped()

◆ make_envp()

◆ output_interposer()

◆ start()

◆ terminate()

◆ to_s()

◆ wait()

◆ write_to_stdin() [1/3]

◆ write_to_stdin() [2/3]

◆ write_to_stdin() [3/3]

Member Data Documentation

◆ argp

◆ argx

◆ cmd

◆ envp

◆ nicelevel

◆ pid

◆ pin

◆ pok

◆ pout

◆ ReadStdout

◆ Terminated

◆ thread_active

◆ thread_id_tt

◆ write_lock