Module ida_name
[frames] | no frames]

Module ida_name

IDA Plugin SDK API wrapper: name

Classes
  ea_name_vec_t
Proxy of C++ qvector<(ea_name_t)> class
  ea_name_t
Proxy of C++ ea_name_t class
  NearestName
Utility class to help find the nearest name in a given ea/name dictionary
Functions
qstring
get_name(ea)
qstring
get_colored_name(ea)
bool
set_name(ea, name, flags=0)
Set or delete name of an item at the specified address.
bool
force_name(ea, name, flags=0)
bool
del_global_name(ea)
bool
del_local_name(ea)
bool
set_dummy_name(_from, ea)
Give an autogenerated (dummy) name.
bool
make_name_auto(ea)
bool
make_name_user(ea)
bool
is_valid_cp(cp, kind, data=None)
Is the given codepoint acceptable in the given context?
 
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
bool
is_ident_cp(cp)
Can a character appear in a name? (present in ::NameChars or ::MangleChars)
bool
is_strlit_cp(cp, specific_ranges=None)
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)
bool
is_visible_cp(cp)
Can a character be displayed in a name? (present in ::NameChars)
bool
is_ident(name)
Is a valid name? (including ::MangleChars)
bool
is_uname(name)
Is valid user-specified name? (valid name & !dummy prefix).
bool
is_valid_typename(name)
Is valid type name?
ssize_t
extract_name(line, x)
Extract a name or address from the specified string.
 
hide_name(ea)
Remove name from the list of names
 
show_name(ea)
Insert name to the list of names.
ea_t
get_name_ea(_from, name)
Get address of the name.
ea_t
get_name_base_ea(_from, to)
Get address of the name used in the expression for the address
int
get_name_value(_from, name)
Get value of the name.
qstring
get_visible_name(ea, gtn_flags=0)
qstring
get_short_name(ea, gtn_flags=0)
qstring
get_long_name(ea, gtn_flags=0)
qstring
get_colored_short_name(ea, gtn_flags=0)
qstring
get_colored_long_name(ea, gtn_flags=0)
qstring
get_demangled_name(ea, inhibitor, demform, gtn_flags=0)
qstring
get_colored_demangled_name(ea, inhibitor, demform, gtn_flags=0)
color_t
get_name_color(_from, ea)
Calculate flags for 'get_ea_name()' function.
ssize_t
get_name_expr(_from, n, ea, off, flags=0x0001)
Convert address to name expression (name with a displacement).
ssize_t
get_nice_colored_name(ea, flags=0)
Get a nice colored name at the specified address.
flags_t
append_struct_fields(disp, n, path, flags, delta, appzero)
Append names of struct fields to a name if the name is a struct name.
bool
is_public_name(ea)
 
make_name_public(ea)
 
make_name_non_public(ea)
bool
is_weak_name(ea)
 
make_name_weak(ea)
 
make_name_non_weak(ea)
size_t
get_nlist_size()
Get number of names in the list.
size_t
get_nlist_idx(ea)
Get index of the name in the listreturns the closest match.
bool
is_in_nlist(ea)
Is name included into names list?
ea_t
get_nlist_ea(idx)
Get address from the list at 'idx'.
char const *
get_nlist_name(idx)
Get name using idx.
 
rebuild_nlist()
Rebuild names list.
 
reorder_dummy_names()
Renumber dummy names.
bool
set_debug_name(ea, name)
ssize_t
get_debug_name(ea_ptr, how)
 
del_debug_names(ea1, ea2)
ea_t
get_debug_name_ea(name)
int32
demangle_name(name, disable_mask, demreq=DQT_FULL)
Demangle a name.
bool
is_name_defined_locally(pfn, name, ignore_name_def, ea1=BADADDR, ea2=BADADDR)
Is the name defined locally in the specified function?
bool
cleanup_name(ea, name, flags=0)
 
get_debug_names(names, ea1, ea2)
get_debug_names(ea1, ea2, return_list=False) -> PyObject *
qstring
get_ea_name(ea, gtn_flags=0)
Get name at the specified address.
PyObject *
validate_name(name, type, flags=0)
Validate a name.
 
