| 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) cannot 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=nullptr)
| 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.
idaman bool ida_export | get_cp_validity (ucdr_kind_t kind, wchar32_t cp, wchar32_t endcp=BADCP)
| 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.
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=nullptr)
| 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)
bool | is_valid_name (const char *name, bool cpuregs_permitted)
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 the address of a 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=nullptr)
| 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 flags64_t ida_export | append_struct_fields (qstring *out, adiff_t *disp, int n, const tid_t *path, int plen, flags64_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
  ea | linear address
  Return values
  1 | ok, name is deleted
  0 | failure, 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
  ea | linear address
  Return values
  1 | ok
  0 | no 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 the name included into the name 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 the name 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
| Fail if the name contains invalid characters.
#define | SN_NOCHECK 0x01
| Replace invalid characters silently. 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; non-ASCII bytes will be decoded accordingly. More...
#define | SN_FORCE 0x800
| if the specified name is already present in the database, try variations with a numerical suffix like "_123"
#define | SN_NODUMMY 0x1000
| automatically prepend the name with '_' if it begins with a dummy suffix such as 'sub_'. More...
#define | SN_DELTAIL 0x2000
| if name cannot be set because of a tail byte, delete the hindering item
#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 cannot 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 | GN_NOT_DUMMY 0x0200
| do not return a dummy name
#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_t > | ea_name_vec_t
| vector of ea,name pairs
typedef int | ignore_name_def_t
| What name types to ignore.

## Enumerations
enum | ucdr_kind_t { UCDR_STRLIT = 0x01 , UCDR_NAME = 0x02 , UCDR_MANGLED = 0x04 , UCDR_TYPE = 0x08 }
enum | nametype_t { VNT_IDENT = UCDR_NAME|UCDR_MANGLED , VNT_TYPE = UCDR_TYPE , VNT_UDTMEM = UCDR_NAME , VNT_STRLIT = UCDR_STRLIT , 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

## ◆ debug_name_how_t

enum debug_name_how_t

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

## ◆ set_name()

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

  ea | linear address. do nothing if ea is not valid (return 0). tail bytes can't have names.
  name | new name. nullptr: do nothing (return 0). "" : delete name. otherwise this is a new name.
  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.

Return values

  1 | ok, name is changed
  0 | failure, a warning is displayed

## ◆ set_dummy_name()

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

  from | linear address of the operand which references to the address
  ea | linear address

Return values

  1 | ok, dummy name is generated or the byte already had a name
  0 | failure, invalid address or tail byte

## ◆ validate_name()

idaman bool ida_export validate_name | ( | qstring * | name,
|  | nametype_t | type,
|  | int | flags = `0`
| ) |  |

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

Parameters

  [in,out] | name | ptr to name. the name will be modified
  | type | the type of name we want to validate
  | flags | see SN_*

Returns
  success

## ◆ is_uname()

idaman bool ida_export is_uname | ( | const char * | name | ) |

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

Parameters

  name | name to test. may be nullptr.

Return values

  1 | yes
  0 | no

## ◆ is_valid_typename()

idaman bool ida_export is_valid_typename | ( | const char * | name | ) |

Is valid type name?

Parameters

  name | name to test. may be nullptr.

Return values

  1 | yes
  0 | no

## ◆ dummy_name_ea()

idaman ea_t ida_export dummy_name_ea | ( | const char * | name | ) |

Is dummy name?

Parameters

  name | name to test. may be nullptr.

Returns
  BADADDR if not, otherwise the address denoted by the name

## ◆ extract_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] | out | output buffer for the identifier
  | line | input string
  | x | x coordinate of cursor

Returns
  -1 if cannot extract. otherwise length of the name

## ◆ hide_name()

idaman void ida_export hide_name | ( | ea_t | ea | ) |

Remove name from the list of names.

Parameters

  ea | address of the name

## ◆ get_name_ea()

idaman ea_t ida_export get_name_ea | ( | ea_t | from,
|  | const char * | name
| ) |  |

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.

Parameters

  from | 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.
  name | any name in the program or nullptr

Returns
  address of the name or BADADDR

## ◆ get_name_base_ea()

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

  from | address of the operand which references to the address
  to | the referenced address

Returns
  address of the name used to represent the operand

## ◆ get_name_value()

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] | value | pointer to variable with answer
  | from | linear address where the name is used if not applicable, then should be BADADDR
  | name | any name in the program or nullptr

Returns
  Name value result codes

## ◆ get_ea_name()

idaman ssize_t ida_export get_ea_name | ( | qstring * | out,
|  | ea_t | ea,
|  | int | gtn_flags = `0`,
|  | getname_info_t * | gtni = `nullptr`
| ) |  |

Get name at the specified address.

Parameters

  [out] | out | buffer to hold the name
  | ea | linear address
  | gtn_flags | how exactly the name should be retrieved. combination of bits for get_ea_name() function. There is a convenience bits
  | gtni | additional information for name demangling Please use the convenience functions declared below instead of calling get_ea_name directly.

Returns
  success

## ◆ get_name_color()

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

  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.
  ea | linear address

## ◆ get_name_expr()

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] | out | output buffer for the name
  | 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.
  | n | number of referencing operand. for data items specify 0
  | ea | address to convert to name expression
  | 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.
  | flags | Name expression flags

Returns
  < 0 if address is not valid, no segment or other failure. otherwise the length of the name expression in characters.

## ◆ get_nice_colored_name()

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] | buf | buffer to hold the name
    | ea | linear address
    | flags | Nice colored name flags

  Returns
    the length of the generated name in bytes.

## ◆ append_struct_fields()

idaman flags64_t ida_export append_struct_fields | ( | qstring * | out,
|  | adiff_t * | disp,
|  | int | n,
|  | const tid_t * | path,
|  | int | plen,
|  | flags64_t | flags,
|  | adiff_t | delta,
|  | bool | appzero
| ) |  |

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

Parameters

  out | pointer to the output buffer
  disp | displacement from the name
  n | operand number in which the name appears
  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).
  plen | size of path array
  flags | the input flags. they will be returned if the struct cannot be found.
  delta | delta to add to displacement
  appzero | should append a struct field name if the displacement is zero?

Returns
  flags of the innermost struct member or the input flags

## ◆ get_struct_operand()

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

    disp | pointer to displacement (answer will be here)
    delta | pointer to displacement delta (answer will be here)
    path | existing strpath (if any)
    ea | linear address of instruction/data
    n | 0..UA_MAXOP-1 operand number

  Returns
    if success, then length of path + 1. if failed, then 0.

## ◆ get_nlist_idx()

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.

## ◆ demangle_name()

idaman int32 ida_export demangle_name | ( | qstring * | out,
|  | const char * | name,
|  | uint32 | disable_mask,
|  | demreq_type_t | demreq = `DQT_FULL`
| ) |  |

Demangle a name.

Parameters

  out | output buffer
  name | name to demangle
  disable_mask | bits to inhibit parts of demangled name (see MNG_). by the M_COMPILER bits a specific compiler can be selected (see MT_).
  demreq | the request type demreq_type_t

Returns
  ME_... or MT__ bitmasks from demangle.hpp

## ◆ is_name_defined_locally()

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

  pfn | pointer to function
  name | name to check
  ignore_name_def | which names to ignore when checking
  ea1 | the starting address of the range inside the function (optional)
  ea2 | the ending address of the range inside the function (optional)

Returns
  true if the name has been defined