#include <pstream.h>
Public Types | |
typedef CharT | char_type |
typedef Traits | traits_type |
typedef traits_type::int_type | int_type |
typedef traits_type::off_type | off_type |
typedef traits_type::pos_type | pos_type |
typedef fd_type | fd_t |
typedef std::ios_base::openmode | pmode |
Type used to specify how to connect to the process. | |
typedef std::vector< std::string > | argv_type |
Type used to hold the arguments for a command. | |
typedef int | fd_type |
Type used for file descriptors. | |
Public Member Functions | |
basic_pstreambuf () | |
Default constructor. | |
basic_pstreambuf (const std::string &command, pmode mode) | |
Constructor that initialises the buffer with command. | |
basic_pstreambuf (const std::string &file, const argv_type &argv, pmode mode) | |
Constructor that initialises the buffer with file and argv. | |
~basic_pstreambuf () | |
Destructor. | |
basic_pstreambuf * | open (const std::string &command, pmode mode) |
Initialise the stream buffer with command. | |
basic_pstreambuf * | open (const std::string &file, const argv_type &argv, pmode mode) |
Initialise the stream buffer with file and argv. | |
basic_pstreambuf * | close () |
Close the stream buffer and wait for the process to exit. | |
basic_pstreambuf * | kill (int signal=SIGTERM) |
Send a signal to the process. | |
void | peof () |
Close the pipe connected to the process' stdin. | |
bool | read_err (bool readerr=true) |
Change active input source. | |
bool | is_open () const |
Report whether the stream buffer has been initialised. | |
bool | exited () |
Report whether the process has exited. | |
int | status () const |
Return the exit status of the process. | |
int | error () const |
Return the error number (errno) for the most recent failed operation. | |
Static Public Attributes | |
static const pmode | pstdin = std::ios_base::out |
Write to stdin. | |
static const pmode | pstdout = std::ios_base::in |
Read from stdout. | |
static const pmode | pstderr = std::ios_base::app |
Read from stderr. | |
Protected Types | |
enum | buf_read_src { rsrc_out = 0, rsrc_err = 1 } |
Enumerated type to indicate whether stdout or stderr is to be read. | |
Protected Member Functions | |
int_type | overflow (int_type c) |
Transfer characters to the pipe when character buffer overflows. | |
int_type | underflow () |
Transfer characters from the pipe when the character buffer is empty. | |
int_type | pbackfail (int_type c=traits_type::eof()) |
Make a character available to be returned by the next extraction. | |
int | sync () |
Write any buffered characters to the stream. | |
std::streamsize | xsputn (const char_type *s, std::streamsize n) |
Insert multiple characters into the pipe. | |
std::streamsize | write (const char_type *s, std::streamsize n) |
Insert a sequence of characters into the pipe. | |
std::streamsize | read (char_type *s, std::streamsize n) |
Extract a sequence of characters from the pipe. | |
std::streamsize | showmanyc () |
Report how many characters can be read from active input without blocking. | |
pid_t | fork (pmode mode) |
Initialise pipes and fork process. | |
int | wait (bool nohang=false) |
Wait for the child process to exit. | |
fd_type & | wpipe () |
Return the file descriptor for the output pipe. | |
fd_type & | rpipe () |
Return the file descriptor for the active input pipe. | |
fd_type & | rpipe (buf_read_src which) |
Return the file descriptor for the specified input pipe. | |
void | create_buffers (pmode mode) |
void | destroy_buffers (pmode mode) |
bool | empty_buffer () |
Writes buffered characters to the process' stdin pipe. | |
bool | fill_buffer (bool non_blocking=false) |
char_type * | rbuffer () |
Return the active input buffer. | |
buf_read_src | switch_read_buffer (buf_read_src) |
Related Functions | |
(Note that these are not member functions.) | |
void | close_fd (pstreams::fd_type &fd) |
Helper function to close a file descriptor. | |
template<int N> | |
void | close_fd_array (pstreams::fd_type(&fds)[N]) |
Helper function to close an array of file descriptors. |
Provides underlying streambuf functionality for the PStreams classes.
typedef fd_type redi::basic_pstreambuf< CharT, Traits >::fd_t |
redi::basic_pstreambuf< C, T >::basic_pstreambuf | ( | ) | [inline] |
Default constructor.
Creates an uninitialised stream buffer.
redi::basic_pstreambuf< C, T >::basic_pstreambuf | ( | const std::string & | command, | |
pmode | mode | |||
) | [inline] |
Constructor that initialises the buffer with command.
Initialises the stream buffer by calling open() with the supplied arguments.
command | a string containing a shell command. | |
mode | the I/O mode to use when opening the pipe. |
References redi::basic_pstreambuf< CharT, Traits >::open().
redi::basic_pstreambuf< C, T >::basic_pstreambuf | ( | const std::string & | file, | |
const argv_type & | argv, | |||
pmode | mode | |||
) | [inline] |
Constructor that initialises the buffer with file and argv.
Initialises the stream buffer by calling open() with the supplied arguments.
file | a string containing the name of a program to execute. | |
argv | a vector of argument strings passsed to the new program. | |
mode | the I/O mode to use when opening the pipe. |
References redi::basic_pstreambuf< CharT, Traits >::open().
redi::basic_pstreambuf< C, T >::~basic_pstreambuf | ( | ) | [inline] |
Destructor.
Closes the stream by calling close().
References redi::basic_pstreambuf< CharT, Traits >::close().
basic_pstreambuf< C, T > * redi::basic_pstreambuf< C, T >::close | ( | ) | [inline] |
Close the stream buffer and wait for the process to exit.
Closes all pipes and calls wait() to wait for the process to finish. If an error occurs the error code will be set to one of the possible errors for waitpid()
. See your system's documentation for these errors.
this
on successful close or NULL
if there is no process to close or if an error occurs. References redi::basic_pstreambuf< CharT, Traits >::close_fd(), redi::basic_pstreambuf< CharT, Traits >::close_fd_array(), redi::basic_pstreambuf< CharT, Traits >::error(), redi::basic_pstreambuf< CharT, Traits >::is_open(), redi::pstreams::pstderr, redi::pstreams::pstdin, redi::pstreams::pstdout, redi::basic_pstreambuf< CharT, Traits >::sync(), and redi::basic_pstreambuf< CharT, Traits >::wait().
Referenced by redi::pstream_common< CharT, Traits >::close(), redi::basic_pstreambuf< CharT, Traits >::fork(), redi::basic_pstreambuf< CharT, Traits >::open(), and redi::basic_pstreambuf< CharT, Traits >::~basic_pstreambuf().
bool redi::basic_pstreambuf< C, T >::empty_buffer | ( | ) | [inline, protected] |
Writes buffered characters to the process' stdin pipe.
References redi::basic_pstreambuf< CharT, Traits >::write().
Referenced by redi::basic_pstreambuf< CharT, Traits >::overflow(), and redi::basic_pstreambuf< CharT, Traits >::sync().
int redi::basic_pstreambuf< C, T >::error | ( | ) | const [inline] |
Return the error number (errno) for the most recent failed operation.
Referenced by redi::basic_pstreambuf< CharT, Traits >::close().
bool redi::basic_pstreambuf< C, T >::exited | ( | ) | [inline] |
Report whether the process has exited.
This function can call pstreambuf::wait() and so may change the object's state if the child process has already exited.
References redi::basic_pstreambuf< CharT, Traits >::wait().
Referenced by redi::basic_pstreambuf< CharT, Traits >::kill(), redi::basic_pstreambuf< CharT, Traits >::sync(), and redi::basic_pstreambuf< CharT, Traits >::wait().
bool redi::basic_pstreambuf< C, T >::fill_buffer | ( | bool | non_blocking = false |
) | [inline, protected] |
References redi::basic_pstreambuf< CharT, Traits >::rbuffer(), redi::basic_pstreambuf< CharT, Traits >::read(), and redi::basic_pstreambuf< CharT, Traits >::rpipe().
Referenced by redi::basic_pstreambuf< CharT, Traits >::showmanyc(), and redi::basic_pstreambuf< CharT, Traits >::underflow().
pid_t redi::basic_pstreambuf< C, T >::fork | ( | pmode | mode | ) | [inline, protected] |
Initialise pipes and fork process.
Creates pipes as specified by mode and calls fork()
to create a new process. If the fork is successful the parent process stores the child's PID and the opened pipes and the child process replaces its standard streams with the opened pipes.
If an error occurs the error code will be set to one of the possible errors for pipe()
or fork()
. See your system's documentation for these error codes.
mode | an OR of pmodes specifying which of the child's standard streams to connect to. |
References redi::basic_pstreambuf< CharT, Traits >::close(), redi::basic_pstreambuf< CharT, Traits >::close_fd_array(), redi::pstreams::pstderr, redi::pstreams::pstdin, redi::pstreams::pstdout, and redi::basic_pstreambuf< CharT, Traits >::read_err().
Referenced by redi::basic_pstreambuf< CharT, Traits >::open().
bool redi::basic_pstreambuf< C, T >::is_open | ( | ) | const [inline] |
Report whether the stream buffer has been initialised.
Unlike pstreambuf::exited(), this function will not call wait() and so will not change the object's state. This means that once a child process is executed successfully this function will continue to return true even after the process exits (until wait() is called.)
Referenced by redi::basic_pstreambuf< CharT, Traits >::close(), redi::pstream_common< CharT, Traits >::is_open(), redi::basic_pstreambuf< CharT, Traits >::kill(), redi::basic_pstreambuf< CharT, Traits >::open(), and redi::basic_pstreambuf< CharT, Traits >::wait().
basic_pstreambuf< C, T > * redi::basic_pstreambuf< C, T >::kill | ( | int | signal = SIGTERM |
) | [inline] |
Send a signal to the process.
Sends the specified signal to the process. A signal can be used to terminate a child process that would not exit otherwise.
If an error occurs the error code will be set to one of the possible errors for kill()
. See your system's documentation for these errors.
signal | A signal to send to the child process. |
this
or NULL
if kill()
fails. References redi::basic_pstreambuf< CharT, Traits >::exited(), and redi::basic_pstreambuf< CharT, Traits >::is_open().
basic_pstreambuf< C, T > * redi::basic_pstreambuf< C, T >::open | ( | const std::string & | file, | |
const argv_type & | argv, | |||
pmode | mode | |||
) | [inline] |
Initialise the stream buffer with file and argv.
Starts a new process by executing file with the arguments in argv and opens pipes to the process with the specified mode.
By convention argv
[0] should be the file name of the file being executed.
Will duplicate the actions of the shell in searching for an executable file if the specified file name does not contain a slash (/) character.
Iff file is successfully executed then is_open() will return true. Otherwise, pstreambuf::error() can be used to obtain the value of errno
that was set by execvp(3) in the child process.
The exit status of the new process will be returned by pstreambuf::status() after pstreambuf::exited() returns true.
file | a string containing the pathname of a program to execute. | |
argv | a vector of argument strings passed to the new program. | |
mode | a bitwise OR of one or more of out , in and err . |
this
otherwise. References redi::basic_pstreambuf< CharT, Traits >::close(), redi::basic_pstreambuf< CharT, Traits >::close_fd_array(), redi::basic_pstreambuf< CharT, Traits >::fork(), redi::basic_pstreambuf< CharT, Traits >::is_open(), redi::basic_pstreambuf< CharT, Traits >::read(), redi::basic_pstreambuf< CharT, Traits >::wait(), and redi::basic_pstreambuf< CharT, Traits >::write().
basic_pstreambuf< C, T > * redi::basic_pstreambuf< C, T >::open | ( | const std::string & | command, | |
pmode | mode | |||
) | [inline] |
Initialise the stream buffer with command.
Starts a new process by passing command to the shell (/bin/sh) and opens pipes to the process with the specified mode.
Will duplicate the actions of the shell in searching for an executable file if the specified file name does not contain a slash (/) character.
command | a string containing a shell command. | |
mode | a bitwise OR of one or more of out , in , err . |
this
otherwise. References redi::basic_pstreambuf< CharT, Traits >::fork(), and redi::basic_pstreambuf< CharT, Traits >::is_open().
Referenced by redi::basic_pstreambuf< CharT, Traits >::basic_pstreambuf(), and redi::pstream_common< CharT, Traits >::do_open().
basic_pstreambuf< C, T >::int_type redi::basic_pstreambuf< C, T >::overflow | ( | int_type | c | ) | [inline, protected] |
Transfer characters to the pipe when character buffer overflows.
Called when the internal character buffer is not present or is full, to transfer the buffer contents to the pipe.
c | a character to be written to the pipe. |
traits_type::not_eof(c)
if c is equal to traits_type::eof()
. Otherwise returns c if c can be written to the pipe, or traits_type::eof()
if not. References redi::basic_pstreambuf< CharT, Traits >::empty_buffer().
basic_pstreambuf< C, T >::int_type redi::basic_pstreambuf< C, T >::pbackfail | ( | int_type | c = traits_type::eof() |
) | [inline, protected] |
Make a character available to be returned by the next extraction.
Attempts to make c available as the next character to be read by sgetc()
.
c | a character to make available for extraction. |
traits_type::eof()
otherwise. void redi::basic_pstreambuf< C, T >::peof | ( | ) | [inline] |
Close the pipe connected to the process' stdin.
Closes the output pipe, causing the child process to receive the end-of-file indicator on subsequent reads from its stdin
stream.
References redi::basic_pstreambuf< CharT, Traits >::close_fd(), and redi::basic_pstreambuf< CharT, Traits >::sync().
basic_pstreambuf< C, T >::char_type * redi::basic_pstreambuf< C, T >::rbuffer | ( | ) | [inline, protected] |
Return the active input buffer.
Referenced by redi::basic_pstreambuf< CharT, Traits >::fill_buffer().
std::streamsize redi::basic_pstreambuf< C, T >::read | ( | char_type * | s, | |
std::streamsize | n | |||
) | [inline, protected] |
Extract a sequence of characters from the pipe.
Reads up to n characters from the pipe to the buffer s.
s | character buffer. | |
n | buffer length. |
References redi::basic_pstreambuf< CharT, Traits >::rpipe().
Referenced by redi::basic_pstreambuf< CharT, Traits >::fill_buffer(), and redi::basic_pstreambuf< CharT, Traits >::open().
bool redi::basic_pstreambuf< C, T >::read_err | ( | bool | readerr = true |
) | [inline] |
Change active input source.
Toggle the stream used for reading. If readerr is true
then the process' stderr
output will be used for subsequent extractions, if readerr is false the the process' stdout will be used.
readerr | true to read stderr , false to read stdout . |
true
if the requested stream is open and will be used for subsequent extractions, false
otherwise. Referenced by redi::basic_rpstream< CharT, Traits >::err(), redi::basic_pstream< CharT, Traits >::err(), redi::basic_ipstream< CharT, Traits >::err(), redi::basic_pstreambuf< CharT, Traits >::fork(), redi::basic_rpstream< CharT, Traits >::out(), redi::basic_pstream< CharT, Traits >::out(), and redi::basic_ipstream< CharT, Traits >::out().
basic_pstreambuf< C, T >::fd_type & redi::basic_pstreambuf< C, T >::rpipe | ( | buf_read_src | which | ) | [inline, protected] |
Return the file descriptor for the specified input pipe.
basic_pstreambuf< C, T >::fd_type & redi::basic_pstreambuf< C, T >::rpipe | ( | ) | [inline, protected] |
Return the file descriptor for the active input pipe.
Referenced by redi::basic_pstreambuf< CharT, Traits >::fill_buffer(), redi::basic_pstreambuf< CharT, Traits >::read(), and redi::basic_pstreambuf< CharT, Traits >::showmanyc().
int redi::basic_pstreambuf< C, T >::status | ( | ) | const [inline] |
Return the exit status of the process.
Referenced by redi::basic_pstreambuf< CharT, Traits >::wait().
basic_pstreambuf< C, T >::int_type redi::basic_pstreambuf< C, T >::underflow | ( | ) | [inline, protected] |
Transfer characters from the pipe when the character buffer is empty.
Called when the internal character buffer is is empty, to re-fill it from the pipe.
traits_type::eof()
in case of failure. References redi::basic_pstreambuf< CharT, Traits >::fill_buffer().
int redi::basic_pstreambuf< C, T >::wait | ( | bool | nohang = false |
) | [inline, protected] |
Wait for the child process to exit.
Suspends execution and waits for the associated process to exit, or until a signal is delivered whose action is to terminate the current process or to call a signal handling function. If the process has already exited (i.e. it is a "zombie" process) then wait() returns immediately. Waiting for the child process causes all its system resources to be freed.
error() will return EINTR if wait() is interrupted by a signal.
nohang | true to return immediately if the process has not exited. |
References redi::basic_pstreambuf< CharT, Traits >::close_fd(), redi::basic_pstreambuf< CharT, Traits >::exited(), redi::basic_pstreambuf< CharT, Traits >::is_open(), and redi::basic_pstreambuf< CharT, Traits >::status().
Referenced by redi::basic_pstreambuf< CharT, Traits >::close(), redi::basic_pstreambuf< CharT, Traits >::exited(), and redi::basic_pstreambuf< CharT, Traits >::open().
basic_pstreambuf< C, T >::fd_type & redi::basic_pstreambuf< C, T >::wpipe | ( | ) | [inline, protected] |
Return the file descriptor for the output pipe.
Referenced by redi::basic_pstreambuf< CharT, Traits >::write().
std::streamsize redi::basic_pstreambuf< C, T >::write | ( | const char_type * | s, | |
std::streamsize | n | |||
) | [inline, protected] |
Insert a sequence of characters into the pipe.
Writes up to n characters to the pipe from the buffer s.
s | character buffer. | |
n | buffer length. |
References redi::basic_pstreambuf< CharT, Traits >::wpipe().
Referenced by redi::basic_pstreambuf< CharT, Traits >::empty_buffer(), and redi::basic_pstreambuf< CharT, Traits >::open().
std::streamsize redi::basic_pstreambuf< C, T >::xsputn | ( | const char_type * | s, | |
std::streamsize | n | |||
) | [inline, protected] |
Insert multiple characters into the pipe.
s | character buffer. | |
n | buffer length. |
void close_fd | ( | pstreams::fd_type & | fd | ) | [related] |
Helper function to close a file descriptor.
Inspects fd and calls close(3) if it has a non-negative value.
fd | a file descriptor. |
Referenced by redi::basic_pstreambuf< CharT, Traits >::close(), redi::basic_pstreambuf< CharT, Traits >::peof(), and redi::basic_pstreambuf< CharT, Traits >::wait().
void close_fd_array | ( | pstreams::fd_type(&) | fds[N] | ) | [related] |
Helper function to close an array of file descriptors.
Calls close_fd()
on each member of the array. The length of the array is determined automatically by template argument deduction to avoid errors.
fds | an array of file descriptors. |
Referenced by redi::basic_pstreambuf< CharT, Traits >::close(), redi::basic_pstreambuf< CharT, Traits >::fork(), and redi::basic_pstreambuf< CharT, Traits >::open().