This class runs an external executable. More...

#include <arc/Run.h>

Data Structures
class	Data

class	StringData

Public Member Functions
	Run (const std::string &cmdline)
	Constructor prepares object to run cmdline. More...

	Run (const std::list< std::string > &argv)
	Constructor prepares object to run executable and arguments specified in argv. More...

	~Run (void)
	Destructor kills running executable and releases associated resources. More...

	operator bool (void)
	Returns true if object is valid. More...

bool	operator! (void)
	Returns true if object is invalid. More...

bool	Start (void)
	Starts running executable. This method may be called only once. More...

bool	Wait (int timeout)
	Wait till execution finished or till timeout seconds expires. More...

bool	Wait (void)
	Wait till execution finished. More...

int	Result (void)
	Returns exit code of execution. More...

bool	Running (void)
	Return true if execution is going on. More...

Time	RunTime (void)
	Returns time when executable was started. More...

Time	ExitTime (void)
	Return time when executable finished executing. More...

int	ReadStdout (int timeout, char *buf, int size)
	Read from stdout pipe of running executable. More...

int	ReadStderr (int timeout, char *buf, int size)
	Read from stderr pipe of running executable. More...

int	WriteStdin (int timeout, const char *buf, int size)
	Write to stdin pipe of running executable. More...

void	AssignStdout (std::string &str, int max_size=102400)
	Associate stdout pipe of executable with string. More...

void	AssignStdout (Data &str)

void	AssignStderr (std::string &str, int max_size=102400)
	Associate stderr pipe of executable with string. More...

void	AssignStderr (Data &str)

void	AssignStdin (std::string &str)
	Associate stdin pipe of executable with string. More...

void	AssignStdin (Data &str)

void	KeepStdout (bool keep=true)
	Keep stdout same as parent's if keep = true. No pipe will be created. More...

void	KeepStderr (bool keep=true)
	Keep stderr same as parent's if keep = true. No pipe will be created. More...

void	KeepStdin (bool keep=true)
	Keep stdin same as parent's if keep = true. No pipe will be created. More...

void	CloseStdout (void)
	Closes pipe associated with stdout handle. More...

void	CloseStderr (void)
	Closes pipe associated with stderr handle. More...

void	CloseStdin (void)
	Closes pipe associated with stdin handle. More...

void	AssignInitializer (void(initializer_func)(void ), void *initializer_arg)
	Assign a function to be called just after process is forked but before execution starts. More...

void	AssignKicker (void(kicker_func)(void ), void *kicker_arg)
	Assign a function to be called just after execution ends. It is executed asynchronously. More...

void	AssignWorkingDirectory (std::string &wd)
	Assign working directory of the process to run. More...

void	AssignUserId (int uid)
	Assign uid for the process to run under. More...

void	AssignGroupId (int gid)
	Assign gid for the process to run under. More...

void	AddEnvironment (const std::string &key, const std::string &value)
	Add environment variable to be passed to process before it is run. More...

void	AddEnvironment (const std::string &var)
	Add environment variable to be passed to process before it is run. More...

void	RemoveEnvironment (const std::string &key)
	Remove environment variable to be passed to process before it is run. More...

void	Kill (int timeout)
	Kill running executable. More...

void	Abandon (void)
	Detach this object from running process. More...

Static Public Member Functions
static void	AfterFork (void)
	Call this method after fork() in child process. More...

Protected Types
typedef bool(Run::*	HandleHandler) ()

typedef bool(Run::*	PidHandler) (int)

Protected Member Functions
bool	stdout_handler ()

bool	stderr_handler ()

bool	stdin_handler ()

void	child_handler (int result)

Protected Attributes
std::string	working_directory

int	stdout_

int	stderr_

int	stdin_

Data *	stdout_str_

Data *	stderr_str_

Data *	stdin_str_

StringData	stdout_str_wrap_

StringData	stderr_str_wrap_

StringData	stdin_str_wrap_

bool	stdout_keep_

