Package ghidra.program.util

# Class ExternalSymbolResolver

java.lang.Object
ghidra.program.util.ExternalSymbolResolver

All Implemented Interfaces:
  `Closeable`, `AutoCloseable`

public class ExternalSymbolResolver extends Object implements Closeable
Moves dangling external function symbols found in the `EXTERNAL/UNKNOWN` namespace into the namespace of the external library that publishes a matching symbol.

This uses an ordered list of external library names that was attached to the program during import by the Elf or Macho loader (see `REQUIRED_LIBRARY_PROPERTY_PREFIX`).

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ExternalSymbolResolver(ProjectData projectData, TaskMonitor monitor)`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addProgramToFixup(Loaded<Program> loaded)`
  Queues a `Loaded` `Program` into this session that will be fixed when `fixUnresolvedExternalSymbols()` is called.
  `void`
  `addProgramToFixup(Program program)`
  Queues a program into this session that will be fixed when `fixUnresolvedExternalSymbols()` is called.
  `void`
  `close()`
  `void`
  `fixUnresolvedExternalSymbols()`
  Resolves any unresolved external symbols in each program that has been queued up via `addProgramToFixup(Loaded)` or `addProgramToFixup(Program)`.
  `protected Program`
  `getLibraryProgram(String libPath)`
  Fetches a program from a cache of Program instances.
  `static List<String>`
  `getOrderedRequiredLibraryNames(Program program)`
  Returns an ordered list of library names, as specified by the logic/rules of the original operating system's loader (eg.
  `static String`
  `getRequiredLibraryProperty(int libraryIndex)`
  Gets a program property name to represent the ordered required library of the given index
  `boolean`
  `hasProblemLibraries()`
  Returns true if there was an error encountered when trying to open an external library.
  `void`
  `logInfo(Consumer<String> logger, boolean shortSummary)`
  Logs information about the libraries and symbols that were found during the fixup.
  `protected Program`
  `openLibraryFile(DomainFile libDf, String libPath)`
  Opens a library binary.

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

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

- ## Constructor Details

  - ### ExternalSymbolResolver

    public ExternalSymbolResolver(ProjectData projectData, TaskMonitor monitor)

- ## Method Details

  - ### getRequiredLibraryProperty

    public static String getRequiredLibraryProperty(int libraryIndex)
    Gets a program property name to represent the ordered required library of the given index
    Parameters:
      `libraryIndex` - The index of the required library
    Returns:
      A program property name to represent the ordered required library of the given index

  - ### getOrderedRequiredLibraryNames

    public static List<String> getOrderedRequiredLibraryNames(Program program)
    Returns an ordered list of library names, as specified by the logic/rules of the original operating system's loader (eg. Elf / MachO dynamic library loading / symbol resolving rules)
    Parameters:
      `program` - The `Program`
    Returns:
      list of library names, in original order

  - ### addProgramToFixup

    public void addProgramToFixup(Program program)
    Queues a program into this session that will be fixed when `fixUnresolvedExternalSymbols()` is called.

    The program should be fully persisted to the project if using this method, otherwise use `addProgramToFixup(Loaded)`.

    Parameters:
      `program` - `Program` to fix

  - ### addProgramToFixup

    public void addProgramToFixup(Loaded<Program> loaded)
    Queues a `Loaded` `Program` into this session that will be fixed when `fixUnresolvedExternalSymbols()` is called.
    Parameters:
      `loaded` - The `Loaded` `Program` to fix

  - ### hasProblemLibraries

    public boolean hasProblemLibraries()
    Returns true if there was an error encountered when trying to open an external library.
    Returns:
      boolean flag, true if there was a problem opening an external library

  - ### close

    public void close()
    Specified by:
      `close` in interface `AutoCloseable`
    Specified by:
      `close` in interface `Closeable`

  - ### fixUnresolvedExternalSymbols

    public void fixUnresolvedExternalSymbols() throws CancelledException
    Resolves any unresolved external symbols in each program that has been queued up via `addProgramToFixup(Loaded)` or `addProgramToFixup(Program)`.
    Throws:
      `CancelledException` - if cancelled

  - ### logInfo

    public void logInfo(Consumer<String> logger, boolean shortSummary)
    Logs information about the libraries and symbols that were found during the fixup.
    Parameters:
      `logger` - consumer that will log a string
      `shortSummary` - boolean flag, if true individual symbol names will be omitted

  - ### getLibraryProgram

    protected Program getLibraryProgram(String libPath) throws CancelledException
    Fetches a program from a cache of Program instances. If the requested program isn't currently in the cache, it will be opened (if possible).

    This cache of programs are pinned by registering a consumer on the program, and will be released during `close()` of this ExternalSymbolServer instance.

    This cache is shared between all ProgramSymbolResolver instances (that were created by calling `addProgramToFixup(Loaded)` or `addProgramToFixup(Program)`).

    Parameters:
      `libPath` - project path to a library program
    Returns:
      `Program`, or null if not found or other error during opening
    Throws:
      `CancelledException` - if cancelled

  - ### openLibraryFile

    protected Program openLibraryFile(DomainFile libDf, String libPath) throws CancelledException
    Opens a library binary.
    Parameters:
      `libDf` - optional, reference to a the DomainFile that was found in a project. If null (meaning a lookup in the project failed to find a matching file), libPath will be used when creating error strings that reference the problematic file
      `libPath` - project path for the DomainFile
    Returns:
      a opened `Program`
    Throws:
      `CancelledException` - if cancelled