Latest available version: IDA and decompilers v8.4.240320sp1 see all releases
Hex-Rays logo State-of-the-art binary code analysis tools
email icon
struct.hpp File Reference

Structure type management (assembly level types) More...

Classes

class  member_t
 Describes a member of an assembly level structure. More...
 
class  struc_t
 Information about a structure type (assembly level) More...
 
struct  udm_visitor_t
 

Macros

#define STRUC_SEPARATOR   '.'
 structname.fieldname
 
#define MF_OK   0x00000001
 is the member ok? (always yes)
 
#define MF_UNIMEM   0x00000002
 is a member of a union?
 
#define MF_HASUNI   0x00000004
 has members of type "union"?
 
#define MF_BYTIL   0x00000008
 the member was created due to the type system
 
#define MF_HASTI   0x00000010
 has type information?
 
#define MF_BASECLASS   0x00000020
 a special member representing base class
 
#define MF_DTOR   0x00000040
 a special member representing destructor
 
#define MF_DUPNAME   0x00000080
 duplicate name resolved with _N suffix (N==soff)
 
#define MF_RESERVED1   0x80000000
 reserved (for internal usage)
 
#define SF_VAR   0x00000001
 is variable size structure (varstruct)? a variable size structure is one with the zero size last member. More...
 
#define SF_UNION   0x00000002
 is a union? varunions are prohibited!
 
#define SF_HASUNI   0x00000004
 has members of type "union"?
 
#define SF_NOLIST   0x00000008
 don't include in the chooser list
 
#define SF_TYPLIB   0x00000010
 the structure comes from type library
 
#define SF_HIDDEN   0x00000020
 the structure is collapsed
 
#define SF_FRAME   0x00000040
 the structure is a function frame
 
#define SF_ALIGN   0x00000F80
 alignment (shift amount: 0..31)
 
#define SF_GHOST   0x00001000
 ghost copy of a local type
 
#define SF_ASMTIL   0x80000000
 temporary: asmtil struct *-
 
#define STRNFL_REGEX   0x0001
 apply regular expressions to beautify the name
 
#define SET_MEMTI_MAY_DESTROY   0x0001
 may destroy other members
 
#define SET_MEMTI_COMPATIBLE   0x0002
 new type must be compatible with the old
 
#define SET_MEMTI_FUNCARG   0x0004
 mptr is function argument (cannot create arrays)
 
#define SET_MEMTI_BYTIL   0x0008
 new type was created by the type subsystem
 
#define SET_MEMTI_USERTI   0x0010
 user-specified type
 

Enumerations

enum  struc_error_t {
  STRUC_ERROR_MEMBER_OK = 0 , STRUC_ERROR_MEMBER_NAME = -1 , STRUC_ERROR_MEMBER_OFFSET = -2 , STRUC_ERROR_MEMBER_SIZE = -3 ,
  STRUC_ERROR_MEMBER_TINFO = -4 , STRUC_ERROR_MEMBER_STRUCT = -5 , STRUC_ERROR_MEMBER_UNIVAR = -6 , STRUC_ERROR_MEMBER_VARLAST = -7 ,
  STRUC_ERROR_MEMBER_NESTED = -8 , STRUC_ERROR_MEMBER_LTUDT = -9
}
 Return values for add_struc_member() More...
 
enum  smt_code_t {
  SMT_BADARG = -6 , SMT_NOCOMPAT = -5 , SMT_WORSE = -4 , SMT_SIZE = -3 ,
  SMT_ARRAY = -2 , SMT_OVERLAP = -1 , SMT_FAILED = 0 , SMT_OK = 1 ,
  SMT_KEEP = 2
}
 Member type information (return values for set_member_tinfo()) More...
 

Functions

idaman tid_t ida_export get_struc_id (const char *name)
 Get struct id by name.
 
idaman ssize_t ida_export get_struc_name (qstring *out, tid_t id, int flags=0)
 Get struct name by id. More...
 
qstring get_struc_name (tid_t id, int flags=0)
 
idaman ssize_t ida_export get_struc_cmt (qstring *buf, tid_t id, bool repeatable)
 Get struct comment.
 
idaman asize_t ida_export get_struc_size (const struc_t *sptr)
 Get struct size (also see get_struc_size(tid_t))
 
asize_t get_struc_size (tid_t id)
 Get struct size (also see get_struc_size(const struc_t *))
 
bool is_varstr (tid_t id)
 Is variable size structure?
 
bool is_union (tid_t id)
 Is a union?
 
idaman struc_t *ida_export get_member_struc (const char *fullname)
 Get containing structure of member by its full name "struct.field".
 
idaman struc_t *ida_export get_sptr (const member_t *mptr)
 Get child struct if member is a struct.
 
idaman member_t *ida_export get_member (const struc_t *sptr, asize_t offset)
 Get member at given offset.
 
