Description

Abstract base class for shells that can execute system commands.

Note: All methods (for one object) must be called from the same thread.

Definition at line 1870 of file base.H.

#include "base.H"

Inheritance diagram for CShell:

Public Member Functions
Execution control...
virtual bool	Start (const char *cmd, bool readStdErr=false)=0
	Start command. More...

virtual bool	StartRestricted (const char name, const char args=NULL)
	Same as 'Start', but fetch the command from the environment. More...

virtual bool	IsRunning ()
	Still running?

virtual void	Wait ()=0
	Wait until current command completes.

virtual void	Kill (int sig=SIGTERM)
	Kill the current command nicely. This may not work for all types of shells. A Wait() invocation is required anyway afterwards.

int	ExitCode ()
	Get the exit code of last command.

Simple running...
int	Run (const char cmd, const char input=NULL, CString *output=NULL)
	Run command 'cmd' synchronously and return its exit code. More...

Accessing stdin & stdout...
virtual void	CheckIO (bool canWrite, bool canRead, TTicks maxTime=-1)=0
	Check whether the i/o channels can take/deliver data. More...

bool	WaitUntilReadable (TTicks maxTime=-1)
	Wait until output of the external command is readable. Be aware of potential deadlocks. This command can only be safely used if the external command does not wait for input. More...

bool	WaitUntilWritable (TTicks maxTime=-1)
	Wait until the external command can accept written input. Be aware of potential deadlocks. This command can only be safely used if the external command does not produce any output. More...

bool	Writable ()
	Poll for writability (non-blocking).

virtual void	WriteLine (const char *line)=0
	Blocking write, execution is guaranteed. To avoid blocking, run Writable() or CheckI() first.

void	WriteLine (CString *str)
	Write a line.

virtual void	WriteClose ()=0
	Close the write channel.

bool	Readable ()
	Poll for readability.

virtual bool	ReadLine (CString *str)=0
	Non-Blocking read, returns 'true' on success. `str` can be NULL, in which case the line is ignored, given the reading was successul.

virtual bool	ReadClosed ()=0
	Close the read channel.

Member Function Documentation

◆ Start()

virtual bool CShell::Start	(	const char *	cmd,
		bool	readStdErr = `false`
	)

pure virtual

Start command.

Parameters

cmd	The exact (and arbitrary) shell command. On Android, relative paths are prepended with HOME2L_ROOT.
readStdErr	decides whether STDERR is redirected to STDIN and also returned via ReadLine() and friends. By default, it is left undirected.

If a previous command is still running, Wait() is executed before. On error, a warning is printed and 'false' is returned. Only one command can be executed at a time. It can be understood that the Start() method includes an implicit Mutex-Lock operation, and the lock has been obtained (only) if 'true' is returned. The corresponding Mutex-Unlock operation is implied by calling Wait().

Implemented in CShellSession, and CShellBare.

◆ StartRestricted()

virtual bool CShell::StartRestricted	(	const char *	name,
		const char *	args = `NULL`
	)

virtual

Same as 'Start', but fetch the command from the environment.

This way, only commands explicitly defined in the environment settings are allowed, which is a security improvment. The actual command is taken from the environment variable rc.cmd.<name>. The command name may contain the placeholder "%s", which is replaced by args. This mode of command definition is meant for remote network execution to avoid security holes.

◆ Run()

int CShell::Run	(	const char *	cmd,
		const char *	input = `NULL`,
		CString *	output = `NULL`
	)

Run command 'cmd' synchronously and return its exit code.

The standard input is taken from 'input' and the output is writen to the string referred to by 'output'. This function is only appropriate for short running commands since the calling thread blocks until the command completes.

◆ CheckIO()

virtual void CShell::CheckIO	(	bool *	canWrite,
		bool *	canRead,
		TTicks	maxTime = `-1`
	)

pure virtual

Check whether the i/o channels can take/deliver data.

Parameters

canWrite	may point to a variable that will be set, depending on whether at least one byte can be written to the external command.
canRead	may point to a variable that will be set, depending on whether at least one byte can be read from the external command.
maxTime	is the maximum waiting time in milliseconds. A value <0 lets it wait forever, a value 0 does not cause any waiting at all.

If any of the two pointers 'canWrite' and 'canRead' is 'NULL', the caller indicates that he is not interested in the respective result. Hence, the method waits until the respective other channel is ready.

In situations, where CheckIO() would wait forever, it returns immediately with both flags set to 'false' (for example: read channel already closed, and canWrite == NULL). Note: As long as both the read and the write channel are open, the caller (usually) must always write and read as much as possible. Otherwise, a deadlock may occur.

Implemented in CShellSession, and CShellBare.

◆ WaitUntilReadable()

bool CShell::WaitUntilReadable ( TTicks maxTime = -1 )

inline

Wait until output of the external command is readable. Be aware of potential deadlocks. This command can only be safely used if the external command does not wait for input.

Returns: 'true', if the output is readable.

Definition at line 1941 of file base.H.

◆ WaitUntilWritable()

bool CShell::WaitUntilWritable ( TTicks maxTime = -1 )

inline

Wait until the external command can accept written input. Be aware of potential deadlocks. This command can only be safely used if the external command does not produce any output.

Returns: 'true', if the output is writeable.

Definition at line 1947 of file base.H.

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

common/base.H