Package ghidra.app.util.bin

Class BinaryReader

java.lang.Object

ghidra.app.util.bin.BinaryReader

Direct Known Subclasses:

FactoryBundledWithBinaryReader

public class BinaryReader
extends java.lang.Object

A class for reading data from a generic byte provider in either big-endian or little-endian.

Field Summary

Fields

Modifier and Type	Field	Description
static int	SIZEOF_BYTE	The size of a BYTE in Java.
static int	SIZEOF_INT	The size of an INTEGER in Java.
static int	SIZEOF_LONG	The size of a LONG in Java.
static int	SIZEOF_SHORT	The size of a SHORT in Java.

Constructor Summary

Constructors

Constructor	Description
BinaryReader(ByteProvider provider, boolean isLittleEndian)	Constructs a reader using the given file and endian-order.

Method Summary

Modifier and Type	Method	Description
int	align(int alignValue)	Aligns the current index on the specified alignment value.
BinaryReader	clone(int newIndex)	Returns a clone of this reader positioned at the new index.
ByteProvider	getByteProvider()	Returns the underlying byte provider.
long	getPointerIndex()	Returns the current index value.
boolean	isLittleEndian()	Returns true if this reader will extract values in little endian, otherwise in big endian.
boolean	isValidIndex(int index)	Returns true if the specified index into the underlying byte provider is valid.
boolean	isValidIndex(long index)	Returns true if the specified index into the underlying byte provider is valid.
long	length()	Returns the length of the underlying file.
byte	peekNextByte()	Peeks at the next byte without incrementing the current index.
int	peekNextInt()	Peeks at the next integer without incrementing the current index.
long	peekNextLong()	Peeks at the next long without incrementing the current index.
short	peekNextShort()	Peeks at the next short without incrementing the current index.
java.lang.String	readAsciiString(long index)	Reads an Ascii string starting at index, ending at the next character outside the range [32..126] or when reaching the end of the underlying ByteProvider.
java.lang.String	readAsciiString(long index, int length)	Returns an Ascii string of length bytes starting at index.
java.lang.String[]	readAsciiStringArray(long index, int nElements)	Returns the Ascii string array of nElements starting at index
byte	readByte(long index)	Returns the signed BYTE at index.
byte[]	readByteArray(long index, int nElements)	Returns the BYTE array of nElements starting at index.
java.lang.String	readFixedLenAsciiString(long index, int len)	Reads an fixed length Ascii string starting at index.
int	readInt(long index)	Returns the signed INTEGER at index.
int	readInt(long index, int minClamp, int maxClamp)	Returns the INTEGER at index, after coercing it into the range [minClamp-maxClamp].
int[]	readIntArray(long index, int nElements)	Returns the INTEGER array of nElements starting at index.
long	readLong(long index)	Returns the LONG at index.
long[]	readLongArray(long index, int nElements)	Returns the LONG array of nElements starting at index.
java.lang.String	readNextAsciiString()	Reads the Ascii string at the current index and then increments the current index by the length of the Ascii string that was found.
java.lang.String	readNextAsciiString(int length)	Reads an Ascii string of length characters starting at the current index and then increments the current index by length.
byte	readNextByte()	Reads the byte at the current index and then increments the current index by SIZEOF_BYTE.
byte[]	readNextByteArray(int nElements)	Reads a byte array of nElements starting at the current index and then increments the current index by SIZEOF_BYTE * nElements.
int	readNextInt()	Reads the integer at the current index and then increments the current index by SIZEOF_INT.
int[]	readNextIntArray(int nElements)	Reads an integer array of nElements starting at the current index and then increments the current index by SIZEOF_INT * nElements.
long	readNextLong()	Reads the long at the current index and then increments the current index by SIZEOF_LONG.
long[]	readNextLongArray(int nElements)	Reads a long array of nElements starting at the current index and then increments the current index by SIZEOF_LONG * nElements.
java.lang.String	readNextNullTerminatedAsciiString()	Reads a null terminated Ascii string starting at the current index, ending at the first null character or when reaching the end of the underlying ByteProvider.
short	readNextShort()	Reads the short at the current index and then increments the current index by SIZEOF_SHORT.
short[]	readNextShortArray(int nElements)	Reads a short array of nElements starting at the current index and then increments the current index by SIZEOF_SHORT * nElements.
java.lang.String	readNextUnicodeString()	Reads the Unicode string at the current index and then increments the current index by the length of the Unicode string that was found.
java.lang.String	readNextUnicodeString(int length)	Reads fixed length UTF-16 Unicode string the current index and then increments the current pointer index by length elements (length*2 bytes).
int	readNextUnsignedByte()	Reads the unsigned byte at the current index and then increments the current index by SIZEOF_BYTE.
long	readNextUnsignedInt()	Reads the unsigned integer at the current index and then increments the current index by SIZEOF_INT.
int	readNextUnsignedShort()	Reads the unsigned short at the current index and then increments the current index by SIZEOF_SHORT.
short	readShort(long index)	Returns the signed SHORT at index.
short[]	readShortArray(long index, int nElements)	Returns the SHORT array of nElements starting at index.
java.lang.String	readTerminatedString(long index, char termChar)	Reads an Ascii string starting at index, ending at the next termChar character byte or when reaching the end of the underlying ByteProvider.
java.lang.String	readTerminatedString(long index, java.lang.String termChars)	Reads an Ascii string starting at index, ending at the next character that is one of the specified termChars or when reaching the end of the underlying ByteProvider.
java.lang.String	readUnicodeString(long index)	Reads a null-terminated UTF-16 Unicode string starting at index using the pre-specified endianness.
java.lang.String	readUnicodeString(long index, int length)	Reads a fixed length UTF-16 Unicode string of length characters starting at index, using the pre-specified endianness.
int	readUnsignedByte(long index)	Returns the unsigned BYTE at index.
long	readUnsignedInt(long index)	Returns the unsigned INTEGER at index.
int	readUnsignedShort(long index)	Returns the unsigned SHORT at index.
void	setLittleEndian(boolean isLittleEndian)	Sets the endian of this binary reader.
void	setPointerIndex(int index)	A convenience method for setting the index using an integer.
void	setPointerIndex(long index)	Sets the current index to the specified value.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

SIZEOF_BYTE

public static final int SIZEOF_BYTE

The size of a BYTE in Java.

See Also:

Constant Field Values

SIZEOF_SHORT

public static final int SIZEOF_SHORT

The size of a SHORT in Java.

See Also:

Constant Field Values

SIZEOF_INT

public static final int SIZEOF_INT

The size of an INTEGER in Java.

See Also:

Constant Field Values

SIZEOF_LONG

public static final int SIZEOF_LONG

The size of a LONG in Java.

See Also:

Constant Field Values

Constructor Detail

BinaryReader

public BinaryReader(ByteProvider provider,
                    boolean isLittleEndian)

Constructs a reader using the given file and endian-order. If isLittleEndian is true, then all values read from the file will be done so assuming little-endian order. Otherwise, if isLittleEndian is false, then all values will be read assuming big-endian order.

Parameters:

provider - the byte provider

isLittleEndian - the endian-order

Method Detail

clone

public BinaryReader clone(int newIndex)

Returns a clone of this reader positioned at the new index.

Parameters:

newIndex - the new index

Returns:

a clone of this reader positioned at the new index

isLittleEndian

public boolean isLittleEndian()

Returns true if this reader will extract values in little endian, otherwise in big endian.

Returns:

true is little endian, false is big endian

setLittleEndian

public void setLittleEndian(boolean isLittleEndian)

Sets the endian of this binary reader.

Parameters:

isLittleEndian - true for little-endian and false for big-endian

length

public long length()
            throws java.io.IOException

Returns the length of the underlying file.

Returns:

returns the length of the underlying file

Throws:

java.io.IOException - if an I/O error occurs

isValidIndex

public boolean isValidIndex(int index)
                     throws java.io.IOException

Returns true if the specified index into the underlying byte provider is valid.

Parameters:

index - the index in the byte provider

Returns:

returns true if the specified index is valid

Throws:

java.io.IOException - if an I/O error occurs

isValidIndex

public boolean isValidIndex(long index)
                     throws java.io.IOException

Returns true if the specified index into the underlying byte provider is valid.

Parameters:

index - the index in the byte provider

Returns:

returns true if the specified index is valid

Throws:

java.io.IOException - if an I/O error occurs

align

public int align(int alignValue)

Aligns the current index on the specified alignment value. For example, if current index was 123 and align value was 16, then current index would become 128.

Parameters:

alignValue -

