Module index

# Module `ida_name`

Functions that deal with names.

A non-tail address of the program may have a name. Tail addresses (i.e. the addresses in the middle of an instruction or data item) cannot have names.

## Global variables

`var CN_KEEP_TRAILING__DIGITS`

  do not remove "_\d+" at the end of name

`var DEBNAME_EXACT`

  find a name at exactly the specified address

`var DEBNAME_LOWER`

  find a name with the address >= the specified address

`var DEBNAME_NICE`

  find a name with the address <= the specified address

`var DEBNAME_UPPER`

  find a name with the address > the specified address

`var DQT_COMPILER`

  only detect compiler that generated the name

`var DQT_FULL`

  really demangle

`var DQT_NAME_TYPE`

  only detect the name type (data/code)

`var DQT_NPURGED_2`

  only calculate number of purged bytes (sizeof(arg)==2)

`var DQT_NPURGED_4`

  only calculate number of purged bytes (sizeof(arg)==4)

`var DQT_NPURGED_8`

  only calculate number of purged bytes (sizeof(arg)==8)

`var FUNC_IMPORT_PREFIX`

  Name prefix used by IDA for the imported functions.

`var GETN_APPZERO`

  meaningful only if the name refers to a structure. append a struct field name if the field offset is zero?

`var GETN_NODUMMY`

  do not create a new dummy name but pretend it exists

`var GETN_NOFIXUP`

  ignore the fixup information when producing the name

`var GNCN_NOCOLOR`

  generate an uncolored name

`var GNCN_NODBGNM`

  don't use debug names

`var GNCN_NOFUNC`

  don't generate funcname+… expressions

`var GNCN_NOLABEL`

  don't generate labels

`var GNCN_NOSEG`

  ignore the segment prefix when producing the name

`var GNCN_PREFDBG`

  if using debug names, prefer debug names over function names

`var GNCN_REQFUNC`

  return 0 if the address does not belong to a function

`var GNCN_REQNAME`

  return 0 if the address can only be represented as a hex number

`var GNCN_SEGNUM`

  segment part is displayed as a hex number

`var GNCN_SEG_FUNC`

  generate both segment and function names (default is to omit segment name if a function name is present)

`var GN_COLORED`

  return colored name

`var GN_DEMANGLED`

  return demangled name

`var GN_ISRET`

  for dummy names: use retloc

`var GN_LOCAL`

  try to get local name first; if failed, get global

`var GN_LONG`

  use long form of demangled name

`var GN_NOT_DUMMY`

  do not return a dummy name

`var GN_NOT_ISRET`

  for dummy names: do not use retloc

`var GN_SHORT`

  use short form of demangled name

`var GN_STRICT`

  fail if cannot demangle

`var GN_VISIBLE`

  replace forbidden characters by SUBSTCHAR

`var MAXNAMELEN`

  Maximum length of a name in IDA (with the trailing zero)

`var NT_ABS`

  name is absolute symbol (SEG_ABSSYM)

`var NT_BMASK`

  name is a bit group mask name

`var NT_BYTE`

  name is byte name (regular name)

`var NT_ENUM`

  name is symbolic constant

`var NT_LOCAL`

  name is local label

`var NT_NONE`

  name doesn't exist or has no value

`var NT_REGVAR`

  name is a renamed register (*value is idx into pfn->regvars)

`var NT_SEG`

  name is segment or segment register name

`var NT_STKVAR`

  name is stack variable name

`var NT_STROFF`

  name is structure member

`var SN_AUTO`

  if set, make name autogenerated

`var SN_CHECK`

  Fail if the name contains invalid characters.

`var SN_DELTAIL`

  if name cannot be set because of a tail byte, delete the hindering item

`var SN_FORCE`

  if the specified name is already present in the database, try variations with a numerical suffix like "_123"

`var SN_IDBENC`

  the name is given in the IDB encoding; non-ASCII bytes will be decoded accordingly. Specifying SN_IDBENC also implies SN_NODUMMY

`var SN_LOCAL`

  create local name. a function should exist. local names can't be public or weak. also they are not included into the list of names they can't have dummy prefixes.