bool	stderr_keep_

bool	stdin_keep_

pid_t	pid_

std::list< std::string >	argv_

std::list< std::string >	envp_

std::list< std::string >	envx_

void(*	initializer_func_ )(void *)

void *	initializer_arg_

void(*	kicker_func_ )(void *)

void *	kicker_arg_

bool	started_

bool	running_

bool	abandoned_

int	result_

Glib::Mutex	lock_

Glib::Cond	cond_

int	user_id_

int	group_id_

Time	run_time_

Time	exit_time_

Friends
class	RunPump

Detailed Description

This class runs an external executable.

It is possible to read from or write to its standard handles or to redirect them to std::string elements.

Constructor & Destructor Documentation

◆ Run() [1/2]

Arc::Run::Run ( const std::string & cmdline )

Constructor prepares object to run cmdline.

◆ Run() [2/2]

Arc::Run::Run ( const std::list< std::string > & argv )

Constructor prepares object to run executable and arguments specified in argv.

◆ ~Run()

Arc::Run::~Run ( void )

Destructor kills running executable and releases associated resources.

Member Function Documentation

◆ Abandon()

void Arc::Run::Abandon ( void )

Detach this object from running process.

After calling this method class instance is not associated with external process anymore. As result destructor will not kill process.

◆ AddEnvironment() [1/2]

void Arc::Run::AddEnvironment	(	const std::string &	key,
		const std::string &	value
	)

inline

Add environment variable to be passed to process before it is run.

◆ AddEnvironment() [2/2]

void Arc::Run::AddEnvironment ( const std::string & var )

inline

Add environment variable to be passed to process before it is run.

◆ AfterFork()

static void Arc::Run::AfterFork ( void )

static

Call this method after fork() in child process.

It will reinitialize internal structures for new environment. Do not call it in any other case than defined.

◆ AssignGroupId()

void Arc::Run::AssignGroupId ( int gid )

inline

Assign gid for the process to run under.

◆ AssignInitializer()

void Arc::Run::AssignInitializer	(	void()(void )	initializer_func,
		void *	initializer_arg
	)

Assign a function to be called just after process is forked but before execution starts.

◆ AssignKicker()

void Arc::Run::AssignKicker	(	void()(void )	kicker_func,
		void *	kicker_arg
	)

Assign a function to be called just after execution ends. It is executed asynchronously.

◆ AssignStderr()

void Arc::Run::AssignStderr	(	std::string &	str,
		int	max_size = `102400`
	)

Associate stderr pipe of executable with string.

This method must be called before Start(). str object must be valid as long as this object exists.

◆ AssignStdin()

void Arc::Run::AssignStdin ( std::string & str )

Associate stdin pipe of executable with string.

This method must be called before Start(). str object must be valid as long as this object exists.

◆ AssignStdout()

void Arc::Run::AssignStdout	(	std::string &	str,
		int	max_size = `102400`
	)

Associate stdout pipe of executable with string.

This method must be called before Start(). str object must be valid as long as this object exists.

◆ AssignUserId()

void Arc::Run::AssignUserId ( int uid )

inline

Assign uid for the process to run under.

◆ AssignWorkingDirectory()

void Arc::Run::AssignWorkingDirectory ( std::string & wd )

inline

Assign working directory of the process to run.

◆ CloseStderr()

void Arc::Run::CloseStderr ( void )

Closes pipe associated with stderr handle.

◆ CloseStdin()

void Arc::Run::CloseStdin ( void )

Closes pipe associated with stdin handle.

◆ CloseStdout()

void Arc::Run::CloseStdout ( void )

Closes pipe associated with stdout handle.

◆ ExitTime()

Time Arc::Run::ExitTime ( void )

inline

Return time when executable finished executing.

◆ KeepStderr()

void Arc::Run::KeepStderr ( bool keep = true )

Keep stderr same as parent's if keep = true. No pipe will be created.

◆ KeepStdin()

void Arc::Run::KeepStdin ( bool keep = true )

