IDA SDK
Classes | Functions | Macros | Typedefs | Enumerations | Variables
name.hpp File Reference

Detailed Description

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) can not have names.

Classes

struct  getname_info_t
 Additional information for get_ea_name() function. More...
 
struct  ea_name_t
 ea, name pair More...
 

Functions

idaman bool ida_export set_name (ea_t ea, const char *name, int flags=0)
 Set or delete name of an item at the specified address. More...
 
bool force_name (ea_t ea, const char *name, int flags=0)
 
idaman bool ida_export set_dummy_name (ea_t from, ea_t ea)
 Give an autogenerated (dummy) name. More...
 
idaman bool ida_export validate_name (qstring *name, nametype_t type, int flags=0)
 Validate a name. More...
 
idaman bool ida_export is_valid_cp (wchar32_t cp, nametype_t kind, void *data=NULL)
 Is the given codepoint acceptable in the given context?
 
idaman void ida_export set_cp_validity (ucdr_kind_t kind, wchar32_t cp, wchar32_t endcp=BADCP, bool 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 (wchar32_t cp)
 Can a character appear in a name? (present in ::NameChars or ::MangleChars)
 
bool is_strlit_cp (wchar32_t cp, const rangeset_crefvec_t *specific_ranges=NULL)
 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 (wchar32_t cp)
 Can a character be displayed in a name? (present in ::NameChars)
 
idaman bool ida_export is_ident (const char *name)
 Is a valid name? (including ::MangleChars)
 
idaman bool ida_export is_uname (const char *name)
 Is valid user-specified name? (valid name & !dummy prefix). More...
 
idaman bool ida_export is_valid_typename (const char *name)
 Is valid type name? More...
 
idaman ea_t ida_export dummy_name_ea (const char *name)
 Is dummy name? More...
 
idaman ssize_t ida_export extract_name (qstring *out, const char *line, int x)
 Extract a name or address from the specified string. More...
 
idaman void ida_export hide_name (ea_t ea)
 Remove name from the list of names. More...
 
idaman void ida_export show_name (ea_t ea)
 Insert name to the list of names.
 
idaman ea_t ida_export get_name_ea (ea_t from, const char *name)
 Get address of the name. More...
 
idaman ea_t ida_export get_name_base_ea (ea_t from, ea_t to)
 Get address of the name used in the expression for the address. More...
 
idaman int ida_export get_name_value (uval_t *value, ea_t from, const char *name)
 Get value of the name. More...
 
idaman ssize_t ida_export get_ea_name (qstring *out, ea_t ea, int gtn_flags=0, getname_info_t *gtni=NULL)
 Get name at the specified address. More...
 
ssize_t get_name (qstring *out, ea_t ea, int gtn_flags=0)
 
ssize_t idaapi get_visible_name (qstring *out, ea_t ea, int gtn_flags=0)
 
ssize_t idaapi get_colored_name (qstring *out, ea_t ea, int gtn_flags=0)
 
ssize_t idaapi get_short_name (qstring *out, ea_t ea, int gtn_flags=0)
 
ssize_t idaapi get_long_name (qstring *out, ea_t ea, int gtn_flags=0)
 
ssize_t idaapi get_colored_short_name (qstring *out, ea_t ea, int gtn_flags=0)
 
ssize_t idaapi get_colored_long_name (qstring *out, ea_t ea, int gtn_flags=0)
 
ssize_t idaapi get_demangled_name (qstring *out, ea_t ea, int32 inhibitor, int demform, int gtn_flags=0)
 
ssize_t idaapi get_colored_demangled_name (qstring *out, ea_t ea, int32 inhibitor, int demform, int gtn_flags=0)
 
qstring get_name (ea_t ea, int gtn_flags=0)
 
qstring get_visible_name (ea_t ea, int gtn_flags=0)
 
qstring idaapi get_colored_name (ea_t ea, int gtn_flags=0)
 
qstring idaapi get_short_name (ea_t ea, int gtn_flags=0)
 
qstring idaapi get_long_name (ea_t ea, int gtn_flags=0)
 
qstring idaapi get_colored_short_name (ea_t ea, int gtn_flags=0)
 
qstring idaapi get_colored_long_name (ea_t ea, int gtn_flags=0)
 
qstring idaapi get_demangled_name (ea_t ea, int32 inhibitor, int demform, int gtn_flags=0)
 
qstring idaapi get_colored_demangled_name (ea_t ea, int32 inhibitor, int demform, int gtn_flags=0)
 
idaman color_t ida_export get_name_color (ea_t from, ea_t ea)
 Calculate flags for get_ea_name() function. More...
 
idaman ssize_t ida_export get_name_expr (qstring *out, ea_t from, int n, ea_t ea, uval_t off, int flags=GETN_APPZERO)
 Convert address to name expression (name with a displacement). More...
 
idaman ssize_t ida_export get_nice_colored_name (qstring *buf, ea_t ea, int flags=0)
 Get a nice colored name at the specified address. More...
 
idaman flags_t ida_export append_struct_fields (qstring *out, adiff_t *disp, int n, const tid_t *path, int plen, flags_t flags, adiff_t delta, bool appzero)
 Append names of struct fields to a name if the name is a struct name. More...
 
idaman int ida_export get_struct_operand (adiff_t *disp, adiff_t *delta, tid_t *path, ea_t ea, int n)
 Get offset within a structure if the operand refers to structure. More...
 
idaman void ida_export reorder_dummy_names (void)
 Renumber dummy names.
 
idaman int32 ida_export demangle_name (qstring *out, const char *name, uint32 disable_mask, demreq_type_t demreq=DQT_FULL)
 Demangle a name. More...
 
qstring idaapi demangle_name (const char *name, uint32 disable_mask, demreq_type_t demreq=DQT_FULL)
 Demangle a name.
 
int32 detect_compiler_using_demangler (const char *name)
 
idaman bool ida_export is_name_defined_locally (func_t *pfn, const char *name, ignore_name_def_t ignore_name_def, ea_t ea1=BADADDR, ea_t ea2=BADADDR)
 Is the name defined locally in the specified function? More...
 
idaman bool ida_export cleanup_name (qstring *out, ea_t ea, const char *name, uint32 flags=0)
 
Delete a name of a program item
Parameters
ealinear address
Return values
1ok, name is deleted
0failure, invalid address
bool del_global_name (ea_t ea)
 
bool del_local_name (ea_t ea)
 
Set/Clear bit in flags for 'autogenerated but meaningful name'

This bit affects value of has_user_name(), has_auto_name() functions.

Parameters
ealinear address
Return values
1ok
0no meaningful name is present at the specified address
idaman bool ida_export make_name_auto (ea_t ea)
 
idaman bool ida_export make_name_user (ea_t ea)
 
Work with publicness of a name
idaman bool ida_export is_public_name (ea_t ea)
 
idaman void ida_export make_name_public (ea_t ea)
 
idaman void ida_export make_name_non_public (ea_t ea)
 
Work with weak names.
idaman bool ida_export is_weak_name (ea_t ea)
 
idaman void ida_export make_name_weak (ea_t ea)
 
idaman void ida_export make_name_non_weak (ea_t ea)
 
Work with the list of names
idaman size_t ida_export get_nlist_size (void)
 Get number of names in the list.
 
idaman size_t ida_export get_nlist_idx (ea_t ea)
 Get index of the name in the list. More...
 
idaman bool ida_export is_in_nlist (ea_t ea)
 Is name included into names list?
 
idaman ea_t ida_export get_nlist_ea (size_t idx)
 Get address from the list at 'idx'.
 
idaman const char *ida_export get_nlist_name (size_t idx)
 Get name using idx.
 
idaman void ida_export rebuild_nlist (void)
 Rebuild names list.
 
Debug names

Debug names exist during the debugging session.

The kernel does not verify them for anything and happily accepts any string as a name.

idaman int ida_export set_debug_names (const ea_t *addrs, const char *const *names, int qty)
 
idaman bool ida_export set_debug_name (ea_t ea, const char *name)
 
idaman ssize_t ida_export get_debug_name (qstring *out, ea_t *ea_ptr, debug_name_how_t how)
 
idaman void ida_export del_debug_names (ea_t ea1, ea_t ea2)
 
idaman ea_t ida_export get_debug_name_ea (const char *name)
 
idaman void ida_export get_debug_names (ea_name_vec_t *names, ea_t ea1, ea_t ea2)
 

Macros

#define MAXNAMELEN   512
 Maximum length of a name in IDA (with the trailing zero)
 
#define FUNC_IMPORT_PREFIX   "__imp_"
 Name prefix used by IDA for the imported functions.
 
#define SN_CHECK   0x00
 
#define SN_NOCHECK   0x01
 Don't fail if the name contains invalid characters. More...
 
#define SN_PUBLIC   0x02
 if set, make name public
 
#define SN_NON_PUBLIC   0x04
 if set, make name non-public
 
#define SN_WEAK   0x08
 if set, make name weak
 
#define SN_NON_WEAK   0x10
 if set, make name non-weak
 
#define SN_AUTO   0x20
 if set, make name autogenerated
 
#define SN_NON_AUTO   0x40
 if set, make name non-autogenerated
 
#define SN_NOLIST   0x80
 if set, exclude name from the list. More...
 
#define SN_NOWARN   0x100
 don't display a warning if failed
 
#define SN_LOCAL   0x200
 create local name. More...
 
#define SN_IDBENC   0x400
 the name is given in the IDB encoding; More...
 
#define SN_FORCE   0x800
 if the specified name is already present More...
 
#define NT_NONE   0
 name doesn't exist or has no value
 
#define NT_BYTE   1
 name is byte name (regular name)
 
#define NT_LOCAL   2
 name is local label
 
#define NT_STKVAR   3
 name is stack variable name
 
#define NT_ENUM   4
 name is symbolic constant
 
#define NT_ABS   5
 name is absolute symbol (SEG_ABSSYM)
 
#define NT_SEG   6
 name is segment or segment register name
 
#define NT_STROFF   7
 name is structure member
 
#define NT_BMASK   8
 name is a bit group mask name
 
#define NT_REGVAR   9
 name is a renamed register (*value is idx into pfn->regvars)
 
#define GN_VISIBLE   0x0001
 replace forbidden characters by SUBSTCHAR
 
#define GN_COLORED   0x0002
 return colored name
 
#define GN_DEMANGLED   0x0004
 return demangled name
 
#define GN_STRICT   0x0008
 fail if can not demangle
 
#define GN_SHORT   0x0010
 use short form of demangled name
 
#define GN_LONG   0x0020
 use long form of demangled name
 
#define GN_LOCAL   0x0040
 try to get local name first; if failed, get global
 
#define GN_ISRET   0x0080
 for dummy names: use retloc
 
#define GN_NOT_ISRET   0x0100
 for dummy names: do not use retloc
 
#define GETN_APPZERO   0x0001
 meaningful only if the name refers to a structure. More...
 
#define GETN_NOFIXUP   0x0002
 ignore the fixup information when producing the name
 
#define GETN_NODUMMY   0x0004
 do not create a new dummy name but pretend it exists
 
#define GNCN_NOSEG   0x0001
 ignore the segment prefix when producing the name
 
#define GNCN_NOCOLOR   0x0002
 generate an uncolored name
 
#define GNCN_NOLABEL   0x0004
 don't generate labels
 
#define GNCN_NOFUNC   0x0008
 don't generate funcname+... expressions
 
#define GNCN_SEG_FUNC   0x0010
 generate both segment and function names (default is to omit segment name if a function name is present)
 
#define GNCN_SEGNUM   0x0020
 segment part is displayed as a hex number
 
#define GNCN_REQFUNC   0x0040
 return 0 if the address does not belong to a function
 
#define GNCN_REQNAME   0x0080
 return 0 if the address can only be represented as a hex number
 
#define GNCN_NODBGNM   0x0100
 don't use debug names
 
#define GNCN_PREFDBG   0x0200
 if using debug names, prefer debug names over function names
 
#define CN_KEEP_TRAILING__DIGITS   0x01
 

Typedefs

typedef uchar color_t
 
typedef qvector< ea_name_tea_name_vec_t
 vector of ea,name pairs
 
typedef int ignore_name_def_t
 What name types to ignore.
 

Enumerations

enum  ucdr_kind_t { URK_NameChars = 0x1, URK_MangleChars = 0x2, URK_StrlitChars = 0x4, URK_TypeNameChars = 0x8 }
 
enum  nametype_t {
  VNT_IDENT = URK_NameChars|URK_MangleChars, VNT_TYPE = URK_TypeNameChars, VNT_UDTMEM = URK_NameChars, VNT_STRLIT = URK_StrlitChars,
  VNT_VISIBLE = VNT_UDTMEM
}
 
enum  debug_name_how_t { DEBNAME_EXACT, DEBNAME_LOWER, DEBNAME_UPPER, DEBNAME_NICE }
 Specify strategy for retrieving debug names. More...
 
enum  demreq_type_t {
  DQT_NPURGED_8 = -8, DQT_NPURGED_4 = -4, DQT_NPURGED_2 = -2, DQT_COMPILER = 0,
  DQT_NAME_TYPE = 1, DQT_FULL = 2
}
 

Variables

const ignore_name_def_t ignore_none = 0
 
const ignore_name_def_t ignore_regvar = 1
 
const ignore_name_def_t ignore_llabel = 2
 
const ignore_name_def_t ignore_stkvar = 3
 
const ignore_name_def_t ignore_glabel = 4
 

Enumeration Type Documentation

Specify strategy for retrieving debug names.

Enumerator
DEBNAME_EXACT 

find a name at exactly the specified address

DEBNAME_LOWER 

find a name with the address >= the specified address

DEBNAME_UPPER 

find a name with the address > the specified address

DEBNAME_NICE 

find a name with the address <= the specified address

Function Documentation

idaman bool ida_export set_name ( ea_t  ea,
const char *  name,
int  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
ealinear address. do nothing if ea is not valid (return 0). tail bytes can't have names.
namenew name.
  • NULL: do nothing (return 0).
  • "" : delete name.
  • otherwise this is a new name.
flagsSet 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.
Return values
1ok, name is changed
0failure, a warning is displayed
idaman bool ida_export set_dummy_name ( ea_t  from,
ea_t  ea 
)

Give an autogenerated (dummy) name.

Autogenerated names have special prefixes (loc_...).

Parameters
fromlinear address of the operand which references to the address
ealinear address
Return values
1ok, dummy name is generated or the byte already had a name
0failure, invalid address or tail byte
idaman bool ida_export validate_name ( qstring name,
nametype_t  type,
int  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
[in,out]nameptr to name. the name will be modified
typethe type of name we want to validate
flagssee SN_* . Only SN_IDBENC is currently considered
Returns
success
idaman bool ida_export is_uname ( const char *  name)

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

Parameters
namename to test. may be NULL.
Return values
1yes
0no
idaman bool ida_export is_valid_typename ( const char *  name)

Is valid type name?

Parameters
namename to test. may be NULL.
Return values
1yes
0no
idaman ea_t ida_export dummy_name_ea ( const char *  name)

Is dummy name?

Parameters
namename to test. may be NULL.
Returns
BADADDR if not, otherwise the address denoted by the name
idaman ssize_t ida_export extract_name ( qstring out,
const char *  line,
int  x 
)

Extract a name or address from the specified string.

Parameters
[out]outoutput buffer for the identifier
lineinput string
xx coordinate of cursor
Returns
-1 if can not extract. otherwise length of the name
idaman void ida_export hide_name ( ea_t  ea)

Remove name from the list of names.

Parameters
eaaddress of the name
idaman ea_t ida_export get_name_ea ( ea_t  from,
const char *  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
fromlinear address where the name is used. if not applicable, then should be BADADDR.
nameany name in the program or NULL
Returns
address of the name or BADADDR
idaman ea_t ida_export get_name_base_ea ( ea_t  from,
ea_t  to 
)

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

Parameters
fromaddress of the operand which references to the address
tothe referenced address
Returns
address of the name used to represent the operand
idaman int ida_export get_name_value ( uval_t value,
ea_t  from,
const char *  name 
)

Get value of the name.

This function knows about: regular names, enums, special segments, etc.

Parameters
[out]valuepointer to variable with answer
fromlinear address where the name is used if not applicable, then should be BADADDR
nameany name in the program or NULL
Returns
Name value result codes
idaman ssize_t ida_export get_ea_name ( qstring out,
ea_t  ea,
int  gtn_flags = 0,
getname_info_t gtni = NULL 
)

Get name at the specified address.

Parameters
[out]outbuffer to hold the name
ealinear address
gtn_flagshow exactly the name should be retrieved. combination of bits for get_ea_name() function. There is a convenience bits
gtniadditional information for name demangling Please use the convenience functions declared below instead of calling get_ea_name directly.
Returns
success
idaman color_t ida_export get_name_color ( ea_t  from,
ea_t  ea 
)

Calculate flags for get_ea_name() function.

Get name color.

Parameters
fromlinear 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.
ealinear address
idaman ssize_t ida_export get_name_expr ( qstring out,
ea_t  from,
int  n,
ea_t  ea,
uval_t  off,
int  flags = GETN_APPZERO 
)

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
[out]outoutput buffer for the name
fromlinear 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.
nnumber of referencing operand. for data items specify 0
eaaddress to convert to name expression
offthe 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.
flagsName expression flags
Returns
< 0 if address is not valid, no segment or other failure. otherwise the length of the name expression in characters.
idaman ssize_t ida_export get_nice_colored_name ( qstring buf,
ea_t  ea,
int  flags = 0 
)

Get a nice colored name at the specified address.

Ex:

  • segment:sub+offset
  • segment:sub:local_label
  • segment:label
  • segment:address
  • segment:address+offset
    Parameters
    [out]bufbuffer to hold the name
    ealinear address
    flagsNice colored name flags
    Returns
    the length of the generated name in bytes.
idaman flags_t ida_export append_struct_fields ( qstring out,
adiff_t disp,
int  n,
const tid_t path,
int  plen,
flags_t  flags,
adiff_t  delta,
bool  appzero 
)

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

Parameters
outpointer to the output buffer
dispdisplacement from the name
nnumber of operand n which the name appears
pathpath 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).
plensize of path array
flagsthe input flags. they will be returned if the struct cannot be found.
deltadelta to add to displacement
appzeroshould append a struct field name if the displacement is zero?
Returns
flags of the innermost struct member or the input flags
idaman int ida_export get_struct_operand ( adiff_t disp,
adiff_t delta,
tid_t path,
ea_t  ea,
int  n 
)

Get offset within a structure if the operand refers to structure.

Ex:

mov ax, somedata.field5-2 (before it was max ax, 3) 

for this instruction, op #1 the function will return

  • disp: the value of 'field5', i.e. 5
  • delta: -2
  • path: the existing path if any
    Parameters
    disppointer to displacement (answer will be here)
    deltapointer to displacement delta (answer will be here)
    pathexisting strpath (if any)
    ealinear address of instruction/data
    nnumber of operand
    Returns
    if success, then length of path + 1. if failed, then 0.
idaman size_t ida_export get_nlist_idx ( ea_t  ea)

Get index of the name in the list.

Warning
returns the closest match. may return idx >= size.
idaman int32 ida_export demangle_name ( qstring out,
const char *  name,
uint32  disable_mask,
demreq_type_t  demreq = DQT_FULL 
)

Demangle a name.

Parameters
outoutput buffer
namename to demangle
disable_maskbits to inhibit parts of demangled name (see MNG_). by the M_COMPILER bits a specific compiler can be selected (see MT_).
Returns
ME_... or MT__ bitmasks from demangle.hpp
idaman bool ida_export is_name_defined_locally ( func_t pfn,
const char *  name,
ignore_name_def_t  ignore_name_def,
ea_t  ea1 = BADADDR,
ea_t  ea2 = BADADDR 
)

Is the name defined locally in the specified function?

Parameters
pfnpointer to function
namename to check
ignore_name_defwhich names to ignore when checking
ea1the starting address of the range inside the function (optional)
ea2the ending address of the range inside the function (optional)
Returns
true if the name has been defined