Package ghidra.program.model.listing

Interface Program

All Superinterfaces:
DataTypeManagerDomainObject, DataTypeManagerOwner, DomainObject, ProgramArchitecture
All Known Implementing Classes:
ProgramDB
public interface Program extends DataTypeManagerDomainObject, ProgramArchitecture
This interface represents the main entry point into an object which stores all information relating to a single program. This program model divides a program into four major parts: the memory, the symbol table, the equate table, and the listing. Each of these parts has an extensive interface and can be retrieved via this program interface. Although the components are divided into separate objects, they are not independent. Any changes to one component may and probably will affect the other components. Also, the state of one component will restrict the actions of another component. For example, the createCodeUnit() method of listing will fail if memory is undefined at the address where the codeUnit is to be created.

  • Field Details

    • ANALYSIS_PROPERTIES

      static final String ANALYSIS_PROPERTIES
      See Also:

    • DISASSEMBLER_PROPERTIES

      static final String DISASSEMBLER_PROPERTIES
      See Also:

    • PROGRAM_INFO

      static final String PROGRAM_INFO
      Options for storing program info
      See Also:

    • ANALYZED_OPTION_NAME

      static final String ANALYZED_OPTION_NAME
      Name of boolean analyzed property
      See Also:

    • ASK_TO_ANALYZE_OPTION_NAME

      static final String ASK_TO_ANALYZE_OPTION_NAME
      Property to control if user should be asked to analyze when unanalyzed program opened
      See Also:

    • DATE_CREATED

      static final String DATE_CREATED
      Date created property
      See Also:

    • CREATED_WITH_GHIDRA_VERSION

      static final String CREATED_WITH_GHIDRA_VERSION
      Ghidra version property
      See Also:

    • PREFERRED_ROOT_NAMESPACE_CATEGORY_PROPERTY

      static final String PREFERRED_ROOT_NAMESPACE_CATEGORY_PROPERTY
      Ghidra preferred root namespace category property
      See Also:

    • ANALYSIS_START_DATE

      static final String ANALYSIS_START_DATE
      Creation date for analysis
      See Also:

    • ANALYSIS_START_DATE_FORMAT

      static final String ANALYSIS_START_DATE_FORMAT
      Format string of analysis date
      See Also:

    • JANUARY_1_1970

      static final Date JANUARY_1_1970
      A date from January 1, 1970

    • MAX_OPERANDS

      static final int MAX_OPERANDS
      The maximum number of operands for any assembly language
      See Also:

  • Method Details

    • getListing

      Listing getListing()
      Get the listing object.
      Returns:
      the Listing interface to the listing object.

    • getAddressMap

      @Deprecated(forRemoval=true) AddressMap getAddressMap()
      Deprecated, for removal: This API element is subject to removal in a future version.
      Method intended for internal ProgramDB use and is not intended for general use. This method may be removed from this interface in a future release.
      Get the internal program address map
      Returns:
      internal address map

    • getDataTypeManager

      ProgramBasedDataTypeManager getDataTypeManager()
      Returns the program's datatype manager.
      Specified by:
      getDataTypeManager in interface DataTypeManagerOwner
      Returns:
      the data type manager.

    • getFunctionManager

      FunctionManager getFunctionManager()
      Returns the programs function manager.
      Returns:
      the function manager

    • getProgramUserData

      ProgramUserData getProgramUserData()
      Returns the user-specific data manager for this program.
      Returns:
      the program-specific user data manager

    • getSymbolTable

      SymbolTable getSymbolTable()
      Get the symbol table object.
      Returns:
      the symbol table object.

    • getExternalManager

      ExternalManager getExternalManager()
      Returns the external manager.
      Returns:
      the external manager

    • getEquateTable

      EquateTable getEquateTable()
      Get the equate table object.
      Returns:
      the equate table.

    • getMemory

      Memory getMemory()
      Get the memory object.
      Returns:
      the memory object.

    • getReferenceManager

      ReferenceManager getReferenceManager()
      Get the reference manager.
      Returns:
      the reference manager

    • getBookmarkManager

      BookmarkManager getBookmarkManager()
      Get the bookmark manager.
      Returns:
      the bookmark manager

    • getDefaultPointerSize

      int getDefaultPointerSize()
      Gets the default pointer size in bytes as it may be stored within the program listing.
      Returns:
      default pointer size.
      See Also:

    • getCompiler

      String getCompiler()
      Gets the name of the compiler believed to have been used to create this program. If the compiler hasn't been determined then "unknown" is returned.
      Returns:
      name of the compiler or "unknown".

    • setCompiler

      void setCompiler(String compiler)
      Sets the name of the compiler which created this program.
      Parameters:
      compiler - the name

    • getPreferredRootNamespaceCategoryPath

      CategoryPath getPreferredRootNamespaceCategoryPath()
      Gets the preferred root data type category path which corresponds to the global namespace of a namespace-based storage area. Preference will be given to this category when searching for data types within a specific namespace. This setting corresponds to the Program Information option "Preferred Root Namespace Category. See DataTypeUtilities and its various find methods for its usage details.
      Returns:
      data type category path for root namespace or null if not set or is invalid.

    • setPreferredRootNamespaceCategoryPath

      void setPreferredRootNamespaceCategoryPath(String categoryPath)
      Sets the preferred data type category path which corresponds to the root of a namespace hierarchy storage area. Preference will be given to this category when searching for data types within a specific namespace. This setting corresponds to the Program Information option "Preferred Root Namespace Category. See DataTypeUtilities and its various find methods for its usage details.
      Parameters:
      categoryPath - data type category path for root namespace or null to clear option. The specified path must be absolute and start with "/" and must not end with one (e.g., /ClassDataTypes). An invalid path setting will be ignored.

    • getExecutablePath

      String getExecutablePath()
      Gets the path to the program's executable file. For example, /home/user/foo.exe. This will allow plugins to execute the program.

      NOTE: The format of the path is not guaranteed to follow any standard naming conventions. If used for anything other than display purpose, callers of this method should take extra steps to ensure the path is in a form suitable for their needs.

      Returns:
      String path to program's exe file

    • setExecutablePath

      void setExecutablePath(String path)
      Sets the path to the program's executable file. For example, /home/user/foo.exe.
      Parameters:
      path - the path to the program's exe

    • getExecutableFormat

      String getExecutableFormat()
      Returns a value corresponding to the original file format.
      Returns:
      original file format used to load program or null if unknown

    • setExecutableFormat

      void setExecutableFormat(String format)
      Sets the value corresponding to the original file format.
      Parameters:
      format - the binary file format string to set.

    • getExecutableMD5

      String getExecutableMD5()
      Returns a value corresponding to the original binary file MD5 hash.
      Returns:
      original loaded file MD5 or null

    • setExecutableMD5

      void setExecutableMD5(String md5)
      Sets the value corresponding to the original binary file MD5 hash.
      Parameters:
      md5 - MD5 binary file hash

    • setExecutableSHA256

      void setExecutableSHA256(String sha256)
      Sets the value corresponding to the original binary file SHA256 hash.
      Parameters:
      sha256 - SHA256 binary file hash

    • getExecutableSHA256

      String getExecutableSHA256()
      Returns a value corresponding to the original binary file SHA256 hash.
      Returns:
      original loaded file SHA256 or null

    • getCreationDate

      Date getCreationDate()
      Returns the creation date of this program. If the program was created before this property existed, then Jan 1, 1970 is returned.
      Returns:
      the creation date of this program

    • getRelocationTable

      RelocationTable getRelocationTable()
      Gets the relocation table.
      Returns:
      relocation table object

    • getLanguage

      Language getLanguage()
      Returns the language used by this program.
      Specified by:
      getLanguage in interface ProgramArchitecture
      Returns:
      the language used by this program.

    • getCompilerSpec

      CompilerSpec getCompilerSpec()
      Returns the CompilerSpec currently used by this program.
      Specified by:
      getCompilerSpec in interface ProgramArchitecture
      Returns:
      the compilerSpec currently used by this program.

    • getLanguageID

      LanguageID getLanguageID()
      Return the name of the language used by this program.
      Returns:
      the name of the language

    • getUsrPropertyManager

      PropertyMapManager getUsrPropertyManager()
      Get the user propertyMangager stored with this program. The user property manager is used to store arbitrary address indexed information associated with the program.
      Returns:
      the user property manager.

    • getProgramContext

      ProgramContext getProgramContext()
      Returns the program context.
      Returns:
      the program context object

    • getMinAddress

      Address getMinAddress()
      Get the program's minimum address. NOTE: An AddressRange should generally not be formed using this address and getMaxAddress() since it may span multiple AddressSpaces.
      Returns:
      the program's minimum address or null if no memory blocks have been defined in the program.

    • getMaxAddress

      Address getMaxAddress()
      Get the programs maximum address. NOTE: An AddressRange should generally not be formed using this address and getMinAddress() since it may span multiple AddressSpaces.
      Returns:
      the program's maximum address or null if no memory blocks have been defined in the program.

    • getChanges

      ProgramChangeSet getChanges()
      Get the program changes since the last save as a set of addresses.
      Returns:
      set of changed addresses within program.

    • getAddressFactory

      AddressFactory getAddressFactory()
      Returns the AddressFactory for this program.
      Specified by:
      getAddressFactory in interface ProgramArchitecture
      Returns:
      the program address factory

    • parseAddress

      Address[] parseAddress(String addrStr)
      Return an array of Addresses that could represent the given string.
      Parameters:
      addrStr - the string to parse.
      Returns:
      zero length array if addrStr is properly formatted but no matching addresses were found or if the address is improperly formatted.

    • parseAddress

      Address[] parseAddress(String addrStr, boolean caseSensitive)
      Return an array of Addresses that could represent the given string.
      Parameters:
      addrStr - the string to parse.
      caseSensitive - whether or not to process any addressSpace names as case sensitive.
      Returns:
      zero length array if addrStr is properly formatted but no matching addresses were found or if the address is improperly formatted.

    • createOverlaySpace

      ProgramOverlayAddressSpace createOverlaySpace(String overlaySpaceName, AddressSpace baseSpace) throws IllegalStateException, DuplicateNameException, InvalidNameException, LockException
      Create a new overlay space based upon the given base AddressSpace
      Parameters:
      overlaySpaceName - the name of the new overlay space.
      baseSpace - the base AddressSpace to overlay (i.e., overlayed-space)
      Returns:
      the new overlay space
      Throws:
      DuplicateNameException - if an address space already exists with specified overlaySpaceName.
      LockException - if the program is shared and not checked out exclusively.
      IllegalStateException - if image base override is active
      InvalidNameException - if overlaySpaceName contains invalid characters

    • renameOverlaySpace

      void renameOverlaySpace(String overlaySpaceName, String newName) throws NotFoundException, InvalidNameException, DuplicateNameException, LockException
      Rename an existing overlay address space. NOTE: This experimental method has known limitations with existing Address and AddressSpace objects following an undo/redo which may continue to refer to the old overlay name which may lead to unxpected errors.
      Parameters:
      overlaySpaceName - overlay address space name
      newName - new name for overlay
      Throws:
      NotFoundException - if the specified overlay space was not found
      InvalidNameException - if new name is invalid
      DuplicateNameException - if new name already used by another address space
      LockException - if program does not has exclusive access

    • removeOverlaySpace

      boolean removeOverlaySpace(String overlaySpaceName) throws LockException, NotFoundException
      Remove the specified overlay address space from this program.
      Parameters:
      overlaySpaceName - overlay address space name
      Returns:
      true if successfully removed, else false if blocks still make use of overlay space.
      Throws:
      LockException - if program does not has exclusive access
      NotFoundException - if specified overlay space not found in program

    • getRegister

      Register getRegister(String name)
      Returns the register with the given name;
      Parameters:
      name - the name of the register to retrieve
      Returns:
      register or null

    • getRegister

      Register getRegister(Address addr)
      Returns the largest register located at the specified address
      Parameters:
      addr - register minimum address
      Returns:
      largest register at addr or null

    • getRegisters

      Register[] getRegisters(Address addr)
      Returns all registers located at the specified address
      Parameters:
      addr - register minimum address
      Returns:
      all registers at addr

    • getRegister

      Register getRegister(Address addr, int size)
      Returns a specific register based upon its address and size
      Parameters:
      addr - register address
      size - the size of the register (in bytes);
      Returns:
      register or null

    • getRegister

      Register getRegister(Varnode varnode)
      Returns the register which corresponds to the specified varnode
      Parameters:
      varnode - the varnode
      Returns:
      register or null

    • getImageBase

      Address getImageBase()
      Returns the current program image base address
      Returns:
      program image base address within default space

    • setImageBase

      void setImageBase(Address base, boolean commit) throws AddressOverflowException, LockException, IllegalStateException
      Sets the program's image base address.
      Parameters:
      base - the new image base address;
      commit - if false, then the image base change is temporary and does not really change the program and will be lost once the program is closed. If true, the change is permanent and marks the program as "changed" (needs saving).
      Throws:
      AddressOverflowException - if the new image would cause a memory block to end past the the address space.
      LockException - if the program is shared and the user does not have an exclusive checkout. This will never be thrown if commit is false.
      IllegalStateException - if the program state is not suitable for setting the image base.

    • restoreImageBase

      void restoreImageBase()
      Restores the last committed image base.

    • setLanguage

      void setLanguage(Language language, CompilerSpecID compilerSpecID, boolean forceRedisassembly, TaskMonitor monitor) throws IllegalStateException, IncompatibleLanguageException, LockException
      Sets the language for the program. If the new language is "compatible" with the old language, the addressMap is adjusted then the program is "re-disassembled".
      Parameters:
      language - the new language to use.
      compilerSpecID - the new compiler specification ID
      forceRedisassembly - if true a redisassembly will be forced. This should always be false.
      monitor - the task monitor
      Throws:
      IllegalStateException - thrown if any error occurs, including a cancelled monitor, which leaves this program object in an unusable state. The current transaction should be aborted and the program instance discarded.
      IncompatibleLanguageException - thrown if the new language is too different from the existing language.
      LockException - if the program is shared and not checked out exclusively.

    • getGlobalNamespace

      Namespace getGlobalNamespace()
      Returns the global namespace for this program
      Returns:
      the global namespace

    • createAddressSetPropertyMap

      AddressSetPropertyMap createAddressSetPropertyMap(String name) throws DuplicateNameException
      Create a new AddressSetPropertyMap with the specified name.
      Parameters:
      name - name of the property map.
      Returns:
      the newly created property map.
      Throws:
      DuplicateNameException - if a property map already exists with the given name.

    • createIntRangeMap

      IntRangeMap createIntRangeMap(String name) throws DuplicateNameException
      Create a new IntRangeMap with the specified name.
      Parameters:
      name - name of the property map.
      Returns:
      the newly created property map.
      Throws:
      DuplicateNameException - if a property map already exists with the given name.

    • getAddressSetPropertyMap

      AddressSetPropertyMap getAddressSetPropertyMap(String name)
      Get the property map with the given name.
      Parameters:
      name - name of the property map
      Returns:
      null if no property map exist with the given name

    • getIntRangeMap

      IntRangeMap getIntRangeMap(String name)
      Get the property map with the given name.
      Parameters:
      name - name of the property map
      Returns:
      null if no property map exist with the given name

    • deleteAddressSetPropertyMap

      void deleteAddressSetPropertyMap(String name)
      Remove the property map from the program.
      Parameters:
      name - name of the property map to remove

    • deleteIntRangeMap

      void deleteIntRangeMap(String name)
      Remove the property map from the program.
      Parameters:
      name - name of the property map to remove

    • getUniqueProgramID

      long getUniqueProgramID()
      Returns an ID that is unique for this program. This provides an easy way to store references to a program across client persistence.
      Returns:
      unique program ID