Async::Exec Class Reference

Execute external commands. More...

#include <AsyncExec.h>

Inheritance diagram for Async::Exec:

Public Types
using	Environment = std::vector<std::pair<std::string,std::string>>

Public Member Functions
	Exec (const std::string &cmdline="")
	Default constructor.
	~Exec (void)
	Destructor.
void	setCommandLine (const std::string &cmdline)
	Set the command line to use.
const std::string &	command (void) const
	Get the command name for the command.
void	appendArgument (const std::string &arg)
	Append a command line argument to a command.
void	clearEnvironment (void)
	Clear the environment.
void	addEnvironmentVar (const std::string &name, const std::string &val)
	Add an additional environment variable.
void	addEnvironmentVars (const Environment &env)
	Add multiple environment variables.
bool	nice (int inc=10)
	Modify the nice value for the child subprocess.
void	setTimeout (int time_s)
	Set a timeout on the allowed runtime for the subprocess.
bool	run (void)
	Run the command.
bool	writeStdin (const char *buf, int cnt)
	Write data to stdin on the subprocess.
bool	writeStdin (const std::string &str)
	Write data to stdin on the subprocess.
bool	kill (int sig=SIGTERM)
	Send a UNIX signal to the subprocess.
bool	closeStdin (void)
	Close the stdin pipe to the subprocess.
bool	ifExited (void) const
	Check if the subprocess exited in a normal way.
bool	ifSignaled (void) const
	Check if the subprocess exited due to receiving a UNIX signal.
int	exitStatus (void) const
	Read the exit code of the subprocess.
int	termSig (void) const
	Read the UNIX signal number that caused the subprocess to stop.

Public Attributes
sigc::signal< void, const char *, int >	stdoutData
	A signal that is emitted when the subprocess write to stdout.
sigc::signal< void, const char *, int >	stderrData
	A signal that is emitted when the subprocess write to stderr.
sigc::signal< void >	stdoutClosed
	A signal that is emitted when the subprocess close its stdout.
sigc::signal< void >	stderrClosed
	A signal that is emitted when the subprocess close its stderr.
sigc::signal< void >	exited
	A signal that is emitted when the subprocess exits.

Detailed Description

Execute external commands.

Author

Tobias Blomberg / SM0SVX

Date

2013-10-26

This class is used to execute external commands. It essentially wraps the exec system call together with commonly used infrastructure in a convenient class.

This class depends on the SIGCHLD UNIX signal so it must not be used by another part of the application.

#include <iostream>
#include <AsyncCppApplication.h>
#include <AsyncExec.h>
#include <AsyncTimer.h>
 
using namespace std;
using namespace Async;
 
void handleOutput(const char *buf, int cnt)
{
  cout << buf;
}
 
void handleExit(Exec *exec)
{
  cout << "Exited(\"" << exec->command() << "\"): ";
  if (exec->ifExited())
  {
    cout << "exit_status=" << exec->exitStatus();
  }
  else if (exec->ifSignaled())
  {
    cout << "term_sig=" << exec->termSig();
  }
  cout << endl;
}
 
int main()
{
  CppApplication app;
 
    // Start a "cat" process and then run some text through it. Use the -n
    // option to make cat number the lines
  Exec cat("/bin/cat -n");
  cat.stdoutData.connect(sigc::ptr_fun(handleOutput));
  cat.stderrData.connect(sigc::ptr_fun(handleOutput));
  cat.exited.connect(sigc::bind(sigc::ptr_fun(handleExit), &cat));
  cat.nice();
  cat.run();
  cat.writeStdin("Hello, Exec!\n");
  cat.writeStdin("This is a test\n");
  cat.closeStdin();
 
    // Try to run a command that does not exist
  Exec xyz("/bin/xyz");
  xyz.exited.connect(sigc::bind(sigc::ptr_fun(handleExit), &xyz));
  xyz.run();
 
    // Start a sort that just blocks and then set a timeout which kills it
  Exec kill("/bin/sort");
  kill.exited.connect(sigc::bind(sigc::ptr_fun(handleExit), &kill));
  kill.setTimeout(1);
  kill.run();
 
    // Sleep for two seconds then quit application
  Exec sleep("/bin/sleep 2");
  sleep.exited.connect(sigc::bind(sigc::ptr_fun(handleExit), &sleep));
  sleep.exited.connect(mem_fun(app, &CppApplication::quit));
  sleep.run();
 
  app.exec();
 
  return 0;
}
 

Examples

AsyncExec_demo.cpp.

Definition at line 131 of file AsyncExec.h.

Member Typedef Documentation

Environment

using Async::Exec::Environment = std::vector<std::pair<std::string,std::string>>

Definition at line 134 of file AsyncExec.h.

Constructor & Destructor Documentation

Exec()

Async::Exec::Exec ( const std::string & cmdline = "" )

explicit

Default constructor.

~Exec()

Async::Exec::~Exec

(

void

)

Destructor.

Member Function Documentation

addEnvironmentVar()

void Async::Exec::addEnvironmentVar	(	const std::string &	name,
		const std::string &	val )

Add an additional environment variable.

Parameters

name	The name of the environment variable
val	The value of the environment variable

This function is used to add a variable to the environment for the process to be executed. It must be done before calling run().

addEnvironmentVars()

void Async::Exec::addEnvironmentVars

(

const Environment &

env

)

Add multiple environment variables.

Parameters

env	The environment variables to add

This function is used to add multiple variables to the environment for the process to be executed. It must be done before calling run().

appendArgument()

void Async::Exec::appendArgument

(

const std::string &

arg

)

Append a command line argument to a command.

Parameters

