execute an external command More...

#include <system_exec.h>

Inheritance diagram for PBD::SystemExec:

Public Member Functions
	SystemExec (std::string c, std::string a="")

	SystemExec (std::string c, char **a)

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

virtual	~SystemExec ()

int	start (int stderr_mode, const char *_vfork_exec_wrapper)

void	terminate ()

bool	is_running ()

int	wait (int options=0)

void	close_stdin ()

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

void	output_interposer ()

Public Attributes
PBD::Signal2< void, std::string, size_t >	ReadStdout

PBD::Signal0< 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 ()

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

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 70 of file system_exec.h.

Constructor & Destructor Documentation

SystemExec::SystemExec	(	std::string	c,
		std::string	a = `""`
	)

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

c	program pathname that identifies the new process image file.
a	string of commandline-arguments to be passed to the new program.

Definition at line 176 of file system_exec.cc.

SystemExec::SystemExec	(	std::string	c,
		char **	a
	)

similar to SystemExec but allows to specify custom arguments

Parameters

c	program pathname that identifies the new process image file.
a	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.

Definition at line 186 of file system_exec.cc.

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

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) returns an argv array suitable for creating a new SystemExec with

Definition at line 197 of file system_exec.cc.

SystemExec::~SystemExec ( )

virtual

Reimplemented in ARDOUR::SystemExec.

Definition at line 285 of file system_exec.cc.

Member Function Documentation

void 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()

Definition at line 905 of file system_exec.cc.

void SystemExec::init ( )

private

Definition at line 161 of file system_exec.cc.

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

Definition at line 704 of file system_exec.cc.

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

protected

Definition at line 595 of file system_exec.cc.

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

protected

Definition at line 216 of file system_exec.cc.

void SystemExec::make_envp ( )

protected

Definition at line 583 of file system_exec.cc.

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

Definition at line 870 of file system_exec.cc.

int SystemExec::start	(	int	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.

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

Definition at line 713 of file system_exec.cc.

void 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

Definition at line 636 of file system_exec.cc.

int 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

option flags - see waitpid manual

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

Definition at line 679 of file system_exec.cc.

int SystemExec::write_to_stdin	(	std::string	d,
		size_t	len = `0`
	)

write into child-program's STDIN

Parameters

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

Definition at line 915 of file system_exec.cc.

Member Data Documentation

char** PBD::SystemExec::argp

protected

Definition at line 207 of file system_exec.h.

std::string PBD::SystemExec::cmd

protected

path to command - set when creating the class

Definition at line 200 of file system_exec.h.

char** PBD::SystemExec::envp

protected

Definition at line 208 of file system_exec.h.

int PBD::SystemExec::nicelevel

protected

process nice level - defaults to 0

Definition at line 201 of file system_exec.h.

pid_t PBD::SystemExec::pid

private

Definition at line 219 of file system_exec.h.

int PBD::SystemExec::pin[2]

private

Definition at line 225 of file system_exec.h.

int PBD::SystemExec::pok[2]

private

Definition at line 224 of file system_exec.h.

int PBD::SystemExec::pout[2]

private

Definition at line 226 of file system_exec.h.

PBD::Signal2<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 176 of file system_exec.h.

PBD::Signal0<void> PBD::SystemExec::Terminated

The Terminated signal is emitted when application terminates.

Definition at line 183 of file system_exec.h.

bool PBD::SystemExec::thread_active

private

Definition at line 229 of file system_exec.h.

pthread_t PBD::SystemExec::thread_id_tt

private

Definition at line 228 of file system_exec.h.

pthread_mutex_t PBD::SystemExec::write_lock

private

Definition at line 222 of file system_exec.h.

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

/usr/local/music/src/ardour/4.0/libs/pbd/pbd/system_exec.h
/usr/local/music/src/ardour/4.0/libs/pbd/system_exec.cc

Public Member Functions

Public Attributes

Protected Member Functions

Protected Attributes

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation