Module openj9.dtfj

Package com.ibm.dtfj.image

Interface ImagePointer

All Known Implementing Classes:

CorruptImagePointer, ImagePointer, J9DDRImagePointer, JCImagePointer

public interface ImagePointer

Represents an address in memory. To create an ImagePointer using an absolute address use com.ibm.dtfj.image.ImageAddressSpace.getPointer()

See Also:

ImageAddressSpace.getPointer(long)

Method Summary

Modifier and Type	Method	Description
ImagePointer	add(long offset)	Build a new image pointer offset from this one by the given amount.
boolean	equals(Object obj)	Compares the argument to the receiver, and answers true if they represent the same object using a class specific comparison.
long	getAddress()	Get the unwrapped address, represented as a Java long.
ImageAddressSpace	getAddressSpace()	Get the address space to which this pointer belongs.
byte	getByteAt(long index)	Get the value at the given offset from this pointer.
double	getDoubleAt(long index)	Get the value at the given offset from this pointer.
float	getFloatAt(long index)	Get the value at the given offset from this pointer.
int	getIntAt(long index)	Get the value at the given offset from this pointer.
long	getLongAt(long index)	Get the value at the given offset from this pointer.
ImagePointer	getPointerAt(long index)	Get the value at the given offset from this pointer.
Properties	getProperties()	Get the OS-specific properties for this address
short	getShortAt(long index)	Get the value at the given offset from this pointer.
int	hashCode()	Answers an integer hash code for the receiver.
boolean	isExecutable()	Tests memory execute permission.
boolean	isReadOnly()	Tests memory read/write permission.
boolean	isShared()	Tests memory shared permission.

Method Detail

getAddress

long getAddress()

Get the unwrapped address, represented as a Java long.

Use caution when comparing addresses, as some addresses may be negative.

Note that, on segmented memory architectures, it may not be possible to represent all addresses accurately as integers.

Returns:

the unwrapped address, represented as a 64-bit integer.

getAddressSpace

ImageAddressSpace getAddressSpace()

Get the address space to which this pointer belongs.

Returns:

the address space to which this pointer belongs.

add

ImagePointer add(long offset)

Build a new image pointer offset from this one by the given amount.

Parameters:

offset - Offset in bytes.

Returns:

a new ImagePointer based at getAddress() + offset

isExecutable

boolean isExecutable()
              throws DataUnavailable

Tests memory execute permission.

Returns:

true if this memory address is within an executable page.

Throws:

DataUnavailable

isReadOnly

boolean isReadOnly()
            throws DataUnavailable

Tests memory read/write permission.

Returns:

true if this memory address is read-only. False otherwise.

Throws:

DataUnavailable

isShared

boolean isShared()
          throws DataUnavailable

Tests memory shared permission.

Returns:

true if this memory address is shared between processes.

Throws:

DataUnavailable

getPointerAt

ImagePointer getPointerAt(long index)
                   throws MemoryAccessException,
                          CorruptDataException

Get the value at the given offset from this pointer. To determine the number of bytes to skip after this call to read the next value, use ImageProcess.getPointerSize(). Note: to create an ImagePointer using an absolute address use com.ibm.dtfj.image.ImageAddressSpace.getPointer()

Parameters:

index - an offset (in bytes) from the current position

Returns:

the 32 or 64-bit pointer stored at getAddress() + index

Throws:

MemoryAccessException - if the memory cannot be read

CorruptDataException - if the memory should be in the image, but is missing or corrupted

See Also:

ImageProcess.getPointerSize(), ImageAddressSpace.getPointer(long)

getLongAt

long getLongAt(long index)
        throws MemoryAccessException,
               CorruptDataException

Get the value at the given offset from this pointer.

Parameters:

index - an offset (in bytes) from the current position

Returns:

the 64-bit long stored at getAddress() + index

Throws:

MemoryAccessException - if the memory cannot be read

CorruptDataException - if the memory should be in the image, but is missing or corrupted

getIntAt

int getIntAt(long index)
      throws MemoryAccessException,
             CorruptDataException

Get the value at the given offset from this pointer.

Parameters:

index - an offset (in bytes) from the current position

Returns:

the 32-bit int stored at getAddress() + index

Throws:

MemoryAccessException - if the memory cannot be read

CorruptDataException - if the memory should be in the image, but is missing or corrupted

getShortAt

short getShortAt(long index)
          throws MemoryAccessException,
                 CorruptDataException

Get the value at the given offset from this pointer.

Parameters:

index - an offset (in bytes) from the current position

Returns:

the 16-bit short stored at getAddress() + index

Throws:

MemoryAccessException - if the memory cannot be read

CorruptDataException - if the memory should be in the image, but is missing or corrupted

getByteAt

byte getByteAt(long index)
        throws MemoryAccessException,
               CorruptDataException

Get the value at the given offset from this pointer.

Parameters:

index - an offset (in bytes) from the current position

Returns:

the 8-bit byte stored at getAddress() + index

Throws:

MemoryAccessException - if the memory cannot be read

CorruptDataException - if the memory should be in the image, but is missing or corrupted

getFloatAt

float getFloatAt(long index)
          throws MemoryAccessException,
                 CorruptDataException

Get the value at the given offset from this pointer.

Parameters:

index - an offset (in bytes) from the current position

Returns:

the 32-bit float stored at getAddress() + index

Throws:

MemoryAccessException - if the memory cannot be read

CorruptDataException - if the memory should be in the image, but is missing or corrupted

getDoubleAt

double getDoubleAt(long index)
            throws MemoryAccessException,
                   CorruptDataException

Get the value at the given offset from this pointer.

Parameters:

index - an offset (in bytes) from the current position

Returns:

the 64-bit double stored at getAddress() + index

Throws:

MemoryAccessException - if the memory cannot be read

CorruptDataException - if the memory should be in the image, but is missing or corrupted

equals

boolean equals(Object obj)

Description copied from class: java.lang.Object

Compares the argument to the receiver, and answers true if they represent the same object using a class specific comparison. The implementation in Object answers true only if the argument is the exact same object as the receiver (==).

Overrides:

equals in class Object

Parameters:

obj -

Returns:

True obj refers to the same Image Pointer in the image

See Also:

Object.hashCode()

hashCode

int hashCode()

Description copied from class: java.lang.Object

Answers an integer hash code for the receiver. Any two objects which answer true when passed to .equals must answer the same value for this method.

Overrides:

hashCode in class Object

Returns:

the receiver's hash.

See Also:

Object.equals(java.lang.Object)

getProperties

Properties getProperties()

Get the OS-specific properties for this address

Returns:

a table of OS-specific properties for this address. Values which are commonly available include

• "readable" -- whether the memory address can be read from
• "writable" -- whether the memory address can be written to
• "executable" -- whether data in the memory address can be executed

Since:

1.11