arg	The command line argument to add

clearEnvironment()

void Async::Exec::clearEnvironment

(

void

)

Clear the environment.

This function is used to clear the environment. It must be called before calling run(). It will clear both the environment inherited from the parent process as well as any environment variables added using the addEnvironmentVar(s) functions.

closeStdin()

bool Async::Exec::closeStdin

(

void

)

Close the stdin pipe to the subprocess.

Returns

Returns true on success or false otherwise

This method is used to close the pipe from the parent process to the subprocess. This will indicate to the subprocess that the parent process is done sending data to it.

command()

const std::string & Async::Exec::command ( void ) const

inline

Get the command name for the command.

Returns

Returns the command name

Examples

AsyncExec_demo.cpp.

Definition at line 161 of file AsyncExec.h.

exitStatus()

int Async::Exec::exitStatus

(

void

)

const

Read the exit code of the subprocess.

Returns

Returns the exit code (0-255) of the subprocess

This function may only be called after the process has exited. This is indicated by the "exited" signal. The returned value is only meaningful if the ifExited function returns true.

Examples

AsyncExec_demo.cpp.

ifExited()

bool Async::Exec::ifExited

(

void

)

const

Check if the subprocess exited in a normal way.

Returns

Returns true if it was a normal exit or false otherwise

This function may only be called after the process has exited. This is indicated by the "exited" signal.

Examples

AsyncExec_demo.cpp.

ifSignaled()

bool Async::Exec::ifSignaled

(

void

)

const

Check if the subprocess exited due to receiving a UNIX signal.

Returns

Returns true if it was a signal exit or false otherwise

This function may only be called after the process has exited. This is indicated by the "exited" signal.

Examples

AsyncExec_demo.cpp.

kill()

bool Async::Exec::kill

(

int

sig = SIGTERM

)

Send a UNIX signal to the subprocess.

Parameters

sig	The UNIX signal to send

Returns

Returns true on success or false otherwise

nice()

bool Async::Exec::nice

(

int

inc = 10

)

Modify the nice value for the child subprocess.

Parameters

inc	How much to increase the nice value

Returns

Returns true on success or else false

This function will modify the nice value of the subprocess. A positive value will increase the nice value (lower priority) and a negative value will decrease the nice value (higher priority). This function may be called both before and after the run method.

run()

bool Async::Exec::run

(

void

)

Run the command.

Returns

Returns true on success or false otherwise

This method is used to run the command specified using the constructor, setCommandLine and appendArgument. This function will return success as long as the fork call succeeds. If the command cannot be run for some reason, this function will still return success. Errors that occurr after the fork call will be handled through the "exited" signal. If the command cannot run for some reason, the exit code will be 255.

setCommandLine()

void Async::Exec::setCommandLine

(

const std::string &

cmdline

)

Set the command line to use.

Parameters

cmdline

The command line to run

This function can be used to set the command line before the run method is called. The command line can also be set directly in the constructor. It's possible to append more arguments to the command line using the appendArgument method.

setTimeout()

void Async::Exec::setTimeout

(

int

time_s

)

Set a timeout on the allowed runtime for the subprocess.

Parameters

time_s

The timeout time in seconds

Use this method to limit the maximum runtime for the subprocess. If the process runs for longer than the specified time, a SIGTERM will be sent to it. If the subprocess has not exited withing ten seconds, a SIGKILL will be sent to the subprocess.

termSig()

int Async::Exec::termSig

(

void

)

const

Read the UNIX signal number that caused the subprocess to stop.

Returns

Returns the UNIX signal number

This function may only be called after the process has exited. This is indicated by the "exited" signal. The returned value is only meaningful if the ifSignaled function returns true.

Examples

AsyncExec_demo.cpp.

writeStdin() [1/2]

bool Async::Exec::writeStdin	(	const char *	buf,
		int	cnt )

Write data to stdin on the subprocess.

Parameters

buf	The buffer to write data from
cnt	The number of bytes to write

Returns

Returns true on success or false otherwise

writeStdin() [2/2]

bool Async::Exec::writeStdin

(

const std::string &

str

)

Write data to stdin on the subprocess.

Parameters

str	The string buffer to write

Returns

Returns true on success or false otherwise

Member Data Documentation

exited

sigc::signal<void> Async::Exec::exited

A signal that is emitted when the subprocess exits.

This signal will be emitted when the subprocess exits. After that the methods ifExited, ifSignaled, exitStatus and termSig may be used to find out what caused the subprocess to exit.

Definition at line 343 of file AsyncExec.h.

stderrClosed

sigc::signal<void> Async::Exec::stderrClosed

A signal that is emitted when the subprocess close its stderr.

Definition at line 334 of file AsyncExec.h.

stderrData

sigc::signal<void, const char *, int> Async::Exec::stderrData

A signal that is emitted when the subprocess write to stderr.

Parameters

buf	The buffer containing the data
cnt	The number of valid bytes in the buffer

This signal is emitted when a subprocess write to its stderr. The data will be zero terminated.

Definition at line 324 of file AsyncExec.h.

stdoutClosed

sigc::signal<void> Async::Exec::stdoutClosed

A signal that is emitted when the subprocess close its stdout.

Definition at line 329 of file AsyncExec.h.

stdoutData

sigc::signal<void, const char *, int> Async::Exec::stdoutData

A signal that is emitted when the subprocess write to stdout.

Parameters

buf	The buffer containing the data
cnt	The number of valid bytes in the buffer

This signal is emitted when a subprocess write to its stdout. The data will be zero terminated.

Definition at line 314 of file AsyncExec.h.

---

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

• AsyncExec.h