Returns:

the number of bytes required to align

setPointerIndex

public void setPointerIndex(int index)

A convenience method for setting the index using an integer.

setPointerIndex

public void setPointerIndex(long index)

Sets the current index to the specified value. The pointer index will allow the reader to operate as a psuedo-iterator.

Parameters:

index - the byte provider index value

getPointerIndex

public long getPointerIndex()

Returns the current index value.

Returns:

the current index value

peekNextByte

public byte peekNextByte()
                  throws java.io.IOException

Peeks at the next byte without incrementing the current index.

Returns:

the next byte

Throws:

java.io.IOException - if an I/O error occurs

peekNextShort

public short peekNextShort()
                    throws java.io.IOException

Peeks at the next short without incrementing the current index.

Returns:

the next short

Throws:

java.io.IOException - if an I/O error occurs

peekNextInt

public int peekNextInt()
                throws java.io.IOException

Peeks at the next integer without incrementing the current index.

Returns:

the next int

Throws:

java.io.IOException - if an I/O error occurs

peekNextLong

public long peekNextLong()
                  throws java.io.IOException

Peeks at the next long without incrementing the current index.

Returns:

the next long

Throws:

java.io.IOException - if an I/O error occurs

readNextByte

public byte readNextByte()
                  throws java.io.IOException

Reads the byte at the current index and then increments the current index by SIZEOF_BYTE.

Returns:

the byte at the current index

Throws:

java.io.IOException - if an I/O error occurs

readNextUnsignedByte

public int readNextUnsignedByte()
                         throws java.io.IOException

Reads the unsigned byte at the current index and then increments the current index by SIZEOF_BYTE.

Returns:

the unsigned byte at the current index, as an int

Throws:

java.io.IOException - if an I/O error occurs

readNextShort

public short readNextShort()
                    throws java.io.IOException

Reads the short at the current index and then increments the current index by SIZEOF_SHORT.

Returns:

the short at the current index

Throws:

java.io.IOException - if an I/O error occurs

readNextUnsignedShort

public int readNextUnsignedShort()
                          throws java.io.IOException

Reads the unsigned short at the current index and then increments the current index by SIZEOF_SHORT.

Returns:

the unsigned short at the current index, as an int

Throws:

java.io.IOException - if an I/O error occurs

readNextInt

public int readNextInt()
                throws java.io.IOException

Reads the integer at the current index and then increments the current index by SIZEOF_INT.

Returns:

the integer at the current index

Throws:

java.io.IOException - if an I/O error occurs

readNextUnsignedInt

public long readNextUnsignedInt()
                         throws java.io.IOException

Reads the unsigned integer at the current index and then increments the current index by SIZEOF_INT.

Returns:

the unsigned integer at the current index, as a long

Throws:

java.io.IOException - if an I/O error occurs

readNextLong

public long readNextLong()
                  throws java.io.IOException

Reads the long at the current index and then increments the current index by SIZEOF_LONG.

Returns:

the long at the current index

Throws:

java.io.IOException - if an I/O error occurs

readNextAsciiString

public java.lang.String readNextAsciiString()
                                     throws java.io.IOException

Reads the Ascii string at the current index and then increments the current index by the length of the Ascii string that was found. This method expects the string to be null-terminated.

Returns:

the null-terminated Ascii string at the current index

Throws:

java.io.IOException - if an I/O error occurs

readNextNullTerminatedAsciiString

public java.lang.String readNextNullTerminatedAsciiString()
                                                   throws java.io.IOException

Reads a null terminated Ascii string starting at the current index, ending at the first null character or when reaching the end of the underlying ByteProvider.

The current index is advanced to the next byte after the null terminator.

Returns:

the null-terminated Ascii string at the current index

Throws:

java.io.IOException - if an I/O error occurs

readNextAsciiString

public java.lang.String readNextAsciiString(int length)
                                     throws java.io.IOException

Reads an Ascii string of length characters starting at the current index and then increments the current index by length.

Returns:

the Ascii string at the current index

Throws:

java.io.IOException

readNextUnicodeString

public java.lang.String readNextUnicodeString()
                                       throws java.io.IOException

Reads the Unicode string at the current index and then increments the current index by the length of the Unicode string that was found. This method expects the string to be double null-terminated ('\0\0').

Returns:

the null-terminated Ascii string at the current index

