Libexecstream provides one class, exec_stream_t, which has the following members:
class error_t : public std::exception
Exceptions thrown from exec_stream_t members are derived from error_t. error_t is derived from std::exception and has no additional public members besides constructors. Exceptions may be thrown from any exec_stream_t member function except destructor and accessors: in(), out() and err(). Writing to in() and reading out() and err() will also throw exceptions when errors occur.
exec_stream_t()
Constructs exec_stream_t in the default state. You may change timeouts, buffer limits and text or binary modes of the streams before starting child process (see set_buffer_limit, set_binary_mode, set_text_mode, set_wait_timeout). In the default state, amount of data buffered for writing to child's stdin, and amount of data read in advance from child's stdout and stderr is unlimited. On windows, all streams are in the text mode.
exec_stream_t( std::string const & program, std::string const & arguments )
Constructs exec_stream_t in the default state, then starts program with arguments. Arguments containing space should be included in double quotation marks, and double quote in such arguments should be escaped with backslash.
template< class iterator > exec_stream_t( std::string const & program, iterator args_begin, iterator args_end )
Constructs exec_stream_t in the default state, then starts program with arguments specified by the range args_begin, args_end. args_begin should be an input iterator that when dereferenced gives value assignable to std::string. Spaces and double quotes in arguments need not to be escaped.
~exec_stream_t()
Writes (with timeout) all pending data to child stdin, closes streams and waits (with timeout) for child process to stop.
std::ostream & in()
Returns output stream for writing to child's stdin.
std::istream & out()
Returns input stream for reading child's stdout.
std::istream & err()
Returns input stream for reading child's stderr.
bool close_in()
Closes child's standard input after writing (with timeout) all pending data to it.
void start( std::string const & program, std::string const & arguments )
Starts program with arguments. Arguments are space-separated. Arguments containing space should be included in double quotation marks, and double quote in such arguments should be escaped with backslash.
template< class iterator > void start( std::string const & program, iterator args_begin, iterator args_end )
Starts program with arguments specified by the range args_begin, args_end. args_begin should be an input iterator that when dereferenced gives value assignable to std::string. Spaces and double quotes in arguments need not to be escaped.
enum stream_kind_t { s_in=1, s_out=2, s_err=4, s_all=s_in|s_out|s_err, s_child=8 }
Used for the first argument to set_buffer_limit, set_wait_timeout, set_binary_mode, set_text_mode for selecting stream to operate upon.
void set_buffer_limit( int stream_kind, std::size_t size )
For out() and err() streams (when exec_stream_t::s_out or exec_stream_t::s_err is set in the stream_kind), sets maximum amount of data to read from child process before it will be consumed by reading from out() or err().
For in() stream (when exec_stream_t::s_in is set in the stream_kind) sets maximum amount of data to store as result of writing to in() before it will be consumed by child process.
Setting limit for both input and output streams may cause deadlock in situations when both your program and child process are writing data to each other without reading it. Such deadlock will cause the timeout to expire while writing to in().
When size argument to set_buffer_limit is 0, buffers are considered unlimited, and will grow unlimited if one side produce data that the other side does not consume. This is the default state after exec_stream_t creation.
set_buffer_limit will throw exception when called while child process is running.
typedef unsigned long timeout_t
Type of second argument to set_wait_timeout - timeout in milliseconds.
void set_wait_timeout( int stream_kind, timeout_t milliseconds )
For out() and err() streams (when exec_stream_t::s_out or exec_stream_t::s_err is set in the stream_kind), sets maximum amount of time to wait for a child process to produce data when reading out() and err() respectively.
For in() stream (when exec_stream_t::s_in is set in the stream_kind), sets maximum amount of time to wait for a child process to consume data that were written to in(). Note that when buffer limit for in() is not set, writing to in() always writes to buffer and does not wait for child at all.
If that amount of time is exceeded while reading in() or writing to out() and err(), exception is thrown.
When exec_stream_t::s_child is set in the stream kind, set_wait_timeout sets the maximum amount of time to wait for a child process to terminate when close is called. If that amount of time is exceeded, close() will return false.
set_wait_timeout will throw exception when called while child process is running.
void set_text_mode( int stream_kind )
sets stream specified by stream_kind to text mode. In text mode, in the data written to child's stdin, \n are replaced by \r\n; and in the data read from child's stdout and stderr, \r\n are replaced by \n. Text mode is the default on Windows. set_text_mode has no effect on Linux.
set_text_mode will throw exception when called while child process is running.
void set_binary_mode( int stream_kind )
sets stream specified by stream_kind to binary mode. All data written or read from streams are passed unchanged. set_binary_mode has no effect on Linux.
set_binary_mode will throw exception when called while child process is running.
bool close()
Writes (with timeout) all pending data to child stdin, closes streams and waits (with timeout) for child process to stop. If timeout expires while waiting for child to stop, returns false. Otherwise, returns true.
void kill()
Terminates child process, without giving it a chance of proper shutdown.
int exit_code()
Returns exit code from child process. Exit code usually is available only after close. Exception is thrown if chid process has not yet terminated. Exit code has indeterminable value after kill.