Package ghidra.formats.gfilesystem

Class FSRL

java.lang.Object
ghidra.formats.gfilesystem.FSRL
Direct Known Subclasses:
FSRLRoot
public class FSRL extends Object
A _F_ile _S_ystem _R_esource _L_ocator, (name and string format patterned after URLs)

Used to locate a resource (by name) on a "filesystem", in a recursively nested fashion.

The string format of FSRLs is fstype + "://" + path + optional_MD5 [ + "|" pipe + FSRL ]*

See fromPartString(FSRL, String) for more format info.

Read the string format from right-to-left for easiest understanding... ie. "file://z|y://x" reads as "file x inside a filesystem y inside a container file z".

FSRL instances are immutable and thread-safe.

Examples (pipes shown in red since they are hard to see):

  • file://dir/subdir -- simplest example, locates a file on local computer filesystem.
  • file://dir/subdir/example.zip|zip://readme.txt -- points to a file named "readme.txt" in a zip file.
  • file://dir/subdir/example.zip|zip://dir/nested.tar|tar://file.txt -- points to a file inside a TAR archive, which is inside a ZIP archive, which is on the local filesystem.
  • file://dir/subdir/example.zip?MD5=1234567|zip://readme.txt?MD5=987654 -- points to a file named "readme.txt" (with a MD5 hash) in a zip file (that has another MD5 hash).

See FSRLRoot for examples of how FSRL and FSRLRoot's are related.

FSRL's can be created either piecemeal, from the bottom up, starting with a root filesystem FSRL and calling appendPath(String) or FSRLRoot.nestedFS(FSRL, String) methods to create deeper and deeper nested FSRLs,

or

FSRL's can be created from strings using fromString(String).