tid_t get_member_id (const struc_t *sptr, asize_t offset)
 Get member id at given offset.
 
idaman member_t *ida_export get_innermost_member (struc_t **sptr, asize_t *offset)
 Get the innermost member at the given offset. More...
 
idaman member_t *ida_export get_member_by_name (const struc_t *sptr, const char *membername)
 Get a member by its name, like "field44".
 
idaman member_t *ida_export get_member_by_fullname (struc_t **sptr_place, const char *fullname)
 Get a member by its fully qualified name, "struct.field".
 
idaman ssize_t ida_export get_member_fullname (qstring *out, tid_t mid)
 Get a member's fully qualified name, "struct.field".
 
idaman ssize_t ida_export get_member_name (qstring *out, tid_t mid)
 Get name of structure member.
 
qstring get_member_name (tid_t mid)
 
idaman ssize_t ida_export get_member_cmt (qstring *buf, tid_t mid, bool repeatable)
 Get comment of structure member.
 
asize_t get_member_size (const member_t *NONNULL mptr)
 Get size of structure member. More...
 
idaman bool ida_export is_varmember (const member_t *mptr)
 Is variable size member?
 
idaman member_t *ida_export get_best_fit_member (const struc_t *sptr, asize_t offset)
 Get member that is most likely referenced by the specified offset. More...
 
idaman ssize_t ida_export get_next_member_idx (const struc_t *sptr, asize_t off)
 Get the next member idx, if it does not exist, return -1.
 
idaman ssize_t ida_export get_prev_member_idx (const struc_t *sptr, asize_t off)
 Get the prev member idx, if it does not exist, return -1.
 
idaman tid_t ida_export add_struc (uval_t idx, const char *name, bool is_union=false)
 Create a structure type. More...
 
idaman bool ida_export del_struc (struc_t *sptr)
 Delete a structure type This function deletes as well local type synced with the structure.
 
idaman bool ida_export set_struc_idx (const struc_t *sptr, uval_t idx)
 Set internal number of struct. More...
 
idaman bool ida_export set_struc_align (struc_t *sptr, int shift)
 Set structure alignment (SF_ALIGN)
 
idaman bool ida_export set_struc_name (tid_t id, const char *name)
 Set structure name.
 
idaman bool ida_export set_struc_cmt (tid_t id, const char *cmt, bool repeatable)
 Set structure comment.
 
idaman struc_error_t ida_export add_struc_member (struc_t *sptr, const char *fieldname, ea_t offset, flags64_t flag, const opinfo_t *mt, asize_t nbytes)
 Add member to existing structure. More...
 
idaman bool ida_export del_struc_member (struc_t *sptr, ea_t offset)
 Delete member at given offset.
 
idaman int ida_export del_struc_members (struc_t *sptr, ea_t off1, ea_t off2)
 Delete members which occupy range of offsets (off1..off2). More...
 
idaman bool ida_export set_member_name (struc_t *sptr, ea_t offset, const char *name)
 Set name of member at given offset.
 
idaman bool ida_export set_member_type (struc_t *sptr, ea_t offset, flags64_t flag, const opinfo_t *mt, asize_t nbytes)
 Set type of member at given offset (also see add_struc_member())
 
idaman bool ida_export set_member_cmt (member_t *mptr, const char *cmt, bool repeatable)
 Set member comment.
 
idaman bool ida_export expand_struc (struc_t *sptr, ea_t offset, adiff_t delta, bool recalc=true)
 Expand/Shrink structure type.
 
idaman void ida_export save_struc (const struc_t *sptr, bool may_update_ltypes=true)
 Update struct information in the database (internal function)
 
idaman void ida_export set_struc_hidden (struc_t *sptr, bool is_hidden)
 Hide/unhide a struct type.
 
idaman void ida_export set_struc_listed (struc_t *sptr, bool is_listed)
 Add/remove a struct type from the struct list.
 
idaman bool ida_export get_member_tinfo (tinfo_t *tif, const member_t *mptr)
 Get tinfo for given member.
 
idaman bool ida_export del_member_tinfo (struc_t *sptr, member_t *mptr)
 Delete tinfo for given member.
 
idaman smt_code_t ida_export set_member_tinfo (struc_t *sptr, member_t *mptr, uval_t memoff, const tinfo_t &tif, int flags)
 Set tinfo for given member. More...
 
idaman bool ida_export get_or_guess_member_tinfo (tinfo_t *tif, const member_t *mptr)
 Try to get tinfo for given member - if failed, generate a tinfo using information about the member id from the disassembly.
 
idaman opinfo_t *ida_export retrieve_member_info (opinfo_t *buf, const member_t *mptr)
 Get operand type info for member.
 
THREAD_SAFE bool is_anonymous_member_name (const char *name)
 Is member name prefixed with "anonymous"?
 