calc_gtn_flags(fromaddr, ea)
Calculate flags for get_ea_name() function
Variables
  MAXNAMELEN = 512
Maximum length of a name in IDA (with the trailing zero)
  FUNC_IMPORT_PREFIX = '__imp_'
Name prefix used by IDA for the imported functions.
  SN_CHECK = 0
  SN_NOCHECK = 1
Don't fail if the name contains invalid characters.
  SN_PUBLIC = 2
if set, make name public
  SN_NON_PUBLIC = 4
if set, make name non-public
  SN_WEAK = 8
if set, make name weak
  SN_NON_WEAK = 16
if set, make name non-weak
  SN_AUTO = 32
if set, make name autogenerated
  SN_NON_AUTO = 64
if set, make name non-autogenerated
  SN_NOLIST = 128
if set, exclude name from the list.
  SN_NOWARN = 256
don't display a warning if failed
  SN_LOCAL = 512
create local name.
  SN_IDBENC = 1024
the name is given in the IDB encoding; non-ASCII bytes will be decoded accordingly.
  SN_FORCE = 2048
if the specified name is already present in the database, try variations with a numerical suffix like "_123"
  SN_NODUMMY = 4096
automatically prepend the name with '_' if it begins with a dummy suffix such as 'sub_'.
  SN_DELTAIL = 8192
delete the hindering item
  URK_NameChars = 1
  URK_MangleChars = 2
  URK_StrlitChars = 4
  URK_TypeNameChars = 8
  VNT_IDENT = 3
  VNT_TYPE = 8
  VNT_UDTMEM = 1
  VNT_STRLIT = 4
  VNT_VISIBLE = 1
  NT_NONE = 0
name doesn't exist or has no value
  NT_BYTE = 1
name is byte name (regular name)
  NT_LOCAL = 2
name is local label
  NT_STKVAR = 3
name is stack variable name
  NT_ENUM = 4
name is symbolic constant
  NT_ABS = 5
name is absolute symbol ( 'SEG_ABSSYM' )
  NT_SEG = 6
name is segment or segment register name
  NT_STROFF = 7
name is structure member
  NT_BMASK = 8
name is a bit group mask name
  NT_REGVAR = 9
name is a renamed register (*value is idx into pfn->regvars)
  GN_VISIBLE = 1
replace forbidden characters by SUBSTCHAR
  GN_COLORED = 2
return colored name
  GN_DEMANGLED = 4
return demangled name
  GN_STRICT = 8
fail if cannot demangle
  GN_SHORT = 16
use short form of demangled name
  GN_LONG = 32
use long form of demangled name
  GN_LOCAL = 64
try to get local name first; if failed, get global
  GN_ISRET = 128
for dummy names: use retloc
  GN_NOT_ISRET = 256
for dummy names: do not use retloc
  GN_NOT_DUMMY = 512
do not return a dummy name
  GETN_APPZERO = 1
append a struct field name if the field offset is zero?
  GETN_NOFIXUP = 2
ignore the fixup information when producing the name
  GETN_NODUMMY = 4
do not create a new dummy name but pretend it exists
  GNCN_NOSEG = 1
ignore the segment prefix when producing the name
  GNCN_NOCOLOR = 2
generate an uncolored name
  GNCN_NOLABEL = 4
don't generate labels
  GNCN_NOFUNC = 8
don't generate funcname+...
  GNCN_SEG_FUNC = 16
generate both segment and function names (default is to omit segment name if a function name is present)
  GNCN_SEGNUM = 32
segment part is displayed as a hex number
  GNCN_REQFUNC = 64
return 0 if the address does not belong to a function
  GNCN_REQNAME = 128
return 0 if the address can only be represented as a hex number
  GNCN_NODBGNM = 256
don't use debug names
  GNCN_PREFDBG = 512
if using debug names, prefer debug names over function names
  DEBNAME_EXACT = 0
  DEBNAME_LOWER = 1
  DEBNAME_UPPER = 2
  DEBNAME_NICE = 3
  DQT_NPURGED_8 = -8
  DQT_NPURGED_4 = -4
  DQT_NPURGED_2 = -2
  DQT_COMPILER = 0
  DQT_NAME_TYPE = 1
  DQT_FULL = 2
  CN_KEEP_TRAILING__DIGITS = 1
  cvar = _ida_name.cvar
  ignore_none = 0
  ignore_regvar = 1
  ignore_llabel = 2
  ignore_stkvar = 3
  ignore_glabel = 4
  __package__ = None
