Package ghidra.formats.gfilesystem

Interface GFileSystem

All Superinterfaces:
AutoCloseable, Closeable, ExtensionPoint, Iterable<GFile>
All Known Implementing Classes:
AbstractFileSystem, GFileSystemBase, LocalFileSystem, LocalFileSystemSub
public interface GFileSystem extends Closeable, Iterable<GFile>, ExtensionPoint
Interface that represents a filesystem that contains files.

Operations take a TaskMonitor if they need to be cancel-able.

Use a FileSystemService instance to discover and open instances of filesystems in files or to open a known FSRL path or to deal with creating temp files.

NOTE:

ALL GFileSystem sub-CLASSES MUST END IN "FileSystem". If not, the ClassSearcher will not find them.

Also note that this interface came after the original abstract class GFileSystem and its many implementations, and usage is being migrated to this interface where possible and as time permits.

  • Method Details

    • getName

      String getName()
      File system volume name.

      Typically the name of the container file, or a internally stored 'volume' name.

      Returns:
      string filesystem volume name.

    • getType

      default String getType()
      Returns the type of this file system.

      This default implementation returns the type value in FileSystemInfo annotation.

      Returns:
      type string

    • getDescription

      default String getDescription()
      Returns a description of this file system.

      This default implementation returns the description value in FileSystemInfo annotation.

      Returns:
      description string

    • getFSRL

      FSRLRoot getFSRL()
      File system's FSRL
      Returns:
      FSRLRoot of this filesystem.

    • isClosed

      boolean isClosed()
      Returns true if the filesystem has been closed
      Returns:
      boolean true if the filesystem has been closed.

    • isStatic

      default boolean isStatic()
      Indicates if this filesystem is a static snapshot or changes.
      Returns:
      boolean true if the filesystem is static or false if dynamic content.

    • getRefManager

      FileSystemRefManager getRefManager()
      Returns the ref manager that is responsible for creating and releasing refs to this filesystem.
      Returns:
      FileSystemRefManager that manages references to this filesystem.

    • getFileCount

      default int getFileCount()
      Returns the number of files in the filesystem, if known, otherwise -1 if not known.
      Returns:
      number of files in this filesystem, -1 if not known.

    • lookup

      GFile lookup(String path) throws IOException
      Retrieves a GFile from this filesystem based on its full path and filename, using this filesystem's default name comparison logic (eg. case sensitive vs insensitive).
      Parameters:
      path - string path and filename of a file located in this filesystem. Use null or "/" to retrieve the root directory
      Returns:
      GFile instance of requested file, null if not found.
      Throws:
      IOException - if IO error when looking up file.

    • lookup

      default GFile lookup(String path, Comparator<String> nameComp) throws IOException
      Retrieves a GFile from this filesystem based on its full path and filename, using the specified name comparison logic (eg. case sensitive vs insensitive).
      Parameters:
      path - string path and filename of a file located in this filesystem. Use null or "/" to retrieve the root directory
      nameComp - string comparator used to compare filenames. Use null to specify the file system's native comparison logic.
      Returns:
      GFile instance of requested file, null if not found.
      Throws:
      IOException - if IO error when looking up file.

    • getRootDir

      default GFile getRootDir()
      Returns the file system's root directory.

      Note: using null when calling getListing(GFile) is also valid.

      Returns:
      file system's root directory

    • getInputStream

      default InputStream getInputStream(GFile file, TaskMonitor monitor) throws IOException, CancelledException
      Returns an InputStream that contains the contents of the specified GFile.

      The caller is responsible for closing the stream.

      Parameters:
      file - GFile to get an InputStream for
      monitor - TaskMonitor to watch and update progress
      Returns:
      new InputStream contains the contents of the file or NULL if the file doesn't have data.
      Throws:
      IOException - if IO problem
      CancelledException - if user cancels.

    • getByteProvider

      ByteProvider getByteProvider(GFile file, TaskMonitor monitor) throws IOException, CancelledException
      Returns a ByteProvider that contains the contents of the specified GFile.

      The caller is responsible for closing the provider.

      Parameters:
      file - GFile to get bytes for
      monitor - TaskMonitor to watch and update progress
      Returns:
      new ByteProvider that contains the contents of the file, or NULL if file doesn't have data
      Throws:
      IOException - if error
      CancelledException - if user cancels

    • getListing

      List<GFile> getListing(GFile directory) throws IOException
      Returns a list of files that reside in the specified directory on this filesystem.
      Parameters:
      directory - NULL means root of filesystem.
      Returns:
      List of GFile instances of file in the requested directory.
      Throws:
      IOException - if IO problem.

    • getFileAttributes

      default FileAttributes getFileAttributes(GFile file, TaskMonitor monitor)
      Returns a container of FileAttribute values.

      Implementors of this method are not required to add FSRL, NAME, or PATH values unless the values are non-standard.

      Parameters:
      file - GFile to get the attributes for
      monitor - TaskMonitor
      Returns:
      FileAttributes instance (possibly read-only), maybe empty but never null

    • resolveSymlinks

      default GFile resolveSymlinks(GFile file) throws IOException
      Converts the specified (symlink) file into it's destination, or if not a symlink, returns the original file unchanged.
      Parameters:
      file - symlink file to follow
      Returns:
      destination of symlink, or original file if not a symlink
      Throws:
      IOException - if error following symlink path, typically outside of the hosting file system

    • getInputStreamHelper

      static InputStream getInputStreamHelper(GFile file, GFileSystem fs, TaskMonitor monitor) throws CancelledException, IOException
      Default implementation of getting an InputStream from a GFile's ByteProvider.
      Parameters:
      file - GFile
      fs - the filesystem containing the file
      monitor - TaskMonitor to allow canceling
      Returns:
      new InputStream containing bytes of the file
      Throws:
      CancelledException - if canceled
      IOException - if error

    • files

      default Iterable<GFile> files()
      Gets an Iterable over this GFileSystem's files.
      Returns:
      An Iterable over this GFileSystem's files.

    • files

      default Iterable<GFile> files(GFile dir) throws UncheckedIOException
      Gets an Iterable over this GFileSystem's files.
      Parameters:
      dir - The directory to start iterating at in this GFileSystem. If null, iteration will start at the root of the GFileSystem.
      Returns:
      An Iterable over this GFileSystem's files.
      Throws:
      UncheckedIOException - if dir is not a directory

    • files

      default Iterable<GFile> files(Predicate<GFile> fileFilter)
      Gets an Iterable over this GFileSystem's files.
      Parameters:
      fileFilter - A filter to apply to the files iterated over
      Returns:
      An Iterable over this GFileSystem's files.

    • files

      default Iterable<GFile> files(GFile dir, Predicate<GFile> fileFilter) throws UncheckedIOException
      Gets an Iterable over this GFileSystem's files.
      Parameters:
      dir - The directory to start iterating at in this GFileSystem. If null, iteration will start at the root of the GFileSystem.
      fileFilter - A filter to apply to the files iterated over
      Returns:
      An Iterable over this GFileSystem's files.
      Throws:
      UncheckedIOException - if dir is not a directory

    • iterator

      default Iterator<GFile> iterator()
      Specified by:
      iterator in interface Iterable<GFile>