`var SN_NOCHECK`

  Replace invalid characters silently. If this bit is set, all invalid chars (not in NameChars or MangleChars) will be replaced by '_' List of valid characters is defined in ida.cfg

`var SN_NODUMMY`

  automatically prepend the name with '' if it begins with a dummy suffix such as 'sub'. See also SN_IDBENC

`var SN_NOLIST`

  if set, exclude name from the list. if not set, then include the name into the list (however, if other bits are set, the name might be immediately excluded from the list).

`var SN_NON_AUTO`

  if set, make name non-autogenerated

`var SN_NON_PUBLIC`

  if set, make name non-public

`var SN_NON_WEAK`

  if set, make name non-weak

`var SN_NOWARN`

  don't display a warning if failed

`var SN_PUBLIC`

  if set, make name public

`var SN_WEAK`

  if set, make name weak

`var UCDR_MANGLED`

  mangled names

`var UCDR_NAME`

  regular (unmangled) names

`var UCDR_STRLIT`

  string literals

`var UCDR_TYPE`

  type names

`var VNT_IDENT`

  identifier (e.g., function name)

`var VNT_STRLIT`

  string literal

`var VNT_TYPE`

  type name (can contain '<', '>', …)

`var VNT_UDTMEM`

  UDT (structure, union, enum) member.

`var VNT_VISIBLE`

  visible cp (obsolete; will be deleted)

## Functions

`def append_struct_fields(disp: adiff_t *, n: int, path: tid_t const *, flags: flags64_t, delta: adiff_t, appzero: bool)`

  append_struct_fields(disp, n, path, flags, delta, appzero) -> str Append names of struct fields to a name if the name is a struct name.

  @param disp: (C++: adiff_t ) displacement from the name @param n: (C++: int) operand number in which the name appears @param path: (C++: const tid_t ) path in the struct. path is an array of id's. maximal length of array is MAXSTRUCPATH. the first element of the array is the structure id. consecutive elements are id's of used union members (if any). @param flags: (C++: flags64_t) the input flags. they will be returned if the struct cannot be found. @param delta: (C++: adiff_t) delta to add to displacement @param appzero: (C++: bool) should append a struct field name if the displacement is zero? @return: flags of the innermost struct member or the input flags

`def calc_gtn_flags(fromaddr, ea)`

  Calculate flags for get_ea_name() function

  @param fromaddr: the referring address. May be BADADDR. @param ea: linear address

  @return: flags

`def cleanup_name(ea: ea_t, name: char const *, flags: uint32 = 0)`

  cleanup_name(ea, name, flags=0) -> bool

  @param ea: ea_t @param name: char const * @param flags: uint32

`def del_debug_names(ea1: ea_t, ea2: ea_t)`

  del_debug_names(ea1, ea2)

  @param ea1: ea_t @param ea2: ea_t

`def del_global_name(ea: ea_t)`

  del_global_name(ea) -> bool

  @param ea: ea_t

`def del_local_name(ea: ea_t)`

  del_local_name(ea) -> bool

  @param ea: ea_t

`def demangle_name(name: char const *, disable_mask: uint32, demreq: demreq_type_t = 2)`

  demangle_name(name, disable_mask, demreq=DQT_FULL) -> int32 Demangle a name.

  @param name: (C++: const char *) char const * @param disable_mask: (C++: uint32) @param demreq: (C++: demreq_type_t) enum demreq_type_t

`def extract_name(line: char const *, x: int)`

  extract_name(line, x) -> str Extract a name or address from the specified string.

  @param line: (C++: const char *) input string @param x: (C++: int) x coordinate of cursor @return: -1 if cannot extract. otherwise length of the name

`def force_name(ea: ea_t, name: char const *, flags: int = 0)`

  force_name(ea, name, flags=0) -> bool

  @param ea: ea_t @param name: char const * @param flags: int

`def get_colored_demangled_name(ea: ea_t, inhibitor: int32, demform: int, gtn_flags: int = 0)`

  get_colored_demangled_name(ea, inhibitor, demform, gtn_flags=0) -> qstring

  @param ea: ea_t @param inhibitor: int32 @param demform: int @param gtn_flags: int