Throws:

java.io.IOException - if an I/O error occurs

readNextUnicodeString

public java.lang.String readNextUnicodeString(int length)
                                       throws java.io.IOException

Reads fixed length UTF-16 Unicode string the current index and then increments the current pointer index by length elements (length*2 bytes).

Returns:

the UTF-16 Unicode string at the current index

Throws:

java.io.IOException - if an I/O error occurs

readNextByteArray

public byte[] readNextByteArray(int nElements)
                         throws java.io.IOException

Reads a byte array of nElements starting at the current index and then increments the current index by SIZEOF_BYTE * nElements.

Returns:

the byte array starting at the current index

Throws:

java.io.IOException - if an I/O error occurs

readNextShortArray

public short[] readNextShortArray(int nElements)
                           throws java.io.IOException

Reads a short array of nElements starting at the current index and then increments the current index by SIZEOF_SHORT * nElements.

Returns:

the short array starting at the current index

Throws:

java.io.IOException - if an I/O error occurs

readNextIntArray

public int[] readNextIntArray(int nElements)
                       throws java.io.IOException

Reads an integer array of nElements starting at the current index and then increments the current index by SIZEOF_INT * nElements.

Returns:

the integer array starting at the current index

Throws:

java.io.IOException - if an I/O error occurs

readNextLongArray

public long[] readNextLongArray(int nElements)
                         throws java.io.IOException

Reads a long array of nElements starting at the current index and then increments the current index by SIZEOF_LONG * nElements.

Returns:

the long array starting at the current index

Throws:

java.io.IOException - if an I/O error occurs

readAsciiString

public java.lang.String readAsciiString(long index)
                                 throws java.io.IOException

Reads an Ascii string starting at index, ending at the next character outside the range [32..126] or when reaching the end of the underlying ByteProvider.

Leading and trailing spaces will be trimmed before the string is returned.

Parameters:

index - the index where the Ascii string begins

Returns:

the trimmed Ascii string

Throws:

java.io.IOException - if an I/O error occurs

readAsciiString

public java.lang.String readAsciiString(long index,
                                        int length)
                                 throws java.io.IOException

Returns an Ascii string of length bytes starting at index. This method does not care about null-terminators. Leading and trailing spaces will be trimmed before the string is returned.

Parameters:

index - the index where the Ascii string begins

length - the length of the Ascii string

Returns:

the trimmed Ascii string

Throws:

java.io.IOException - if an I/O error occurs

readTerminatedString

public java.lang.String readTerminatedString(long index,
                                             char termChar)
                                      throws java.io.IOException

Reads an Ascii string starting at index, ending at the next termChar character byte or when reaching the end of the underlying ByteProvider.

Does NOT trim the string.

Parameters:

index - the index where the Ascii string begins

Returns:

the Ascii string (excluding the terminating character)

Throws:

java.io.IOException - if an I/O error occurs

readTerminatedString

public java.lang.String readTerminatedString(long index,
                                             java.lang.String termChars)
                                      throws java.io.IOException

Reads an Ascii string starting at index, ending at the next character that is one of the specified termChars or when reaching the end of the underlying ByteProvider.

Does NOT trim the string.

Parameters:

index - the index where the Ascii string begins

Returns:

the Ascii string (excluding the terminating character)

Throws:

java.io.IOException - if an I/O error occurs

readFixedLenAsciiString

public java.lang.String readFixedLenAsciiString(long index,
                                                int len)
                                         throws java.io.IOException

Reads an fixed length Ascii string starting at index.

Does NOT trim the string.

Parameters:

index - the index where the Ascii string begins

len - number of bytes to read

Returns:

the Ascii string

Throws:

java.io.IOException - if an I/O error occurs

readUnicodeString

public java.lang.String readUnicodeString(long index)
                                   throws java.io.IOException

Reads a null-terminated UTF-16 Unicode string starting at index using the pre-specified endianness.

The end of the string is denoted by a two-byte (ie. short) null character.

Leading and trailing spaces will be trimmed before the string is returned.

Parameters:

index - the index where the UTF-16 Unicode string begins

Returns:

the trimmed UTF-16 Unicode string

Throws:

java.io.IOException - if an I/O error occurs

readUnicodeString

public java.lang.String readUnicodeString(long index,
                                          int length)
                                   throws java.io.IOException