THREAD_SAFE bool is_dummy_member_name (const char *name)
 Is member name an auto-generated name?
 
member_t *idaapi get_member_by_id (qstring *out_mname, tid_t mid, struc_t **sptr_place)
 Check if the specified member id points to a struct member.
 
idaman member_t *ida_export get_member_by_id (tid_t mid, struc_t **sptr_place=nullptr)
 Check if the specified member id points to a struct member. convenience function.
 
idaman bool ida_export is_member_id (tid_t mid)
 Is a member id?
 
idaman bool ida_export is_special_member (tid_t id)
 Is a special member with the name beginning with ' '?
 
idaman int ida_export visit_stroff_udms (udm_visitor_t &sfv, const tid_t *path, int plen, adiff_t *disp, bool appzero)
 Visit structure fields in a stroff expression or in a reference to a struct data variable. More...
 
bool stroff_as_size (int plen, const struc_t *sptr, asize_t value)
 Should display a structure offset expression as the structure size?
 
bool stroff_as_size (int plen, const tinfo_t &tif, asize_t value)
 
Internal structures list

IDA maintains an internal vector of known structures.

Use these functions to work with this vector.

idaman size_t ida_export get_struc_qty (void)
 Get number of known structures.
 
idaman uval_t ida_export get_first_struc_idx (void)
 Get index of first structure. More...
 
idaman uval_t ida_export get_last_struc_idx (void)
 Get index of last structure. More...
 
THREAD_SAFE uval_t get_prev_struc_idx (uval_t idx)
 Get previous struct index. More...
 
idaman uval_t ida_export get_next_struc_idx (uval_t idx)
 Get next struct index. More...
 
idaman uval_t ida_export get_struc_idx (tid_t id)
 Get internal number of the structure.
 
idaman tid_t ida_export get_struc_by_idx (uval_t idx)
 Get struct id by struct number.
 
idaman struc_t *ida_export get_struc (tid_t id)
 Get pointer to struct type info.
 
Struct offsets
Note
for unions, soff == number of the current member
idaman ea_t ida_export get_struc_prev_offset (const struc_t *sptr, ea_t offset)
 Get offset of member with largest offset less than 'offset'. More...
 
idaman ea_t ida_export get_struc_next_offset (const struc_t *sptr, ea_t offset)
 Get offset of member with smallest offset larger than 'offset'. More...
 
idaman ea_t ida_export get_struc_last_offset (const struc_t *sptr)
 Get offset of last member. More...
 
idaman ea_t ida_export get_struc_first_offset (const struc_t *sptr)
 Get offset of first member. More...
 
idaman void ida_export unsync_and_delete_struc (struc_t *sptr)
 Delete the structure but leave synced ltudt unchanged. More...
 
ea_t get_max_offset (struc_t *sptr)
 For unions: returns number of members, for structs: returns size of structure.
 

Detailed Description

Structure type management (assembly level types)

Enumeration Type Documentation

◆ struc_error_t

Return values for add_struc_member()

Enumerator
STRUC_ERROR_MEMBER_OK 

success

STRUC_ERROR_MEMBER_NAME 

already has member with this name (bad name)

STRUC_ERROR_MEMBER_OFFSET 

already has member at this offset

STRUC_ERROR_MEMBER_SIZE 

bad number of bytes or bad sizeof(type)

STRUC_ERROR_MEMBER_TINFO 

bad typeid parameter

STRUC_ERROR_MEMBER_STRUCT 

bad struct id (the 1st argument)

STRUC_ERROR_MEMBER_UNIVAR 

unions can't have variable sized members

STRUC_ERROR_MEMBER_VARLAST 

variable sized member should be the last member in the structure

STRUC_ERROR_MEMBER_NESTED 

recursive structure nesting is forbidden

STRUC_ERROR_MEMBER_LTUDT 

failed to change corresponding local type

◆ smt_code_t

enum smt_code_t

Member type information (return values for set_member_tinfo())

Enumerator
SMT_BADARG 

bad parameters

SMT_NOCOMPAT 

the new type is not compatible with the old type

SMT_WORSE 

the new type is worse than the old type

SMT_SIZE 

the new type is incompatible with the member size

SMT_ARRAY 

arrays are forbidden as function arguments

SMT_OVERLAP 

member would overlap with members that cannot be deleted

SMT_FAILED 

failed to set new member type

SMT_OK 

success: changed the member type

SMT_KEEP 

no need to change the member type, the old type is better

Function Documentation

◆ get_first_struc_idx()

idaman uval_t ida_export get_first_struc_idx ( void  )

Get index of first structure.

Returns
BADADDR if no known structures, 0 otherwise

◆ get_last_struc_idx()

idaman uval_t ida_export get_last_struc_idx ( void  )

Get index of last structure.

Returns
BADADDR if no known structures, get_struc_qty()-1 otherwise