`def get_colored_long_name(ea: ea_t, gtn_flags: int = 0)`

  get_colored_long_name(ea, gtn_flags=0) -> qstring

  @param ea: ea_t @param gtn_flags: int

`def get_colored_name(ea: ea_t)`

  get_colored_name(ea) -> qstring

  @param ea: ea_t

`def get_colored_short_name(ea: ea_t, gtn_flags: int = 0)`

  get_colored_short_name(ea, gtn_flags=0) -> qstring

  @param ea: ea_t @param gtn_flags: int

`def get_cp_validity(*args) ‑> bool`

  get_cp_validity(kind, cp, endcp=wchar32_t(-1)) -> bool Is the given codepoint (or range) acceptable in the given context? If 'endcp' is not BADCP, it is considered to be the end of the range: [cp, endcp), and is not included in the range

  @param kind: (C++: ucdr_kind_t) enum ucdr_kind_t @param cp: (C++: wchar32_t) @param endcp: (C++: wchar32_t)

`def get_debug_name(ea_ptr: ea_t *, how: debug_name_how_t)`

  get_debug_name(ea_ptr, how) -> str

  @param ea_ptr: ea_t * @param how: enum debug_name_how_t

`def get_debug_name_ea(name: char const *)`

  get_debug_name_ea(name) -> ea_t

  @param name: char const *

`def get_debug_names(*args)`

  get_debug_names(names, ea1, ea2)

  @param names: ea_name_vec_t * @param ea1: ea_t @param ea2: ea_t

  get_debug_names(ea1, ea2, return_list=False) -> PyObject

  @param ea1: ea_t @param ea2: ea_t @param return_list: bool

`def get_demangled_name(ea: ea_t, inhibitor: int32, demform: int, gtn_flags: int = 0)`

  get_demangled_name(ea, inhibitor, demform, gtn_flags=0) -> qstring

  @param ea: ea_t @param inhibitor: int32 @param demform: int @param gtn_flags: int

`def get_ea_name(ea: ea_t, gtn_flags: int = 0)`

  get_ea_name(ea, gtn_flags=0) -> qstring Get name at the specified address.

  @param ea: (C++: ea_t) linear address @param gtn_flags: (C++: int) how exactly the name should be retrieved. combination of bits for get_ea_name() function. There is a convenience bits @return: success

`def get_long_name(ea: ea_t, gtn_flags: int = 0)`

  get_long_name(ea, gtn_flags=0) -> qstring

  @param ea: ea_t @param gtn_flags: int

`def get_mangled_name_type(name: char const *)`

  get_mangled_name_type(name) -> mangled_name_type_t

  @param name: char const *

`def get_name(ea: ea_t)`

  get_name(ea) -> qstring

  @param ea: ea_t

`def get_name_base_ea(_from: ea_t, to: ea_t)`

  get_name_base_ea(_from, to) -> ea_t Get address of the name used in the expression for the address

  @param from: (C++: ea_t) address of the operand which references to the address @param to: (C++: ea_t) the referenced address @return: address of the name used to represent the operand

`def get_name_color(_from: ea_t, ea: ea_t)`

  get_name_color(_from, ea) -> color_t Calculate flags for get_ea_name() function.

  Get name color.

  @param from: (C++: ea_t) linear address where the name is used. if not applicable, then should be BADADDR. The kernel returns a local name color if the reference is within a function, i.e. 'from' and 'ea' belong to the same function. @param ea: (C++: ea_t) linear address

`def get_name_ea(_from: ea_t, name: char const *)`

  get_name_ea(_from, name) -> ea_t Get the address of a name. This function resolves a name into an address. It can handle regular global and local names, as well as debugger names.

  @param from: (C++: ea_t) linear address where the name is used. If specified, the local labels of the function at the specified address will will be checked. BADADDR means that local names won't be consulted. @param name: (C++: const char *) any name in the program or nullptr @return: address of the name or BADADDR

