IDA SDK

- Main Page
- Header Files
- Classes
- Modules

- File List
- File Members

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 flag)
| Set or delete name of an item at the specified address. More...
bool | set_name (ea_t ea, const char *name)
| Set or delete a name of an item at the specified address. More...
idaman bool ida_export | set_dummy_name (ea_t from, ea_t ea)
| Give an autogenerated (dummy) name. More...
idaman bool ida_export | do_name_anyway (ea_t ea, const char *name, size_t maxlen=0)
| Give a name anyway. More...
idaman bool ida_export | validate_name3 (qstring *name)
| Validate a name. More...
idaman bool ida_export | is_ident_char (char c)
| Can a character appear in a name? (present in NameChars or MangleChars)
idaman bool ida_export | is_visible_char (char c)
| Can a character be displayed in a name? (present in NameChars)
idaman bool ida_export | isident (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_name2 (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 (ea_t from, const char *name, uval_t *value)
| Get value of the name. More...
idaman ssize_t ida_export | get_ea_name (qstring *out, ea_t ea, int gtn_flags=0, const getname_info_t *gtni=NULL)
| Get name at the specified address. More...
ssize_t | get_true_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)
qstring | get_true_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)
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)
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 (ea_t from, int n, ea_t ea, uval_t off, char *buf, size_t bufsize, int flags=GETN_APPZERO)
| Convert address to name expression (name with a displacement). More...
idaman ssize_t ida_export | get_nice_colored_name (ea_t ea, char *buf, size_t bufsize, int flags=0)
| Get a nice colored name at the specified address. More...
idaman flags_t ida_export | append_struct_fields2 (qstring *out, int n, const tid_t *path, int plen, flags_t flags, adiff_t *disp, 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 (ea_t ea, int n, tid_t *path, adiff_t *disp, adiff_t *delta)
| Get offset within a structure if the operand refers to structure. More...
idaman int ida_export | gen_name_decl (ea_t ea, const char *name)
| Generate declaration of publicness/weakness of a name if necessary. More...
idaman void ida_export | reorder_dummy_names (void)
| Renumber dummy names.
idaman int32 ida_export | demangle_name2 (qstring *out, const char *name, uint32 disable_mask, demreq_type_t demreq=DQT_FULL)
| Demangle a name. More...
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 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_name2 (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_t ea1, ea_t ea2, ea_name_vec_t &names)

## 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 0x01
| Fail if the name contains invalid characters. More...
#define | SN_NOCHECK 0x00
| Replace invalid chars with SubstChar.
#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 | 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_INSNLOC 0x0080
| if cmd.ea and ea are in the same func, set GN_LOCAL
#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 | 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 | 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
idaman char ida_export_data | XlatAsciiName [256]
| Translation used to build meaningful names of ascii strings. More...
idaman ida_export_data char | NameChars [256]
| Array of valid identifier characters. More...
idaman ida_export_data char | MangleChars [256]
| The following characters are allowed in mangled names. More...
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

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

idaman bool ida_export set_name | ( | ea_t | ea,
|  | const char * | name,
|  | int | flag
| ) |  |

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. NULL: do nothing (return 0). "" : delete name. otherwise this is a new name.
  flag | 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

bool set_name | ( | ea_t | ea,
|  | const char * | name
| ) |  |
| inline

Set or delete a name of an item at the specified address.

This function is shortcut for set_name(ea,name,SN_CHECK);

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

idaman bool ida_export do_name_anyway | ( | ea_t | ea,
|  | const char * | name,
|  | size_t | maxlen = `0`
| ) |  |

Give a name anyway.

This function tries to give the specified name the specified address and tries to modify the name with a postfix ("_00") if the name already exists. It will try 100 different postfixes and fail only if all such names are already in use. For example, if the specified name is "xxx", the function will try to give names "xxx","xxx_0","xxx_2",... "xxx_99".

Parameters

  ea | linear address
  name | new name NULL: return 0 "" : return 0
  maxlen | if specified, the name will be truncated to have the specified maximum length

Returns
  success

idaman bool ida_export validate_name3 | ( | qstring * | name | ) |

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] | name | ptr to name. the name will be modified

Returns
  success

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

Return values

  1 | yes
  0 | no

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

Is valid type name?

Parameters

  name | name to test. may be NULL.

Return values

  1 | yes
  0 | no

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

Is dummy name?

Parameters

  name | name to test. may be NULL.

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

idaman ssize_t ida_export extract_name2 | ( | 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 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

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

  from | linear address where the name is used. if not applicable, then should be BADADDR.
  name | any 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

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

Returns
  address of the name used to represent the operand

idaman int ida_export get_name_value | ( | ea_t | from,
|  | const char * | name,
|  | uval_t * | value
| ) |  |

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
  | name | any name in the program or NULL
  [out] | value | pointer to variable with answer

Returns
  Name value result codes

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

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

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

idaman ssize_t ida_export get_name_expr | ( | ea_t | from,
|  | int | n,
|  | ea_t | ea,
|  | uval_t | off,
|  | char * | buf,
|  | size_t | bufsize,
|  | 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

  | 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.
  [out] | buf | buffer for the name
  | bufsize | size of the output buffer
  | 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.

idaman ssize_t ida_export get_nice_colored_name | ( | ea_t | ea,
|  | char * | buf,
|  | size_t | bufsize,
|  | 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

    | ea | linear address
    [out] | buf | buffer to hold the name
    | bufsize | size of the output buffer
    | flags | Nice colored name flags

  Returns
    the length of the generated name in bytes.

idaman flags_t ida_export append_struct_fields2 | ( | qstring * | out,
|  | int | n,
|  | const tid_t * | path,
|  | int | plen,
|  | flags_t | flags,
|  | adiff_t * | disp,
|  | 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
  n | number of operand n 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.
  disp | displacement from the name
  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

idaman int ida_export get_struct_operand | ( | ea_t | ea,
|  | int | n,
|  | tid_t * | path,
|  | adiff_t * | disp,
|  | adiff_t * | delta
| ) |  |

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

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

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

idaman int ida_export gen_name_decl | ( | ea_t | ea,
|  | const char * | name
| ) |  |

Generate declaration of publicness/weakness of a name if necessary.

Parameters

  ea | address of the name
  name | colored name. If name==NULL then is will be retrieved from the database.

Return values

  0 | declaration is generated
  1 | overflow of the line buffer occurred during declaration
  2 | nothing is done: name is not public

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_name2 | ( | 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_).

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

  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

## Variable Documentation

idaman char ida_export_data XlatAsciiName[256]

Translation used to build meaningful names of ascii strings.

Ascii strings are given a 'meaningful' name based on the first characters of the string itself. This array is used to translate characters which can't appear in identifiers to valid ones. This array is initialized with information from ida.cfg.

idaman ida_export_data char NameChars[256]

Array of valid identifier characters.

The kernel doesn't allow digits as first character of a name anyway. This array is initialized with information from ida.cfg. If it is empty, then all characters are allowed. The following characters are allowed in user-defined names:

idaman ida_export_data char MangleChars[256]

The following characters are allowed in mangled names.

they will be substituted with the SubstChar during output.