◆ get_prev_struc_idx()

THREAD_SAFE uval_t get_prev_struc_idx ( uval_t  idx)
inline

Get previous struct index.

Returns
BADADDR if resulting index is negative, otherwise idx - 1

◆ get_next_struc_idx()

idaman uval_t ida_export get_next_struc_idx ( uval_t  idx)

Get next struct index.

Returns
BADADDR if resulting index is out of bounds, otherwise idx++

◆ get_struc_name()

idaman ssize_t ida_export get_struc_name ( qstring out,
tid_t  id,
int  flags = 0 
)

Get struct name by id.

Parameters
[out]outbuffer to hold the name
idstruct id
flagsStruct name flags

◆ get_struc_prev_offset()

idaman ea_t ida_export get_struc_prev_offset ( const struc_t sptr,
ea_t  offset 
)

Get offset of member with largest offset less than 'offset'.

Returns
BADADDR if no prev offset

◆ get_struc_next_offset()

idaman ea_t ida_export get_struc_next_offset ( const struc_t sptr,
ea_t  offset 
)

Get offset of member with smallest offset larger than 'offset'.

Returns
BADADDR if no next offset

◆ get_struc_last_offset()

idaman ea_t ida_export get_struc_last_offset ( const struc_t sptr)

Get offset of last member.

Returns
BADADDR if memqty == 0

◆ get_struc_first_offset()

idaman ea_t ida_export get_struc_first_offset ( const struc_t sptr)

Get offset of first member.

Returns
BADADDR if memqty == 0

◆ unsync_and_delete_struc()

idaman void ida_export unsync_and_delete_struc ( struc_t sptr)

Delete the structure but leave synced ltudt unchanged.

Note del_struc() deletes both ASM struc and the corresponding local type

◆ get_innermost_member()

idaman member_t *ida_export get_innermost_member ( struc_t **  sptr,
asize_t *  offset 
)

Get the innermost member at the given offset.

Parameters
[in]sptrthe starting structure
[out]sptrthe innermost structure
[in]offsetoffset into the starting structure
[out]offsetremaining offset into the returned member
Return values
amember in SPTR (it is not a structure) or 'nullptr'

◆ get_member_size()

asize_t get_member_size ( const member_t *NONNULL  mptr)
inline

Get size of structure member.

May return 0 for the last member of varstruct. For union members, returns member_t::eoff.

◆ get_best_fit_member()

idaman member_t *ida_export get_best_fit_member ( const struc_t sptr,
asize_t  offset 
)

Get member that is most likely referenced by the specified offset.

Useful for offsets > sizeof(struct).

◆ add_struc()

idaman tid_t ida_export add_struc ( uval_t  idx,
const char *  name,
bool  is_union = false 
)

Create a structure type.

if idx==BADADDR then add as the last idx. if name==nullptr then a name will be generated "struct_%d".

◆ set_struc_idx()

idaman bool ida_export set_struc_idx ( const struc_t sptr,
uval_t  idx 
)

Set internal number of struct.

Also see get_struc_idx(), get_struc_by_idx().

◆ add_struc_member()

idaman struc_error_t ida_export add_struc_member ( struc_t sptr,
const char *  fieldname,
ea_t  offset,
flags64_t  flag,
const opinfo_t mt,
asize_t  nbytes 
)

Add member to existing structure.

Parameters
sptrstructure to modify
fieldnameif nullptr, then "anonymous_#" name will be generated
offsetBADADDR means add to the end of structure
flagtype + representation bits
mtadditional info about member type. must be present for structs, offsets, enums, strings, struct offsets.
nbytesif == 0 then the structure will be a varstruct. in this case the member should be the last member in the structure

◆ del_struc_members()

idaman int ida_export del_struc_members ( struc_t sptr,
ea_t  off1,
ea_t  off2 
)

Delete members which occupy range of offsets (off1..off2).

Returns
number of deleted members or -1 on error

◆ set_member_tinfo()

idaman smt_code_t ida_export set_member_tinfo ( struc_t sptr,
member_t mptr,
uval_t  memoff,
const tinfo_t tif,
int  flags 
)

Set tinfo for given member.

Parameters
sptrcontaining struct
mptrtarget member
memoffoffset within member
tiftype info
flagsSet member tinfo flags

◆ visit_stroff_udms()

idaman int ida_export visit_stroff_udms ( udm_visitor_t sfv,
const tid_t path,
int  plen,
adiff_t *  disp,
bool  appzero 
)

Visit structure fields in a stroff expression or in a reference to a struct data variable.

This function can be used to enumerate all components of an expression like 'a.b.c'.

Parameters
sfvvisitor object
pathstruct path (path[0] contains the initial struct id)
plenlen
[in,out]dispoffset into structure
appzeroshould visit field at offset zero?
Returns
visitor result