`def get_name_expr(_from: ea_t, n: int, ea: ea_t, off: uval_t, flags: int = 1)`

  get_name_expr(_from, n, ea, off, flags=0x0001) -> ssize_t Convert address to name expression (name with a displacement). This function takes into account fixup information and returns a colored name expression (in the form +/- ). It also knows about structure members and arrays. If the specified address doesn't have a name, a dummy name is generated.

  @param from: (C++: ea_t) linear address of instruction operand or data referring to the name. This address will be used to get fixup information, so it should point to exact position of the operand in the instruction. @param n: (C++: int) number of referencing operand. for data items specify 0 @param ea: (C++: ea_t) address to convert to name expression @param off: (C++: uval_t) the value of name expression. this parameter is used only to check that the name expression will have the wanted value. 'off' may be equal to BADADDR but this is discouraged because it prohibits checks. @param flags: (C++: int) Name expression flags @return: < 0 if address is not valid, no segment or other failure. otherwise the length of the name expression in characters.

`def get_name_value(_from: ea_t, name: char const *)`

  get_name_value(_from, name) -> int Get value of the name. This function knows about: regular names, enums, special segments, etc.

  @param from: (C++: ea_t) linear address where the name is used if not applicable, then should be BADADDR @param name: (C++: const char *) any name in the program or nullptr @return: Name value result codes

`def get_nice_colored_name(ea: ea_t, flags: int = 0)`

  get_nice_colored_name(ea, flags=0) -> ssize_t Get a nice colored name at the specified address. Ex: * segment:sub+offset * segment:sub:local_label * segment:label * segment:address * segment:address+offset

  @param ea: (C++: ea_t) linear address @param flags: (C++: int) Nice colored name flags @return: the length of the generated name in bytes.

`def get_nlist_ea(idx: size_t)`

  get_nlist_ea(idx) -> ea_t Get address from the list at 'idx'.

  @param idx: (C++: size_t)

`def get_nlist_idx(ea: ea_t)`

  get_nlist_idx(ea) -> size_t Get index of the name in the list @warning: returns the closest match. may return idx >= size.

  @param ea: (C++: ea_t)

`def get_nlist_name(idx: size_t)`

  get_nlist_name(idx) -> char const * Get name using idx.

  @param idx: (C++: size_t)

`def get_nlist_size()`

  get_nlist_size() -> size_t Get number of names in the list.

`def get_short_name(ea: ea_t, gtn_flags: int = 0)`

  get_short_name(ea, gtn_flags=0) -> qstring

  @param ea: ea_t @param gtn_flags: int

`def get_visible_name(ea: ea_t, gtn_flags: int = 0)`

  get_visible_name(ea, gtn_flags=0) -> qstring

  @param ea: ea_t @param gtn_flags: int

`def hide_name(ea: ea_t)`

  hide_name(ea) Remove name from the list of names

  @param ea: (C++: ea_t) address of the name

`def is_ident(name: char const *)`

  is_ident(name) -> bool Is a valid name? (including ::MangleChars)

  @param name: (C++: const char *) char const *

`def is_ident_cp(cp: wchar32_t)`

  is_ident_cp(cp) -> bool Can a character appear in a name? (present in ::NameChars or ::MangleChars)

  @param cp: (C++: wchar32_t)

`def is_in_nlist(ea: ea_t)`

  is_in_nlist(ea) -> bool Is the name included into the name list?

  @param ea: (C++: ea_t)

`def is_name_defined_locally(*args) ‑> bool`

  is_name_defined_locally(pfn, name, ignore_name_def, ea1=BADADDR, ea2=BADADDR) -> bool Is the name defined locally in the specified function?

  @param pfn: (C++: func_t ) pointer to function @param name: (C++: const char ) name to check @param ignore_name_def: (C++: ignore_name_def_t) which names to ignore when checking @param ea1: (C++: ea_t) the starting address of the range inside the function (optional) @param ea2: (C++: ea_t) the ending address of the range inside the function (optional) @return: true if the name has been defined