Keep stdin same as parent's if keep = true. No pipe will be created.

◆ KeepStdout()

void Arc::Run::KeepStdout ( bool keep = true )

Keep stdout same as parent's if keep = true. No pipe will be created.

◆ Kill()

void Arc::Run::Kill ( int timeout )

Kill running executable.

First soft kill signal (SIGTERM) is sent to executable. If after timeout seconds executable is still running it's killed forcefuly.

◆ operator bool()

Arc::Run::operator bool ( void )

inline

Returns true if object is valid.

◆ operator!()

bool Arc::Run::operator! ( void )

inline

Returns true if object is invalid.

◆ ReadStderr()

int Arc::Run::ReadStderr	(	int	timeout,
		char *	buf,
		int	size
	)

Read from stderr pipe of running executable.

This method may be used while stderr is directed to string, but the result is unpredictable.

Parameters

timeout	upper limit for which method will block in milliseconds. Negative means infinite.
buf	buffer to write the stderr to
size	size of buf

Returns: number of read bytes.

◆ ReadStdout()

int Arc::Run::ReadStdout	(	int	timeout,
		char *	buf,
		int	size
	)

Read from stdout pipe of running executable.

This method may be used while stdout is directed to string, but the result is unpredictable.

Parameters

timeout	upper limit for which method will block in milliseconds. Negative means infinite.
buf	buffer to write the stdout to
size	size of buf

Returns: number of read bytes.

◆ RemoveEnvironment()

void Arc::Run::RemoveEnvironment ( const std::string & key )

inline

Remove environment variable to be passed to process before it is run.

◆ Result()

int Arc::Run::Result ( void )

inline

Returns exit code of execution.

If child process was killed then exit code is -1. If code is compiled with support for detecting lost child process this code is -1 also if track of child was lost.

◆ Running()

bool Arc::Run::Running ( void )

Return true if execution is going on.

◆ RunTime()

Time Arc::Run::RunTime ( void )

inline

Returns time when executable was started.

◆ Start()

bool Arc::Run::Start ( void )

Starts running executable. This method may be called only once.

Returns: true if executable started without problems

◆ Wait() [1/2]

bool Arc::Run::Wait ( int timeout )

Wait till execution finished or till timeout seconds expires.

Returns: true if execution is complete.

◆ Wait() [2/2]

bool Arc::Run::Wait ( void )

Wait till execution finished.

Returns: true if execution is complete, false if execution was not started.

◆ WriteStdin()

int Arc::Run::WriteStdin	(	int	timeout,
		const char *	buf,
		int	size
	)

Write to stdin pipe of running executable.

This method may be used while stdin is directed to string, but the result is unpredictable.

Parameters

timeout	upper limit for which method will block in milliseconds. Negative means infinite.
buf	buffer to read the stdin from
size	size of buf

Returns: number of written bytes.

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

Run.h

Data Structures

Public Member Functions

Static Public Member Functions

Protected Types

Protected Member Functions

Protected Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

◆ Run() [1/2]

◆ Run() [2/2]

◆ ~Run()

Member Function Documentation

◆ Abandon()

◆ AddEnvironment() [1/2]

◆ AddEnvironment() [2/2]

◆ AfterFork()

◆ AssignGroupId()

◆ AssignInitializer()

◆ AssignKicker()

◆ AssignStderr()

◆ AssignStdin()

◆ AssignStdout()

◆ AssignUserId()

◆ AssignWorkingDirectory()

◆ CloseStderr()

◆ CloseStdin()

◆ CloseStdout()

◆ ExitTime()

◆ KeepStderr()

◆ KeepStdin()

◆ KeepStdout()

◆ Kill()

◆ operator bool()

◆ operator!()

◆ ReadStderr()

◆ ReadStdout()

◆ RemoveEnvironment()

◆ Result()

◆ Running()

◆ RunTime()

◆ Start()

◆ Wait() [1/2]

◆ Wait() [2/2]

◆ WriteStdin()