Reads a fixed length UTF-16 Unicode string of length characters starting at index, using the pre-specified endianness.

This method does not care about null-terminators.

Leading and trailing spaces will be trimmed before the string is returned.

Parameters:

index - the index where the UTF-16 Unicode string begins

length - the number of UTF-16 character elements to read.

Returns:

the trimmed UTF-16 Unicode string

Throws:

java.io.IOException - if an I/O error occurs

readByte

public byte readByte(long index)
              throws java.io.IOException

Returns the signed BYTE at index.

Parameters:

index - the index where the BYTE begins

Returns:

the signed BYTE

Throws:

java.io.IOException - if an I/O error occurs

readUnsignedByte

public int readUnsignedByte(long index)
                     throws java.io.IOException

Returns the unsigned BYTE at index.

Parameters:

index - the index where the BYTE begins

Returns:

the unsigned BYTE as an int

Throws:

java.io.IOException - if an I/O error occurs

readShort

public short readShort(long index)
                throws java.io.IOException

Returns the signed SHORT at index.

Parameters:

index - the index where the SHORT begins

Returns:

the signed SHORT

Throws:

java.io.IOException - if an I/O error occurs

readUnsignedShort

public int readUnsignedShort(long index)
                      throws java.io.IOException

Returns the unsigned SHORT at index.

Parameters:

index - the index where the SHORT begins

Returns:

the unsigned SHORT as an int

Throws:

java.io.IOException - if an I/O error occurs

readInt

public int readInt(long index)
            throws java.io.IOException

Returns the signed INTEGER at index.

Parameters:

index - the index where the INTEGER begins

Returns:

the signed INTEGER

Throws:

java.io.IOException - if an I/O error occurs

readUnsignedInt

public long readUnsignedInt(long index)
                     throws java.io.IOException

Returns the unsigned INTEGER at index.

Parameters:

index - the index where the INTEGER begins

Returns:

the unsigned INTEGER as a long

Throws:

java.io.IOException - if an I/O error occurs

readInt

public int readInt(long index,
                   int minClamp,
                   int maxClamp)
            throws java.io.IOException

Returns the INTEGER at index, after coercing it into the range [minClamp-maxClamp].

Parameters:

index - the index where the INTEGER begins

minClamp - minimum value that will be returned

maxClamp - maximum value that will be returned

Returns:

the INTEGER

Throws:

java.io.IOException - if an I/O error occurs

readLong

public long readLong(long index)
              throws java.io.IOException

Returns the LONG at index.

Parameters:

index - the index where the LONG begins

Returns:

the LONG

Throws:

java.io.IOException - if an I/O error occurs

readByteArray

public byte[] readByteArray(long index,
                            int nElements)
                     throws java.io.IOException

Returns the BYTE array of nElements starting at index.

Parameters:

index - the index where the BYTE begins

nElements - the number of array elements

Returns:

the BYTE array

Throws:

java.io.IOException - if an I/O error occurs

readShortArray

public short[] readShortArray(long index,
                              int nElements)
                       throws java.io.IOException

Returns the SHORT array of nElements starting at index.

Parameters:

index - the index where the SHORT begins

nElements - the number of array elements

Returns:

the SHORT array

Throws:

java.io.IOException - if an I/O error occurs

readIntArray

public int[] readIntArray(long index,
                          int nElements)
                   throws java.io.IOException

Returns the INTEGER array of nElements starting at index.

Parameters:

index - the index where the INTEGER begins

nElements - the number of array elements

Returns:

the INTEGER array

Throws:

java.io.IOException - if an I/O error occurs

readLongArray

public long[] readLongArray(long index,
                            int nElements)
                     throws java.io.IOException

Returns the LONG array of nElements starting at index.

Parameters:

index - the index where the LONG begins

nElements - the number of array elements

Returns:

the LONG array

Throws:

java.io.IOException - if an I/O error occurs

readAsciiStringArray

public java.lang.String[] readAsciiStringArray(long index,
                                               int nElements)
                                        throws java.io.IOException

Returns the Ascii string array of nElements starting at index

Parameters:

index - the index where the Ascii Strings begin

nElements - the number of array elements

Returns:

the Ascii String array

Throws:

java.io.IOException - if an I/O error occurs

getByteProvider

public ByteProvider getByteProvider()

Returns the underlying byte provider.

Returns:

the underlying byte provider