`def is_public_name(ea: ea_t)`

  is_public_name(ea) -> bool

  @param ea: ea_t

`def is_strlit_cp(cp: wchar32_t, specific_ranges: rangeset_crefvec_t const * = None)`

  is_strlit_cp(cp, specific_ranges=None) -> bool Can a character appear in a string literal (present in ::StrlitChars) If 'specific_ranges' are specified, those will be used instead of the ones corresponding to the current culture (only if ::StrlitChars is configured to use the current culture)

  @param cp: (C++: wchar32_t) @param specific_ranges: (C++: const rangeset_crefvec_t *) rangeset_crefvec_t const *

`def is_uname(name: char const *)`

  is_uname(name) -> bool Is valid user-specified name? (valid name & !dummy prefix).

  @param name: (C++: const char *) name to test. may be nullptr. @retval 1: yes @retval 0: no

`def is_valid_cp(cp: wchar32_t, kind: nametype_t, data: void * = None)`

  is_valid_cp(cp, kind, data=None) -> bool Is the given codepoint acceptable in the given context?

  @param cp: (C++: wchar32_t) @param kind: (C++: nametype_t) enum nametype_t @param data: (C++: void *)

`def is_valid_name(name: char const *, cpuregs_permitted: bool)`

  is_valid_name(name, cpuregs_permitted) -> bool

  @param name: char const * @param cpuregs_permitted: bool

`def is_valid_typename(name: char const *)`

  is_valid_typename(name) -> bool Is valid type name?

  @param name: (C++: const char *) name to test. may be nullptr. @retval 1: yes @retval 0: no

`def is_visible_cp(cp: wchar32_t)`

  is_visible_cp(cp) -> bool Can a character be displayed in a name? (present in ::NameChars)

  @param cp: (C++: wchar32_t)

`def is_weak_name(ea: ea_t)`

  is_weak_name(ea) -> bool

  @param ea: ea_t

`def make_name_auto(ea: ea_t)`

  make_name_auto(ea) -> bool

  @param ea: ea_t

`def make_name_non_public(ea: ea_t)`

  make_name_non_public(ea)

  @param ea: ea_t

`def make_name_non_weak(ea: ea_t)`

  make_name_non_weak(ea)

  @param ea: ea_t

`def make_name_public(ea: ea_t)`

  make_name_public(ea)

  @param ea: ea_t

`def make_name_user(ea: ea_t)`

  make_name_user(ea) -> bool

  @param ea: ea_t

`def make_name_weak(ea: ea_t)`

  make_name_weak(ea)

  @param ea: ea_t

`def rebuild_nlist()`

  rebuild_nlist() Rebuild the name list.

`def reorder_dummy_names()`

  reorder_dummy_names() Renumber dummy names.

`def set_cp_validity(*args)`

  set_cp_validity(kind, cp, endcp=wchar32_t(-1), valid=True) Mark the given codepoint (or range) as acceptable or unacceptable in the given context If 'endcp' is not BADCP, it is considered to be the end of the range: [cp, endcp), and is not included in the range

  @param kind: (C++: ucdr_kind_t) enum ucdr_kind_t @param cp: (C++: wchar32_t) @param endcp: (C++: wchar32_t)

`def set_debug_name(ea: ea_t, name: char const *)`

  set_debug_name(ea, name) -> bool

  @param ea: ea_t @param name: char const *

`def set_dummy_name(_from: ea_t, ea: ea_t)`

  set_dummy_name(from, ea) -> bool Give an autogenerated (dummy) name. Autogenerated names have special prefixes (loc…).

  @param from: (C++: ea_t) linear address of the operand which references to the address @param ea: (C++: ea_t) linear address @retval 1: ok, dummy name is generated or the byte already had a name @retval 0: failure, invalid address or tail byte

