CaptureStream Class Reference

Class to capture anything written to stream into a string. More...

#include <IOIntercept.h>

Inheritance diagram for CaptureStream:

Public Member Functions
	CaptureStream (std::ostream &stream, FILE *fileObject)
	Create a StreamInterceptor which writes into a pipe.
	~CaptureStream ()
	Close file descriptors.
const std::string &	getOutput () const
	Get the output, only set after finish()
bool	start ()
	Start intercepting the output.
bool	finish ()
	Restore the stream and get the output from the pipe.

Protected Member Functions
void	setReplacementFD (int fd)
	set the replacement file descriptor, should be called in the constructor of derived classes
bool	replaceFD (int fileDescriptor)
	Replace the file descriptor of m_fileObject with the one passed.

Static Protected Member Functions
static void	readFD (int fd, std::string &out)
	Read the contents of a file descriptor until there is no more input and place them in out.

Protected Attributes
std::ostream &	m_stream
	C++ stream object, only needed to flush before replacement.
FILE *	m_fileObject
	File object of the file we want to replace, needed to obtain file descriptor and to flush.
int	m_savedFD { -1}
	Saved file descriptor: a duplicate of the file descriptor of m_fileObject.
int	m_replacementFD { -1}
	Replacement file descriptor to be used while capturing.
bool	m_capturing {false}
	Check whether we are already capturing.

Private Attributes
int	m_pipeReadFD { -1}
	file descriptor of the read end of the pipe
std::string	m_outputStr
	string with the output, only filled after finish()

Friends
class	CaptureStreamAbortHandler
	allow handling of SIGABRT

Detailed Description

Class to capture anything written to stream into a string.

Underlying this uses a pipe to buffer the output.

Warning

the default capacity for capturing output is 64 kB but might be smaller on certain systems. If there is more output than this while capturing it the captured output will be truncated and processes who check if output was successful might fail.

Definition at line 103 of file IOIntercept.h.

Constructor & Destructor Documentation

CaptureStream()

CaptureStream	(	std::ostream &	stream,
		FILE *	fileObject
	)

Create a StreamInterceptor which writes into a pipe.

Definition at line 156 of file IOIntercept.cc.

                                                                  : StreamInterceptor(stream, fileObject)
  {
    int pipeFD[2] {0};
    if (pipe2(pipeFD, O_NONBLOCK) < 0) {
      B2ERROR("Error creating pipe: " << std::strerror(errno));
      return;
    }
    m_pipeReadFD = pipeFD[0];
    setReplacementFD(pipeFD[1]);
  }

~CaptureStream()

~CaptureStream

(

)

Close file descriptors.

Definition at line 167 of file IOIntercept.cc.

  {
    // the base destructor is called after this one so we need to make sure
    // everything is finished before we close the pipe.
    finish();
    // no need to close the write part, done by base class
    if (m_pipeReadFD >= 0) close(m_pipeReadFD);
  }

Member Function Documentation

finish()

bool finish

(

)

Restore the stream and get the output from the pipe.

Definition at line 185 of file IOIntercept.cc.

  {
    if (StreamInterceptor::finish()) {
      CaptureStreamAbortHandler::getInstance().removeObject(this);
      readFD(m_pipeReadFD, m_outputStr);
      return true;
    }
    return false;
  }

getOutput()

const std::string & getOutput ( ) const

inline

Get the output, only set after finish()

Definition at line 110 of file IOIntercept.h.

{ return m_outputStr; }

readFD()

void readFD ( int  fd, std::string &  out  )

staticprotectedinherited

Read the contents of a file descriptor until there is no more input and place them in out.

Parameters

fd	file descriptor to read, should be opened in non blocking mode O_NOBLOCK
out	string to be replaced with all the bytes read from fd

Definition at line 102 of file IOIntercept.cc.

  {
    out.clear();
    if (fd <= 0) return;
    // need a buffer to read
    static std::unique_ptr<char[]> buffer(new char[1024]);
    // so then, read everything
    while (true) {
      ssize_t size = read(fd, buffer.get(), 1024);
      if (size <= 0) {
        // in case we get interrupted by signal, try again
        if (size < 0 && errno == EINTR)  continue;
        break;
      }
      out.append(buffer.get(), static_cast<size_t>(size));
    }
  }

replaceFD()

bool replaceFD ( int  fileDescriptor )

protectedinherited

Replace the file descriptor of m_fileObject with the one passed.

Parameters

fileDescriptor

file descriptor to be set for m_fileObject using dup2()

Definition at line 120 of file IOIntercept.cc.

  {
    // obviously we don't want to replace invalid descriptors
    if (fileDescriptor < 0) return false;
    // flush existing stream
    m_stream << std::flush;
    std::fflush(m_fileObject);
    // and clear the bad bits we might have gotten when pipe capacity is reached
    m_stream.clear();
    // and then replace the file descriptor
    const int currentFD = fileno(m_fileObject);
    if (currentFD < 0) {
      B2ERROR("Error obtaining file descriptor: " << std::strerror(errno));
      return false;
    }
    while (dup2(fileDescriptor, currentFD) < 0) {
      if (errno != EINTR && errno != EBUSY) {
        B2ERROR("Error in dup2(), cannot replace file descriptor: " << std::strerror(errno));
        return false;
      }
      // interrupted or busy, let's try again
    }
    return true;
  }

setReplacementFD()

void setReplacementFD ( int  fd )

inlineprotectedinherited

set the replacement file descriptor, should be called in the constructor of derived classes

Definition at line 54 of file IOIntercept.h.

{ m_replacementFD = fd; }

start()

bool start

(

)

Start intercepting the output.

Definition at line 176 of file IOIntercept.cc.

  {
    if (StreamInterceptor::start()) {
      CaptureStreamAbortHandler::getInstance().addObject(this);
      return true;
    }
    return false;
  }

Friends And Related Function Documentation

CaptureStreamAbortHandler

friend class CaptureStreamAbortHandler

friend

allow handling of SIGABRT

Definition at line 121 of file IOIntercept.h.

Member Data Documentation

m_capturing

bool m_capturing {false}

protectedinherited

Check whether we are already capturing.

Definition at line 73 of file IOIntercept.h.

m_fileObject

FILE* m_fileObject

protectedinherited

File object of the file we want to replace, needed to obtain file descriptor and to flush.

Definition at line 67 of file IOIntercept.h.

m_outputStr

std::string m_outputStr

private

string with the output, only filled after finish()

Definition at line 119 of file IOIntercept.h.

m_pipeReadFD

int m_pipeReadFD { -1}

private

file descriptor of the read end of the pipe

Definition at line 117 of file IOIntercept.h.

m_replacementFD

int m_replacementFD { -1}

protectedinherited

Replacement file descriptor to be used while capturing.

Definition at line 71 of file IOIntercept.h.

m_savedFD

int m_savedFD { -1}

protectedinherited

Saved file descriptor: a duplicate of the file descriptor of m_fileObject.

Definition at line 69 of file IOIntercept.h.

m_stream

std::ostream& m_stream

protectedinherited

C++ stream object, only needed to flush before replacement.

Definition at line 65 of file IOIntercept.h.

---

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

• framework/utilities/include/IOIntercept.h
• framework/utilities/src/IOIntercept.cc