Function Details

set_name(ea, name, flags=0)

 

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.

Parameters:
  • ea - linear address. do nothing if ea is not valid (return 0). tail bytes can't have names. (C++: ea_t)
  • name - new name. NULL: do nothing (return 0). "" : delete name. otherwise this is a new name. (C++: const char *)
  • flags - 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. (C++: int)
Returns: bool

set_dummy_name(_from, ea)

 

Give an autogenerated (dummy) name. Autogenerated names have special prefixes (loc_...).

Parameters:
  • _from - linear address of the operand which references to the address (C++: ea_t)
  • ea - linear address (C++: ea_t)
Returns: bool

is_valid_cp(cp, kind, data=None)

 

Is the given codepoint acceptable in the given context?

Parameters:
  • cp, (C++ - wchar32_t)
  • kind, (C++ - nametype_t)
  • data, (C++ - void *)
Returns: bool

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

Parameters:
  • kind, (C++ - ucdr_kind_t)
  • cp, (C++ - wchar32_t)
  • endcp, (C++ - wchar32_t)
  • valid, (C++ - bool)

is_ident_cp(cp)

 

Can a character appear in a name? (present in ::NameChars or ::MangleChars)

Parameters:
  • cp, (C++ - wchar32_t)
Returns: bool

is_strlit_cp(cp, specific_ranges=None)

 

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)

Parameters:
  • cp, (C++ - wchar32_t)
  • specific_ranges, (C++ - const rangeset_crefvec_t *)
Returns: bool

is_visible_cp(cp)

 

Can a character be displayed in a name? (present in ::NameChars)

Parameters:
  • cp, (C++ - wchar32_t)
Returns: bool

is_ident(name)

 

Is a valid name? (including ::MangleChars)

Parameters:
  • name, (C++ - const char *)
Returns: bool

is_uname(name)

 

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

Parameters:
  • name - name to test. may be NULL. (C++: const char *)
Returns: bool

is_valid_typename(name)

 

Is valid type name?

Parameters:
  • name - name to test. may be NULL. (C++: const char *)
Returns: bool

extract_name(line, x)

 

Extract a name or address from the specified string.

Parameters:
  • line - input string (C++: const char *)
  • x - x coordinate of cursor (C++: int)
Returns: ssize_t
-1 if cannot extract. otherwise length of the name

hide_name(ea)

 

Remove name from the list of names

Parameters:
  • ea - address of the name (C++: ea_t)

show_name(ea)

 

Insert name to the list of names.

Parameters:
  • ea, (C++ - ea_t)

get_name_ea(_from, name)

 

Get address of the name. Dummy names (like byte_xxxx where xxxx are hex digits) are parsed by this function to obtain the address. The database is not consulted for them. This function works only with regular names.

Parameters:
  • _from - linear address where the name is used. if not applicable, then should be BADADDR . (C++: ea_t)
  • name - any name in the program or NULL (C++: const char *)
Returns: ea_t
address of the name or BADADDR

get_name_base_ea(_from, to)

 

Get address of the name used in the expression for the address

Parameters:
  • _from - address of the operand which references to the address (C++: ea_t)
  • to - the referenced address (C++: ea_t)
Returns: ea_t
address of the name used to represent the operand

get_name_value(_from, name)

 

Get value of the name. This function knows about: regular names, enums, special segments, etc.

Parameters:
  • _from - linear address where the name is used if not applicable, then should be BADADDR (C++: ea_t)
  • name - any name in the program or NULL (C++: const char *)
Returns: int
Name value result codes

get_name_color(_from, ea)

 

Calculate flags for 'get_ea_name()' function.

Get name color.

Parameters:
  • _from - 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. (C++: ea_t)
  • ea - linear address (C++: ea_t)
Returns: color_t