`def set_name(ea: ea_t, name: char const *, flags: int = 0)`

  set_name(ea, name, flags=0) -> bool Set or delete name of an item at the specified address. An item can be anything: instruction, function, data byte, word, string, structure, etc… Include name into the list of names.

  @param ea: (C++: ea_t) linear address. do nothing if ea is not valid (return 0). tail bytes can't have names. @param name: (C++: const char *) new name. * nullptr: do nothing (return 0). * "" : delete name. * otherwise this is a new name. @param flags: (C++: int) Set name flags. If a bit is not specified, then the corresponding action is not performed and the name will retain the same bits as before calling this function. For new names, default is: non- public, non-weak, non-auto. @retval 1: ok, name is changed @retval 0: failure, a warning is displayed

`def show_name(ea: ea_t)`

  show_name(ea) Insert name to the list of names.

  @param ea: (C++: ea_t)

`def validate_name(name: char const *, type: nametype_t, flags: int = 1)`

  validate_name(name, type, flags=0x01) -> PyObject Validate a name. If SN_NOCHECK is specified, this function replaces all invalid characters in the name with SUBSTCHAR. However, it will return false if name is valid but not allowed to be an identifier (is a register name).

  @param name: (C++: qstring ) ptr to name. the name will be modified @param type: (C++: nametype_t) the type of name we want to validate @param flags: (C++: int) see SN_ @return: success

## Classes

`class NearestName (ea_names)`

  Utility class to help find the nearest name in a given ea/name dictionary

  ### Methods

  `def find(self, ea)`

    Returns a tupple (ea, name, pos) that is the nearest to the passed ea If no name is matched then None is returned

  `def update(self, ea_names)`

    Updates the ea/names map

`class ea_name_t (*args)`

  Proxy of C++ ea_name_t class.

  init(self) -> ea_name_t init(self, _ea, _name) -> ea_name_t

  @param _ea: ea_t @param _name: qstring const &

  ### Instance variables

  `var ea : ea_t`

    ea

  `var name : qstring`

    name

  `var thisown`

    The membership flag

`class ea_name_vec_t (*args)`

  Proxy of C++ qvector< ea_name_t > class.

  init(self) -> ea_name_vec_t init(self, x) -> ea_name_vec_t

  @param x: qvector< ea_name_t > const &

  ### Instance variables

  `var thisown`

    The membership flag

  ### Methods

  `def at(self, _idx: size_t)`

    at(self, _idx) -> ea_name_t

    @param _idx: size_t

  `def back(self)`
  `def begin(self, *args)`

    begin(self) -> ea_name_t

  `def capacity(self)`

    capacity(self) -> size_t

  `def clear(self)`

    clear(self)

  `def empty(self) ‑> bool`

    empty(self) -> bool

  `def end(self, *args)`

    end(self) -> ea_name_t

  `def erase(self, *args)`

    erase(self, it) -> ea_name_t

    @param it: qvector< ea_name_t >::iterator

    erase(self, first, last) -> ea_name_t

    @param first: qvector< ea_name_t >::iterator @param last: qvector< ea_name_t >::iterator

  `def extract(self)`

    extract(self) -> ea_name_t

  `def front(self)`
  `def grow(self, *args)`

    grow(self, x=ea_name_t())

    @param x: ea_name_t const &

  `def inject(self, s: ea_name_t, len: size_t)`

    inject(self, s, len)

    @param s: ea_name_t * @param len: size_t

  `def insert(self, it: ea_name_t, x: ea_name_t)`

    insert(self, it, x) -> ea_name_t

    @param it: qvector< ea_name_t >::iterator @param x: ea_name_t const &

  `def pop_back(self)`

    pop_back(self)

  `def push_back(self, *args)`

    push_back(self, x)

    @param x: ea_name_t const &

    push_back(self) -> ea_name_t

  `def qclear(self)`

    qclear(self)

  `def reserve(self, cnt: size_t)`

    reserve(self, cnt)

    @param cnt: size_t

  `def resize(self, *args)`

    resize(self, _newsize, x)

    @param _newsize: size_t @param x: ea_name_t const &

    resize(self, _newsize)

    @param _newsize: size_t

  `def size(self)`

    size(self) -> size_t

  `def swap(self, r: ea_name_vec_t)`

    swap(self, r)

    @param r: qvector< ea_name_t > &

  `def truncate(self)`

    truncate(self)