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=SN_NOCHECK)

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)

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
	do not remove "_\d+" at the end of name

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

◆ ucdr_kind_t

enum ucdr_kind_t

Enumerator
UCDR_STRLIT	string literals
UCDR_NAME	regular (unmangled) names
UCDR_MANGLED	mangled names
UCDR_TYPE	type names

◆ nametype_t

enum nametype_t

Enumerator
VNT_IDENT	identifier (e.g., function name)
VNT_TYPE	type name (can contain '<', '>', ...)
VNT_UDTMEM	UDT (structure, union, enum) member.
VNT_STRLIT	string literal
VNT_VISIBLE	visible cp (obsolete; will be deleted)

◆ 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

◆ demreq_type_t

enum demreq_type_t

Enumerator
DQT_NPURGED_8	only calculate number of purged bytes (sizeof(arg)==8)
DQT_NPURGED_4	only calculate number of purged bytes (sizeof(arg)==4)
DQT_NPURGED_2	only calculate number of purged bytes (sizeof(arg)==2)
DQT_COMPILER	only detect compiler that generated the name
DQT_NAME_TYPE	only detect the name type (data/code)
DQT_FULL	really demangle

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 = `SN_NOCHECK`
	)

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

Detailed Description

Classes

Functions

Macros

Typedefs

Enumerations

Variables

Enumeration Type Documentation

◆ ucdr_kind_t

◆ nametype_t

◆ debug_name_how_t

◆ demreq_type_t

Function Documentation

◆ set_name()

◆ set_dummy_name()

◆ validate_name()

◆ is_uname()

◆ is_valid_typename()

◆ dummy_name_ea()

◆ extract_name()

◆ hide_name()

◆ get_name_ea()

◆ get_name_base_ea()

◆ get_name_value()

◆ get_ea_name()

◆ get_name_color()

◆ get_name_expr()

◆ get_nice_colored_name()

◆ append_struct_fields()

◆ get_struct_operand()

◆ get_nlist_idx()

◆ demangle_name()

◆ is_name_defined_locally()