Classes | Public Types | Public Member Functions | Static Public Member Functions | Static Public Attributes | Protected Member Functions | List of all members
Rose::BinaryAnalysis::Debugger Class Reference


Simple debugger.

This class implements a very simple debugger.

Definition at line 26 of file BinaryDebugger.h.

#include <BinaryDebugger.h>

Inheritance diagram for Rose::BinaryAnalysis::Debugger:
Inheritance graph
Collaboration diagram for Rose::BinaryAnalysis::Debugger:
Collaboration graph


class  Specimen
 Describes the specimen to be debugged. More...

Public Types

enum  DetachMode {
 How to detach from a process when the debugger is destroyed. More...
enum  Flag {
  ATTACH = 0x00000001,
  REDIRECT_INPUT = 0x00000002,
  REDIRECT_OUTPUT = 0x00000004,
  REDIRECT_ERROR = 0x00000008,
  CLOSE_FILES = 0x00000010,
  DEFAULT_FLAGS = 0x00000013
 Flags controlling operation. More...
enum  FilterActionFlags {
  REJECT = 0x00000001,
  STOP = 0x00000002
 Action for trace filter callback. More...
typedef Sawyer::SharedPointer< DebuggerPtr
 Shared-ownership pointer to Debugger. More...
typedef BitFlags< FilterActionFlagsFilterAction
 Return value for tracing. More...

Public Member Functions

void attach (const Specimen &, Sawyer::Optional< DetachMode > onDelete=Sawyer::Nothing())
 Attach to a specimen. More...
int isAttached ()
 Returns true if attached to a subordinate. More...
void detach (Sawyer::Optional< DetachMode > mode=Sawyer::Nothing())
 Detach from the subordinate. More...
void terminate ()
 Terminate the subordinate. More...
void executionAddress (rose_addr_t va)
 Set execution address. More...
rose_addr_t executionAddress ()
 Get execution address. More...
void setBreakpoint (const AddressInterval &)
 Set breakpoints. More...
void clearBreakpoint (const AddressInterval &)
 Remove breakpoints. More...
void clearBreakpoints ()
 Remove all breakpoints. More...
void singleStep ()
 Execute one instruction. More...
void runToBreakpoint ()
 Run until the next breakpoint is reached. More...
void runToSyscall ()
 Run until the next system call. More...
Sawyer::Container::Trace< rose_addr_t > trace ()
 Run the program and return an execution trace. More...
template<class Filter >
Sawyer::Container::Trace< rose_addr_t > trace (Filter &filter)
 Run the program and return an execution trace. More...
size_t kernelWordSize ()
 Obtain and cache kernel's word size in bits. More...
Sawyer::Container::BitVector readRegister (RegisterDescriptor)
 Read subordinate register. More...
Sawyer::Container::BitVector readMemory (rose_addr_t va, size_t nBytes, ByteOrder::Endianness order)
 Read subordinate memory as a bit vector. More...
size_t readMemory (rose_addr_t va, size_t nBytes, uint8_t *buffer)
 Read subordinate memory. More...
std::string readCString (rose_addr_t va, size_t maxBytes=UNLIMITED)
 Read C-style NUL-terminated string from subordinate. More...
bool isTerminated ()
 Returns true if the subordinate terminated. More...
std::string howTerminated ()
 String describing how the subordinate process terminated. More...
const RegisterDictionaryregisterDictionary () const
 Available registers. More...
Disassemblerdisassembler () const
 Disassembler. More...
int waitpidStatus () const
 Returns the last status from a call to waitpid. More...
- Public Member Functions inherited from Sawyer::SharedObject
 SharedObject ()
 Default constructor. More...
 SharedObject (const SharedObject &)
 Copy constructor. More...
virtual ~SharedObject ()
 Virtual destructor. More...
SharedObjectoperator= (const SharedObject &)
 Assignment. More...

Static Public Member Functions

static Ptr instance ()
 Create a debugger object that isn't attached to any subordinate process. More...
static Ptr instance (const Specimen &specimen)
 Create a debugger and start debugging a specimen. More...
static void initDiagnostics ()
 Initialize diagnostic output. More...

Static Public Attributes

static Sawyer::Message::Facility mlog
 Diagnostic facility for debugger. More...

Protected Member Functions