FSRLs that have a MD5 value are "fully qualified".

  • Field Details

  • Constructor Details

    • FSRL

      protected FSRL(FSRL parent, String path)
      Protected constructor called by static factory methods such as fromString(String) or methods that return a new instance such as withPath(String).
      Parameters:
      parent - FSRL parent, null if this instance is root FSRLRoot
      path - String path, meaning dependent on context

    • FSRL

      protected FSRL(FSRL parent, String path, String md5)
      Protected constructor called by static factory methods such as fromString(String) or methods that return a new instance such as withPath(String).
      Parameters:
      parent - FSRL parent, null if this instance is root FSRLRoot
      path - String path, meaning dependent on context
      md5 - hex string with the md5 hash of the file this FSRL points to, null ok.

  • Method Details

    • fromProgram

      public static FSRL fromProgram(Program program)
      Returns the FSRL stored in a Program's properties, or null if not present or malformed.
      Parameters:
      program - Program
      Returns:
      FSRL from program's properties, or null if not present or invalid

    • writeToProgramInfo

      public static void writeToProgramInfo(Program program, FSRL fsrl)
      Writes a FSRL value to a Program's properties.
      Parameters:
      program - Program
      fsrl - FSRL to write

    • fromString

      public static FSRL fromString(String fsrlStr) throws MalformedURLException
      Creates a FSRL from a raw string. The parent portions of the FSRL are not intern()'d so will not be shared with other FSRL instances.

      See fromPartString(FSRL, String) for details of character encoding fixups.

      Parameters:
      fsrlStr - something like "fstype://path/path|fs2type://path2/path2|etc://etc/etc"
      Returns:
      new FSRL instance, never null
      Throws:
      MalformedURLException - if empty string or bad format

    • fromString

      public static FSRL fromString(FSRL parent, String fsrlStr) throws MalformedURLException
      Creates a FSRL from a raw string.

      See fromPartString(FSRL, String) for details of character encoding fixups.

      Parameters:
      parent - Parent FSRL
      fsrlStr - something like "fstype://path/path|fs2type://path2/path2|etc://etc/etc"
      Returns:
      new FSRL instance, never null
      Throws:
      MalformedURLException - if empty string or bad format

    • convertRootToContainer

      public static FSRL convertRootToContainer(FSRL fsrl)
      Ensures that a FSRL instance is a file type reference by converting any FSRLRoots into the container file that hosts the FSRLRoot.
      Parameters:
      fsrl - FSRL or FSRLRoot instance to possibly convert
      Returns:
      original FSRL if already a normal FSRL, or the container if it was a FSRLRoot

    • getFS

      public FSRLRoot getFS()
      Returns the FSRLRoot object that represents the entire filesystem for this FSRL.

      Never returns NULL, and calling getFS() on a FSRLRoot object returns itself.

      Returns:
      FSRLRoot instance that is the parent of this FSRL, never null.

    • getNestingDepth

      public int getNestingDepth()
      Returns the number of FSRLRoots there are in this FSRL.

      A single level FSRL such as "file://path" will return 1.
      A two level FSRL such as "file://path|subfs://path2" will return 2.
      etc.

      Returns:
      number of levels in this FSRL, min value returned is 1.

    • getPath

      public String getPath()
      Returns the full path/filename of this FSRL. Does not include parent filesystem path or info.

      "file://path|subfs://subpath/blah" returns "/subpath/blah"

      May return null if this instance is a FSRLRoot.

      Returns:
      string path and filename of this object. Null if this FSRL is a FSRLRoot.

    • getName

      public String getName()
      Returns the name portion of this FSRL's path, everything after the last '/'

      "file://path/name.ext" returns "name.ext"

      Returns:
      name portion of this FSRL path, or null if path is null also.

    • getName

      public String getName(int nestedDepth) throws IOException
      Returns the name portion of the FSRL part at parent depth nestedDepth, where 0 is ourself (equiv to just calling getName(), 1 is the parent container's name, etc.
      Parameters:
      nestedDepth - relative parent index of FSRL part to query, 0 == this instance.
      Returns:
      name portion of the path of the specified FSRL part.
      Throws:
      IOException - if nestedDepth is larger than number of FSRL parent parts.

    • getMD5

      public String getMD5()
      Returns the MD5 string associated with this file.

      NULL if no MD5 value present.

      Returns:
      md5 string associated with this file object, or null if not present.

    • isMD5Equal

      public boolean isMD5Equal(String otherMD5)
      Tests specified MD5 value against MD5 in this FSRL.
      Parameters:
      otherMD5 - md5 in a hex string
      Returns:
      boolean true if equal, or that both are null, false otherwise

    • withMD5

      public FSRL withMD5(String newMD5)
      Creates a new FSRL instance, using the same information as this instance, but with a new MD5 value.
      Parameters:
      newMD5 - string md5
      Returns:
      new FSRL instance with the same path and the specified md5 value, or if newMD5 is same as existing, returns this

    • withPath

      public FSRL withPath(String newpath)
      Creates a new FSRL instance, using the same FSRLRoot as this instance, but with a new path.

      See also appendPath(String).

      Parameters:
      newpath - string path
      Returns:
      new FSRL instance with the specified path.

    • withPath

      public FSRL withPath(FSRL copyPath)
      Creates a new FSRL instance using the same path and other metadata present in the copyPath instance.

      Used when re-root'ing a FSRL path onto another parent object (usually during intern()'ing)

      Parameters:
      copyPath - another FSRL to copy path and md5 from
      Returns:
      new FSRL instance

    • appendPath

      public FSRL appendPath(String relPath)
      Creates a new FSRL instance, using the same FSRLRoot as this instance, combining the current path with the relPath value.
      Parameters:
      relPath - relative path string to append, '/'s will be automatically added
      Returns:
      new FSRL instance with additional path appended.

    • makeNested

      public FSRLRoot makeNested(String fstype)
      Creates a new FSRLRoot instance that is a child of this FSRL.

      See FSRLRoot.nestedFS(FSRL, FSRLRoot) and FSRLRoot.nestedFS(FSRL, String).

      Parameters:
      fstype - file system type string.
      Returns:
      new FSRLRoot instance

    • toString

      public String toString()
      Returns a string containing the full FSRL.

      Example: "file://path|subfs://blah?MD5=1234567"

      Overrides:
      toString in class Object
      Returns:
      string with full FSRL

    • toPrettyString

      public String toPrettyString()
      Returns a string containing the full FSRL, excluding MD5 portions.
      Returns:
      string with full FSRL, excluding MD5 portions.

    • toPrettyFullpathString

      public String toPrettyFullpathString()
      Returns a string containing the full FSRL, without FS "fstype://" portions

      Example:

      "fsrl://path/filename?MD5=1234|subfsrl://subpath/subfile"

      will result in

      "path/filename|subpath/subfile".

      Returns:
      formatted string such as: "path/filename|subpath/subfile"

    • appendToStringBuilder

      protected void appendToStringBuilder(StringBuilder sb, boolean recurse, boolean includeParams, boolean includeFSRoot)

    • toStringPart

      public String toStringPart()
      Returns a string containing just the current FSRL protocol and path.

      Example: "file://path|subfs://blah?MD5=123456" returns "subfs://blah?MD5=123456"

      Returns:
      string containing just the current FSRL protocol and path.

    • split

      public List<FSRL> split()
      Splits a FSRL into a List, with each element pointing to each level of the full FSRL.

      Example: "file://path|subfs://blah|subfs2://blah2"

      Produces a list of 3 elements:
      "file://path"
      "file://path|subfs://blah"
      "file://path|subfs://blah|subfs2://blah2"

      Returns:
      List of FSRL elements pointing to each level of this FSRL.

    • isEquivalent

      public boolean isEquivalent(String fsrlStr)
      Returns true if the two FSRLs are the same, excluding any MD5 values.
      Parameters:
      fsrlStr - string-ified FSRL
      Returns:
      boolean true if this instance is the same as the specified string-ified fsrl, ignoring any md5 values.

    • isEquivalent

      public boolean isEquivalent(FSRL other)
      Returns true if the two FSRLs are the same, excluding any MD5 values.
      Parameters:
      other - FSRL to compare with
      Returns:
      boolean true if this instance is the same as the specified FSRL, ignoring any md5 values.

    • isDescendantOf

      public boolean isDescendantOf(FSRL potentialParent)
      Returns true if this object is a child or descendant of the specified potentialParent parameter.
      Parameters:
      potentialParent - FSRL to test against
      Returns:
      boolean true if the specified FSRL is a parent (ignoring md5 hashes) of this instance.

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • equals

      public boolean equals(Object obj)
      Overrides:
      equals in class Object