get_name_expr(_from, n, ea, off, flags=0x0001)

 

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 <name> +/- <offset>). It also knows about structure members and arrays. If the specified address doesn't have a name, a dummy name is generated.

Parameters:
  • _from - 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. (C++: ea_t)
  • n - number of referencing operand. for data items specify 0 (C++: int)
  • ea - address to convert to name expression (C++: ea_t)
  • off - 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. (C++: uval_t)
  • flags - Name expression flags (C++: int)
Returns: ssize_t
< 0 if address is not valid, no segment or other failure. otherwise the length of the name expression in characters.

get_nice_colored_name(ea, flags=0)

 

Get a nice colored name at the specified address. Ex:segment:sub+offse tsegment:sub:local_labelsegment:labelsegment:addresssegment:address+of fset

Parameters:
  • ea, (C++ - ea_t)
  • flags, (C++ - int)
Returns: ssize_t
the length of the generated name in bytes.

append_struct_fields(disp, n, path, flags, delta, appzero)

 

Append names of struct fields to a name if the name is a struct name.

Parameters:
  • disp - displacement from the name (C++: adiff_t *)
  • n - number of operand n which the name appears (C++: int)
  • path - 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). (C++: const tid_t *)
  • flags - the input flags. they will be returned if the struct cannot be found. (C++: flags_t)
  • delta - delta to add to displacement (C++: adiff_t)
  • appzero - should append a struct field name if the displacement is zero? (C++: bool)
Returns: flags_t
flags of the innermost struct member or the input flags

get_nlist_idx(ea)

 

Get index of the name in the listreturns the closest match. may return idx >= size.

Parameters:
  • ea, (C++ - ea_t)
Returns: size_t

is_in_nlist(ea)

 

Is name included into names list?

Parameters:
  • ea, (C++ - ea_t)
Returns: bool

get_nlist_ea(idx)

 

Get address from the list at 'idx'.

Parameters:
  • idx, (C++ - size_t)
Returns: ea_t

get_nlist_name(idx)

 

Get name using idx.

Parameters:
  • idx, (C++ - size_t)
Returns: char const *

demangle_name(name, disable_mask, demreq=DQT_FULL)

 

Demangle a name.

Parameters:
  • name - name to demangle (C++: const char *)
  • disable_mask - bits to inhibit parts of demangled name (see MNG_). by the M_COMPILER bits a specific compiler can be selected (see MT_). (C++: uint32)
  • demreq, (C++ - demreq_type_t)
Returns: int32
ME_... or MT__ bitmasks from demangle.hpp

is_name_defined_locally(pfn, name, ignore_name_def, ea1=BADADDR, ea2=BADADDR)

 

Is the name defined locally in the specified function?

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

get_ea_name(ea, gtn_flags=0)

 

Get name at the specified address.

Parameters:
  • ea - linear address (C++: ea_t)
  • gtn_flags - how exactly the name should be retrieved. combination of bits for get_ea_name() function. There is a convenience bits (C++: int)
Returns: qstring
success

validate_name(name, type, flags=0)

 

Validate a name. 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).

Parameters:
  • name - ptr to name. the name will be modified (C++: qstring *)
  • type - the type of name we want to validate (C++: nametype_t)
  • flags - see SN_* . Only SN_IDBENC is currently considered (C++: int)
Returns: PyObject *
success

calc_gtn_flags(fromaddr, ea)

 

Calculate flags for get_ea_name() function

Parameters:
  • fromaddr - the referring address. May be BADADDR.
  • ea - linear address
Returns:
flags

Variables Details

SN_NOCHECK

Don't fail if the name contains invalid characters. If this bit is clear, all invalid chars (those !is_ident_cp()) will be replaced by SUBSTCHAR List of valid characters is defined in ida.cfg

Value:
1

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).

Value:
128

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.

Value:
512

SN_IDBENC

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

Value:
1024

SN_NODUMMY

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

Value:
4096

SN_DELTAIL

delete the hindering item

if name cannot be set because of a tail byte,

Value:
8192

GETN_APPZERO

append a struct field name if the field offset is zero?

meaningful only if the name refers to a structure.

Value:
1

GNCN_NOFUNC

don't generate funcname+... expressions

Value:
8