Package ghidra.program.model.symbol

Class SymbolUtilities

java.lang.Object
ghidra.program.model.symbol.SymbolUtilities
public class SymbolUtilities extends Object
Class with static methods to deal with symbol strings.

  • Field Details

  • Constructor Details

    • SymbolUtilities

      public SymbolUtilities()

  • Method Details

    • getOrdinalValue

      public static int getOrdinalValue(String symbolName)

    • containsInvalidChars

      public static boolean containsInvalidChars(String str)
      Checks a string for invalid characters (control chars, space chars, whitespace chars).
      Parameters:
      str - the string to be checked for invalid characters.
      Returns:
      boolean true if the string has invalid chars, false if string is valid

    • getDefaultFunctionName

      public static String getDefaultFunctionName(Address addr)
      Generates a default function name for a given address.
      Parameters:
      addr - the entry point of the function.
      Returns:
      the default generated name for the function.

    • isReservedExternalDefaultName

      public static boolean isReservedExternalDefaultName(String name, AddressFactory addrFactory)
      Returns true if the specified name is reserved as a default external name.
      Parameters:
      name -
      addrFactory -
      Returns:
      true if the specified name is reserved as a default external name.

    • getDefaultExternalFunctionName

      public static String getDefaultExternalFunctionName(Address addr)
      Generates a default external name for an external function
      Parameters:
      addr - the memory address referred to by the external.
      Returns:
      the default generated name for the external.

    • getDefaultExternalName

      public static String getDefaultExternalName(Address addr, DataType dt)
      Generates a default external name for a given external data/code location.
      Parameters:
      addr - the memory address referred to by the external.
      dt - data type associated with the specified external memory address
      Returns:
      the default generated name for the external.

    • isReservedDynamicLabelName

      public static boolean isReservedDynamicLabelName(String name, AddressFactory addrFactory)
      Returns true if the given name could match a default dynamic label (EXT, LAB, SUB, FUN, DAT) at some address. WARNING! Does not handle dynamic labels which use data-type prefixes - see isDynamicSymbolPattern(String, boolean) for more liberal check

    • validateName

      public static void validateName(String name) throws InvalidInputException
      Validate the given symbol name: cannot be null, cannot be an empty string, cannot contain blank characters, cannot be a reserved name.
      Parameters:
      name - symbol name to be validated
      Throws:
      InvalidInputException - invalid or reserved name has been specified

    • startsWithDefaultDynamicPrefix

      public static boolean startsWithDefaultDynamicPrefix(String name)
      Returns true if the given name starts with a possible default symbol prefix.
      Parameters:
      name - the name string to test.
      Returns:
      true if name starts with a know dynamic prefix

    • isDynamicSymbolPattern

      public static boolean isDynamicSymbolPattern(String name, boolean caseSensitive)
      Tests if the given name is a possible dynamic symbol name. WARNING! This method should be used carefully since it will return true for any name which starts with a known dynamic label prefix or ends with an '_' followed by a valid hex value.
      Parameters:
      name - the name to test
      caseSensitive - true if case matters.
      Returns:
      true if name is a possible dynamic symbol name, else false

    • isInvalidChar

      public static boolean isInvalidChar(char c)
      Returns true if the specified char is not valid for use in a symbol name.

      See isInvalidCodePoint(int) for better method that uses code points instead of chars.

      Parameters:
      c - the character to be tested as a valid symbol character.
      Returns:
      boolean true if c is an invalid char within a symbol name, else false

    • isInvalidCodePoint NEW

      public static boolean isInvalidCodePoint(int cp)
      Returns true if the specified code point is not valid for use in a symbol name.
      Parameters:
      cp - the code point to be tested as a valid symbol character.
      Returns:
      boolean true if the code point is an invalid character within a symbol name, else false

    • replaceInvalidChars

      public static String replaceInvalidChars(String str, boolean replaceWithUnderscore)
      Converts a string with possible invalid characters into a valid symbol string.
      Parameters:
      str - String to fix, null ok
      replaceWithUnderscore - - true means replace the invalid chars with underscores, else if false, then just drop the invalid chars
      Returns:
      either the original String instance if already valid (or null), or a new string that contains the valid portions of the original with any bad chars removed or replaced with underscores.

    • replaceInvalidChars NEW

      public static String replaceInvalidChars(String str, SymbolUtilities.BadCharFixupFunc badCharFixup)
      Converts a string with possible invalid characters into a valid symbol string.
      Parameters:
      str - String to fix, null ok
      badCharFixup - callback that controls how each bad char is fixed. It should return a string that should be used in place of the invalid character, or null if nothing should be used.
      Returns:
      either the original String instance if already valid (or null), or a new string that contains the valid portions of the original with any fixed-ups as returned by the badCharFixup callback.

    • getDynamicOffcutName

      public static String getDynamicOffcutName(Address addr)
      Create a dynamic label name for an offcut reference.
      Parameters:
      addr - the address at which to create an offcut reference name.
      Returns:
      dynamic offcut label name

    • getDynamicName

      public static String getDynamicName(int referenceLevel, Address addr)
      Create a name for a dynamic symbol with a 3-letter prefix based upon reference level and an address. Acceptable referenceLevel's are: UNK_LEVEL, DAT_LEVEL, LAB_LEVEL, SUB_LEVEL, EXT_LEVEL, FUN_LEVEL.
      Parameters:
      referenceLevel - the type of reference for which to create a dynamic name.
      addr - the address at which to create a dynamic name.
      Returns:
      dynamic symbol name

    • getDynamicName

      public static String getDynamicName(Program program, Address addr)
      Create a name for a dynamic symbol.
      Parameters:
      program - the current program
      addr - the address of the symbol for which to generate a name
      Returns:
      a name for the symbol at the given address

    • getDiffString

      public static String getDiffString(long diff)
      Returns a string representing an address offset. If the offset is less than 10, it doesn't add a prefix, otherwise the difference is shown in hex and includes the "0x" prefix.
      Parameters:
      diff - the address difference
      Returns:
      a string representing an offset from an address that is formated simply for small values and in hex with a prefix for larger values.

    • parseDynamicName

      public static Address parseDynamicName(AddressFactory factory, String name)
      Parse a dynamic name and return its address or null if unable to parse.
      Parameters:
      factory - address factory
      name - the dynamic label name to parse into an address.
      Returns:
      address corresponding to symbol name if it satisfies possible dynamic naming or null if unable to parse address fro name

    • getAddressString

      public static String getAddressString(Address addr)

    • getDefaultParamName

      public static String getDefaultParamName(int ordinal)

    • isDefaultParameterName

      public static boolean isDefaultParameterName(String name)

    • getDefaultLocalName

      public static String getDefaultLocalName(Program program, int stackOffset, int firstUseOffset)

    • getDefaultLocalName

      public static String getDefaultLocalName(Program program, VariableStorage storage, int firstUseOffset)

    • isDefaultLocalName

      public static boolean isDefaultLocalName(Program program, String name, VariableStorage storage)

    • isPossibleDefaultLocalOrParamName

      public static boolean isPossibleDefaultLocalOrParamName(String name)
      Returns true if the given name is a possible default parameter name or local variable name
      Parameters:
      name - the name to check to see if it is a possible default local or parameter name
      Returns:
      true if the given name is a possible default parameter name or local variable name

    • isPossibleDefaultExternalName

      public static boolean isPossibleDefaultExternalName(String name)
      Checks if the given name could be a default external location name
      Parameters:
      name - the name to check
      Returns:
      true if the given name is a possible default external location name

    • isDefaultLocalStackName

      public static boolean isDefaultLocalStackName(String name)

    • getAddressAppendedName

      public static String getAddressAppendedName(String name, Address address)
      Creates the standard symbol name for symbols that have the addresses appended to the name following an "@" character in order to make it unique.
      Parameters:
      name - the "true" name of the symbol
      address - the address to be appended
      Returns:
      the name with the address appended.

    • getCleanSymbolName

      public static String getCleanSymbolName(Symbol symbol)
      Gets the base symbol name regardless of whether or not the address has been appended.
      Parameters:
      symbol - the symbol to get the clean name for.
      Returns:
      the base symbol name where the "@<address>" has been stripped away if it exists.

    • getCleanSymbolName

      public static String getCleanSymbolName(String symbolName, Address address)
      Gets the base symbol name regardless of whether or not the address has been appended using either the standard "@" separator, or the less preferred "_" separator. The address string extension must match that which is produced by the getAddressString(Address) method for it to be recognized.
      Parameters:
      symbolName - a symbol name to get the clean name for.
      address - the symbol's address
      Returns:
      the base symbol name where the "@<address>" has been stripped away if it exists.

    • getSymbolTypeDisplayName

      public static String getSymbolTypeDisplayName(Symbol symbol)
      Returns display text suitable for describing in the GUI the SymbolType of the given symbol
      Parameters:
      symbol - The symbol from which to get the SymbolType
      Returns:
      a display string for the SymbolType

    • getUniqueSymbol

      public static Symbol getUniqueSymbol(Program program, String name)
      Returns the global symbol with the given name if and only if it is the only global symbol with that name.
      Parameters:
      program - the program to search.
      name - the name of the global symbol to find.
      Returns:
      the global symbol with the given name if and only if it is the only one.

    • getUniqueSymbol

      public static Symbol getUniqueSymbol(Program program, String name, Namespace namespace)
      Returns the symbol in the given namespace with the given name if and only if it is the only symbol in that namespace with that name.
      Parameters:
      program - the program to search.
      name - the name of the symbol to find.
      namespace - the parent namespace; may be null
      Returns:
      the symbol with the given name if and only if it is the only one in that namespace

    • getExpectedLabelOrFunctionSymbol

      public static Symbol getExpectedLabelOrFunctionSymbol(Program program, String symbolName, Consumer<String> errorConsumer)
      Returns the unique global label or function symbol with the given name. Also, logs if there is not exactly one symbol with that name.
      Parameters:
      program - the program to search.
      symbolName - the name of the global label or function symbol to search.
      errorConsumer - the object to use for reporting errors via it's accept() method.
      Returns:
      symbol if a unique label/function symbol with name is found or null

    • getLabelOrFunctionSymbol

      public static Symbol getLabelOrFunctionSymbol(Program program, String symbolName, Consumer<String> errorConsumer)
      Returns the unique global label or function symbol with the given name. Also, logs if there is more than one symbol with that name.
      Parameters:
      program - the program to search.
      symbolName - the name of the global label or function symbol to search.
      errorConsumer - the object to use for reporting errors via it's accept() method.
      Returns:
      symbol if a unique label/function symbol with name is found or null

    • createPreferredLabelOrFunctionSymbol

      public static Symbol createPreferredLabelOrFunctionSymbol(Program program, Address address, Namespace namespace, String name, SourceType source) throws InvalidInputException
      Create label symbol giving preference to non-global symbols. An existing function symbol may be returned. If attempting to create a global symbol and the name already exists at the address no symbol will be created and null will be returned. If attempting to create a non-global symbol, which does not exist, and a global symbol does exist with same name its namespace will be changed.
      Parameters:
      program - program within which the symbol should be created
      address - memory address where symbol should be created
      namespace - symbol namespace or null for global
      name - symbol name
      source - symbol source type
      Returns:
      new or existing label or function symbol or null if creating a global symbol whose name already exists at address
      Throws:
      InvalidInputException - if invalid symbol name provided

    • getSymbolNameComparator

      public static Comparator<Symbol> getSymbolNameComparator()
      Returns a comparator for symbols. The comparison is based upon the name. This call replaces the former compareTo method on Symbol. This comparator returned here is case-insensitive.
      Returns:
      the comparator