Package ghidra.app.util.bin

# Class GhidraRandomAccessFile

java.lang.Object
ghidra.app.util.bin.GhidraRandomAccessFile

All Implemented Interfaces:
  `AutoCloseable`

public class GhidraRandomAccessFile extends Object implements AutoCloseable
Instances of this class support both reading and writing to a random access file. A random access file behaves like a large array of bytes stored in the file system. There is a kind of cursor, or index into the implied array, called the file pointer. This implementation relies on java.net.RandomAccessFile, but adds buffering to limit the amount.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `GhidraRandomAccessFile(File file, String mode)`
  Creates a random access file stream to read from, and optionally to write to, the file specified by the `File` argument.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `close()`
  Closes this random access file stream and releases any system resources associated with the stream.
  `protected void`
  `finalize()`
  `long`
  `length()`
  Returns the length of this file.
  `int`
  `read(byte[] b)`
  Reads up to `b.length` bytes of data from this file into an array of bytes.
  `int`
  `read(byte[] b, int offset, int length)`
  Reads up to `length` bytes of data from this file into an array of bytes.
  `byte`
  `readByte()`
  This method reads a byte from the file, starting from the current file pointer.
  `void`
  `seek(long pos)`
  Sets the file-pointer offset, measured from the beginning of this file, at which the next read or write occurs.
  `void`
  `write(byte b)`
  Writes a byte to this file, starting at the current file pointer.
  `void`
  `write(byte[] b)`
  Writes `b.length` bytes from the specified byte array to this file, starting at the current file pointer.
  `void`
  `write(byte[] b, int offset, int length)`
  Writes a sub array as a sequence of bytes.

  ### Methods inherited from class java.lang.Object

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

- ## Constructor Details

  - ### GhidraRandomAccessFile

    public GhidraRandomAccessFile(File file, String mode) throws FileNotFoundException
    Creates a random access file stream to read from, and optionally to write to, the file specified by the `File` argument. A new `FileDescriptor` object is created to represent this file connection.

    This implementation relies on java.net.RandomAccessFile, but adds buffering to limit the amount.

    The `mode` argument specifies the access mode in which the file is to be opened. The permitted values and their meanings are:

    > Access mode permitted values and meanings
    > Value | Meaning
    > --- | ---
    > `"r"` | Open for reading only. Invoking any of the `write` methods of the resulting object will cause an `IOException` to be thrown.
    > `"rw"` | Open for reading and writing. If the file does not already exist then an attempt will be made to create it.
    > `"rws"` | Open for reading and writing, as with `"rw"`, and also require that every update to the file's content or metadata be written synchronously to the underlying storage device.
    > `"rwd"` | Open for reading and writing, as with `"rw"`, and also require that every update to the file's content be written synchronously to the underlying storage device.

    Parameters:
      `file` - the file object
      `mode` - the access mode, as described above
    Throws:
      `IllegalArgumentException` - if the mode argument is not equal to one of `"r"`, `"rw"`, `"rws"`, or `"rwd"`
      `FileNotFoundException` - that name cannot be created, or if some other error occurs while opening or creating the file

- ## Method Details

  - ### finalize

    protected void finalize()
    Overrides:
      `finalize` in class `Object`

  - ### close

    public void close() throws IOException
    Closes this random access file stream and releases any system resources associated with the stream. A closed random access file cannot perform input or output operations and cannot be reopened.

    If this file has an associated channel then the channel is closed as well.

    Specified by:
      `close` in interface `AutoCloseable`
    Throws:
      `IOException` - if an I/O error occurs.

  - ### length

    public long length() throws IOException
    Returns the length of this file.
    Returns:
      the length of this file, measured in bytes.
    Throws:
      `IOException` - if an I/O error occurs.

  - ### seek

    public void seek(long pos) throws IOException
    Sets the file-pointer offset, measured from the beginning of this file, at which the next read or write occurs. The offset may be set beyond the end of the file. Setting the offset beyond the end of the file does not change the file length. The file length will change only by writing after the offset has been set beyond the end of the file.
    Parameters:
      `pos` - the offset position, measured in bytes from the beginning of the file, at which to set the file pointer.
    Throws:
      `IOException` - if `pos` is less than `0` or if an I/O error occurs.

  - ### readByte

    public byte readByte() throws IOException
    This method reads a byte from the file, starting from the current file pointer.

    This method blocks until the byte is read, the end of the stream is detected, or an exception is thrown.

    Returns:
      the next byte of this file as a signed eight-bit `byte`.
    Throws:
      `EOFException` - if this file has reached the end.
      `IOException` - if an I/O error occurs.

  - ### read

    public int read(byte[] b) throws IOException
    Reads up to `b.length` bytes of data from this file into an array of bytes. This method blocks until at least one byte of input is available.
    Parameters:
      `b` - the buffer into which the data is read.
    Returns:
      the total number of bytes read into the buffer, or `-1` if there is no more data because the end of this file has been reached.
    Throws:
      `IOException` - if an I/O error occurs.

  - ### read

    public int read(byte[] b, int offset, int length) throws IOException
    Reads up to `length` bytes of data from this file into an array of bytes. This method blocks until at least one byte of input is available.
    Parameters:
      `b` - the buffer into which the data is read.
      `offset` - the start offset of the data.
      `length` - the maximum number of bytes read.
    Returns:
      the total number of bytes read into the buffer, or `-1` if there is no more data because the end of the file has been reached.
    Throws:
      `IOException` - if an I/O error occurs.

  - ### write

    public void write(byte b) throws IOException
    Writes a byte to this file, starting at the current file pointer.
    Parameters:
      `b` - the data.
    Throws:
      `IOException` - if an I/O error occurs.

  - ### write

    public void write(byte[] b) throws IOException
    Writes `b.length` bytes from the specified byte array to this file, starting at the current file pointer.
    Parameters:
      `b` - the data.
    Throws:
      `IOException` - if an I/O error occurs.

  - ### write

    public void write(byte[] b, int offset, int length) throws IOException
    Writes a sub array as a sequence of bytes.
    Parameters:
      `b` - the data to be written
      `offset` - the start offset in the data
      `length` - the number of bytes that are written
    Throws:
      `IOException` - If an I/O error has occurred.