 Debugger (const Specimen &specimen)
 Construct a debugger attached to a specimen. More...

Member Typedef Documentation

Shared-ownership pointer to Debugger.

See Shared ownership.

Definition at line 29 of file BinaryDebugger.h.

Return value for tracing.

The return value from the trace filter indicates whether the current address should be appended to the trace or rejected, and whether the tracing operation should continue or stop. A default constructed FilterAction will append the current address to the trace and continue tracing, which is normally what one wants.

Definition at line 350 of file BinaryDebugger.h.

Member Enumeration Documentation

How to detach from a process when the debugger is destroyed.


Kill the process.


Simply detach leaving process in current state.


Detach from process and cause it to continue running.


Do nothing.

Definition at line 32 of file BinaryDebugger.h.

Flags controlling operation.


Attach to existing process.


Redirect input from /dev/null.


Redirect output to /dev/null.


Redirect standard error to /dev/null.


Close all file descriptors > 2.


Default flags.

Definition at line 40 of file BinaryDebugger.h.

Action for trace filter callback.


Reject the current address, not appending it to the trace.


Abort tracing, either appending or rejecting the current address.

Definition at line 340 of file BinaryDebugger.h.

Constructor & Destructor Documentation

Rose::BinaryAnalysis::Debugger::Debugger ( const Specimen specimen)

Construct a debugger attached to a specimen.

Definition at line 253 of file BinaryDebugger.h.

References attach().

Member Function Documentation

static Ptr Rose::BinaryAnalysis::Debugger::instance ( )

Create a debugger object that isn't attached to any subordinate process.

Definition at line 270 of file BinaryDebugger.h.

Referenced by Rose::BinaryAnalysis::InstructionSemantics2::NativeSemantics::Dispatcher::instance().

static Ptr Rose::BinaryAnalysis::Debugger::instance ( const Specimen specimen)

Create a debugger and start debugging a specimen.

Definition at line 275 of file BinaryDebugger.h.

void Rose::BinaryAnalysis::Debugger::attach ( const Specimen ,
Sawyer::Optional< DetachMode onDelete = Sawyer::Nothing() 

Attach to a specimen.

The onDelete argument specifies what to do with the subordinate process if this debugger object is deleted while the subordinate is still attached. If onDelete is not specified, then a reasonable value is chosen: for subordinates that existed prior to attaching (e.g., Linux process ID), the default detach mechanism is either DETACH or NOTHING depending on whether the Specimen ATTACH flag was set or clear. For subordniates that are created by this attach method (such as ELF executables), the detach mechanism is KILL.

Referenced by Debugger().

int Rose::BinaryAnalysis::Debugger::isAttached ( )

Returns true if attached to a subordinate.

Return value is the subordinate process ID.

Definition at line 294 of file BinaryDebugger.h.

void Rose::BinaryAnalysis::Debugger::detach ( Sawyer::Optional< DetachMode mode = Sawyer::Nothing())

Detach from the subordinate.

If a detach mode is specified then use that mechanism to detatch. Otherwise use whatever mechanism was chosen as the default during the attach operation.

void Rose::BinaryAnalysis::Debugger::terminate ( )

Terminate the subordinate.

void Rose::BinaryAnalysis::Debugger::executionAddress ( rose_addr_t  va)

Set execution address.

rose_addr_t Rose::BinaryAnalysis::Debugger::executionAddress ( )

Get execution address.

Referenced by trace().

void Rose::BinaryAnalysis::Debugger::setBreakpoint ( const AddressInterval )

Set breakpoints.

void Rose::BinaryAnalysis::Debugger::clearBreakpoint ( const AddressInterval )

Remove breakpoints.

void Rose::BinaryAnalysis::Debugger::clearBreakpoints ( )

Remove all breakpoints.

Definition at line 322 of file BinaryDebugger.h.

References Sawyer::Container::IntervalSet< I >::clear().

void Rose::BinaryAnalysis::Debugger::singleStep ( )

Execute one instruction.

Referenced by trace().

void Rose::BinaryAnalysis::Debugger::runToBreakpoint ( )

Run until the next breakpoint is reached.

void Rose::BinaryAnalysis::Debugger::runToSyscall ( )

Run until the next system call.

The subordinate is run until it is about to make a system call or has just returned from a system call, or it has encountered a signal or terminated. Execution does not stop at break points.

Sawyer::Container::Trace<rose_addr_t> Rose::BinaryAnalysis::Debugger::trace ( )

Run the program and return an execution trace.

template<class Filter >
Sawyer::Container::Trace<rose_addr_t> Rose::BinaryAnalysis::Debugger::trace ( Filter &  filter)

Run the program and return an execution trace.

At each step along the execution, the filter functor is invoked and passed the current execution address. The return value of type FilterAction from the filter functor controls whether the address is appended to the trace and whether the tracing should continue.

Definition at line 358 of file BinaryDebugger.h.

References Sawyer::Container::Trace< T, IndexTag >::append(), executionAddress(), Rose::BitFlags< E, V >::isClear(), Rose::BitFlags< E, V >::isSet(), isTerminated(), REJECT, singleStep(), and STOP.

size_t Rose::BinaryAnalysis::Debugger::kernelWordSize ( )

Obtain and cache kernel's word size in bits.

The wordsize of the kernel is not necessarily the same as the word size of the compiled version of this header.

Sawyer::Container::BitVector Rose::BinaryAnalysis::Debugger::readRegister ( RegisterDescriptor  )

Read subordinate register.

Some registers are wider than what can be easily represented on this architecture (e.g., x86 XMM registers are 128 bits), therefore return the result as a bit vector. If you want just the low-order 64 bits, invoke it like this:

uint64_t value = debugger->readRegister(RIP).toInteger();
Sawyer::Container::BitVector Rose::BinaryAnalysis::Debugger::readMemory ( rose_addr_t  va,
size_t  nBytes,
ByteOrder::Endianness  order 

Read subordinate memory as a bit vector.

uint64_t value = debugger->readMemory(0x12345678, 4, ByteOrder::ORDER_LSB).toInteger();
size_t Rose::BinaryAnalysis::Debugger::readMemory ( rose_addr_t  va,
size_t  nBytes,
uint8_t *  buffer 

Read subordinate memory.

Returns the number of bytes read. The implementation accesses the subordinate memory via proc filesystem rather than sending PTRACE_PEEKDATA commands. This allows large areas of memory to be read efficiently.

std::string Rose::BinaryAnalysis::Debugger::readCString ( rose_addr_t  va,
size_t  maxBytes = UNLIMITED 

Read C-style NUL-terminated string from subordinate.

Reads up to maxBytes bytes from the subordinate or until an ASCII NUL character is read, concatenates all the characters (except the NUL) into a C++ string and returns it. The maxBytes includes the NUL terminator although the NUL terminator is not returned as part of the string.

bool Rose::BinaryAnalysis::Debugger::isTerminated ( )

Returns true if the subordinate terminated.

Referenced by trace().

std::string Rose::BinaryAnalysis::Debugger::howTerminated ( )

String describing how the subordinate process terminated.

const RegisterDictionary* Rose::BinaryAnalysis::Debugger::registerDictionary ( ) const

Available registers.

Disassembler* Rose::BinaryAnalysis::Debugger::disassembler ( ) const


Definition at line 416 of file BinaryDebugger.h.

int Rose::BinaryAnalysis::Debugger::waitpidStatus ( ) const

Returns the last status from a call to waitpid.

Definition at line 421 of file BinaryDebugger.h.

static void Rose::BinaryAnalysis::Debugger::initDiagnostics ( )

Initialize diagnostic output.

This is called automatically when ROSE is initialized.

Member Data Documentation

Sawyer::Message::Facility Rose::BinaryAnalysis::Debugger::mlog

Diagnostic facility for debugger.

Definition at line 223 of file BinaryDebugger.h.

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