Module `ida_struct`

Structure type management (assembly level types)

Global variables

var MF_BASECLASS: a special member representing base class
var MF_BYTIL: the member was created due to the type system
var MF_DTOR: a special member representing destructor
var MF_DUPNAME: duplicate name resolved with _N suffix (N==soff)
var MF_HASTI: has type information?
var MF_HASUNI: has members of type "union"?
var MF_OK: is the member ok? (always yes)
var MF_UNIMEM: is a member of a union?
var SET_MEMTI_BYTIL: new type was created by the type subsystem
var SET_MEMTI_COMPATIBLE: new type must be compatible with the old
var SET_MEMTI_FUNCARG: mptr is function argument (cannot create arrays)
var SET_MEMTI_MAY_DESTROY: may destroy other members
var SET_MEMTI_USERTI: user-specified type
var SF_ALIGN: alignment (shift amount: 0..31)
var SF_ASMTIL: SF_ASMTIL = -2147483648
var SF_FRAME: the structure is a function frame
var SF_GHOST: ghost copy of a local type
var SF_HASUNI: has members of type "union"?
var SF_HIDDEN: the structure is collapsed
var SF_NOLIST: don't include in the chooser list
var SF_TYPLIB: the structure comes from type library
var SF_UNION: is a union? varunions are prohibited!
var SF_VAR: is variable size structure (varstruct)? a variable size structure is one with the zero size last member. if the last member is a varstruct, then the current structure is a varstruct too.
var SMT_ARRAY: arrays are forbidden as function arguments
var SMT_BADARG: bad parameters
var SMT_FAILED: failed to set new member type
var SMT_KEEP: no need to change the member type, the old type is better
var SMT_NOCOMPAT: the new type is not compatible with the old type
var SMT_OK: SMT_OK = 1
var SMT_OVERLAP: member would overlap with members that cannot be deleted
var SMT_SIZE: the new type is incompatible with the member size
var SMT_WORSE: the new type is worse than the old type
var STRNFL_REGEX: apply regular expressions to beautify the name
var STRUC_ERROR_MEMBER_LTUDT: failed to change corresponding local type
var STRUC_ERROR_MEMBER_NAME: already has member with this name (bad name)
var STRUC_ERROR_MEMBER_NESTED: recursive structure nesting is forbidden
var STRUC_ERROR_MEMBER_OFFSET: already has member at this offset
var STRUC_ERROR_MEMBER_OK: success
var STRUC_ERROR_MEMBER_SIZE: bad number of bytes or bad sizeof(type)
var STRUC_ERROR_MEMBER_STRUCT: bad struct id (the 1st argument)
var STRUC_ERROR_MEMBER_TINFO: bad typeid parameter
var STRUC_ERROR_MEMBER_UNIVAR: unions can't have variable sized members
var STRUC_ERROR_MEMBER_VARLAST: variable sized member should be the last member in the structure
var STRUC_SEPARATOR: structname.fieldname

Functions

def add_struc(*args) ‑> tid_t

add_struc(idx, name, is_union=False) -> tid_t

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

idx: (C++: uval_t)

name: (C++: const char *) char const *

is_union: (C++: bool)

def add_struc_member(*args) ‑> struc_error_t

add_struc_member(sptr, fieldname, offset, flag, mt, nbytes) -> struc_error_t

Add member to existing structure.

sptr: (C++: struc_t *) structure to modify

fieldname: (C++: const char *) if nullptr, then "anonymous_#" name will be generated

offset: (C++: ea_t) BADADDR means add to the end of structure

flag: (C++: flags64_t) type + representation bits

mt: (C++: const opinfo_t *) additional info about member type. must be present for structs,

offsets, enums, strings, struct offsets.

nbytes: (C++: asize_t) if == 0 then the structure will be a varstruct. in this case the

member should be the last member in the structure

def del_member_tinfo(*args) ‑> bool

del_member_tinfo(sptr, mptr) -> bool

Delete tinfo for given member.

sptr: (C++: struc_t *)

mptr: (C++: member_t *)

def del_struc(*args) ‑> bool

del_struc(sptr) -> bool

Delete a structure type This function deletes as well local type synced with the structure

sptr: (C++: struc_t *)

def del_struc_member(*args) ‑> bool

del_struc_member(sptr, offset) -> bool

Delete member at given offset.

sptr: (C++: struc_t *)

offset: (C++: ea_t)

def del_struc_members(*args) ‑> int

del_struc_members(sptr, off1, off2) -> int

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

sptr: (C++: struc_t *)

off1: (C++: ea_t)

off2: (C++: ea_t)

return: number of deleted members or -1 on error

def expand_struc(*args) ‑> bool

expand_struc(sptr, offset, delta, recalc=True) -> bool

Expand/Shrink structure type.

sptr: (C++: struc_t *)

offset: (C++: ea_t)

delta: (C++: adiff_t)

recalc: (C++: bool)

def get_best_fit_member(*args) ‑> member_t *

get_best_fit_member(sptr, offset) -> member_t

Get member that is most likely referenced by the specified offset. Useful for offsets > sizeof(struct).

sptr: (C++: const struc_t *) struc_t const *

offset: (C++: asize_t)

def get_first_struc_idx(*args) ‑> uval_t

get_first_struc_idx() -> uval_t

Get index of first structure.

return: BADADDR if no known structures, 0 otherwise

def get_innermost_member(*args) ‑> PyObject *

get_innermost_member(sptr, offset) -> (member_t, struc_t, int)

Get the innermost member at the given offset

sptr: the starting structure

offset: offset into the starting structure

return: - None on failure

tuple(member_t, struct_t, offset)
where member_t: a member in SPTR (it is not a structure),
struct_t: the innermost structure, offset: remaining offset into the returned member

def get_last_struc_idx(*args) ‑> uval_t

get_last_struc_idx() -> uval_t

Get index of last structure.

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

def get_max_offset(*args) ‑> ea_t

get_max_offset(sptr) -> ea_t

For unions: returns number of members, for structs: returns size of structure.

sptr: (C++: struc_t *)

def get_member(*args) ‑> member_t *

get_member(sptr, offset) -> member_t

Get member at given offset.

sptr: (C++: const struc_t *) struc_t const *

offset: (C++: asize_t)

def get_member_by_fullname(*args) ‑> struc_t **

get_member_by_fullname(fullname) -> member_t

Get a member by its fully qualified name, "struct.field".

fullname: (C++: const char *) char const *

def get_member_by_id(*args) ‑> qstring *, struc_t **

get_member_by_id(mid) -> member_t

Check if the specified member id points to a struct member. convenience function.

mid: (C++: tid_t)

def get_member_by_name(*args) ‑> member_t *

get_member_by_name(sptr, membername) -> member_t

Get a member by its name, like "field44".

sptr: (C++: const struc_t *) struc_t const *

membername: (C++: const char *) char const *

def get_member_cmt(*args) ‑> qstring *

get_member_cmt(mid, repeatable) -> str

Get comment of structure member.

mid: (C++: tid_t)

repeatable: (C++: bool)

def get_member_fullname(*args) ‑> qstring *

get_member_fullname(mid) -> str

Get a member's fully qualified name, "struct.field".

mid: (C++: tid_t)

def get_member_id(*args) ‑> tid_t

get_member_id(sptr, offset) -> tid_t

Get member id at given offset.

sptr: (C++: const struc_t *) struc_t const *

offset: (C++: asize_t)

def get_member_name(*args) ‑> qstring *

get_member_name(mid) -> str

mid: tid_t

def get_member_size(*args) ‑> asize_t

get_member_size(NONNULL_mptr) -> asize_t

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

NONNULL_mptr: (C++: const member_t *) member_t const *

def get_member_struc(*args) ‑> struc_t *

get_member_struc(fullname) -> struc_t

Get containing structure of member by its full name "struct.field".

fullname: (C++: const char *) char const *

def get_member_tinfo(*args) ‑> bool

get_member_tinfo(tif, mptr) -> bool

Get tinfo for given member.

tif: (C++: tinfo_t *)

mptr: (C++: const member_t *) member_t const *

def get_next_member_idx(*args) ‑> ssize_t

get_next_member_idx(sptr, off) -> ssize_t

Get the next member idx, if it does not exist, return -1.

sptr: (C++: const struc_t *) struc_t const *

off: (C++: asize_t)

def get_next_struc_idx(*args) ‑> uval_t

get_next_struc_idx(idx) -> uval_t

Get next struct index.

idx: (C++: uval_t)

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

def get_or_guess_member_tinfo(*args) ‑> bool

get_or_guess_member_tinfo(tif, mptr) -> bool

Try to get tinfo for given member - if failed, generate a tinfo using information about the member id from the disassembly

tif: (C++: tinfo_t *)

mptr: (C++: const member_t *) member_t const *

def get_prev_member_idx(*args) ‑> ssize_t

get_prev_member_idx(sptr, off) -> ssize_t

Get the prev member idx, if it does not exist, return -1.

sptr: (C++: const struc_t *) struc_t const *

off: (C++: asize_t)

def get_prev_struc_idx(*args) ‑> uval_t

get_prev_struc_idx(idx) -> uval_t

Get previous struct index.

idx: (C++: uval_t)

return: BADADDR if resulting index is negative, otherwise idx - 1

def get_sptr(*args) ‑> struc_t *

get_sptr(mptr) -> struc_t

Get child struct if member is a struct.

mptr: (C++: const member_t *) member_t const *

def get_struc(*args) ‑> struc_t *

get_struc(id) -> struc_t

Get pointer to struct type info.

id: (C++: tid_t)

def get_struc_by_idx(*args) ‑> tid_t

get_struc_by_idx(idx) -> tid_t

Get struct id by struct number.

idx: (C++: uval_t)

def get_struc_cmt(*args) ‑> qstring *

get_struc_cmt(id, repeatable) -> str

Get struct comment.

id: (C++: tid_t)

repeatable: (C++: bool)

def get_struc_first_offset(*args) ‑> ea_t

get_struc_first_offset(sptr) -> ea_t

Get offset of first member.

sptr: (C++: const struc_t *) struc_t const *

return: BADADDR if memqty == 0

def get_struc_id(*args) ‑> tid_t

get_struc_id(name) -> tid_t

Get struct id by name.

name: (C++: const char *) char const *

def get_struc_idx(*args) ‑> uval_t

get_struc_idx(id) -> uval_t

Get internal number of the structure.

id: (C++: tid_t)

def get_struc_last_offset(*args) ‑> ea_t

get_struc_last_offset(sptr) -> ea_t

Get offset of last member.

sptr: (C++: const struc_t *) struc_t const *

return: BADADDR if memqty == 0

def get_struc_name(*args) ‑> qstring *

get_struc_name(id, flags=0) -> str

id: tid_t

flags: int

def get_struc_next_offset(*args) ‑> ea_t

get_struc_next_offset(sptr, offset) -> ea_t

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

sptr: (C++: const struc_t *) struc_t const *

offset: (C++: ea_t)

return: BADADDR if no next offset

def get_struc_prev_offset(*args) ‑> ea_t

get_struc_prev_offset(sptr, offset) -> ea_t

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

sptr: (C++: const struc_t *) struc_t const *

offset: (C++: ea_t)

return: BADADDR if no prev offset

def get_struc_qty(*args) ‑> size_t

get_struc_qty() -> size_t

Get number of known structures.

def get_struc_size(*args) ‑> asize_t

get_struc_size(sptr) -> asize_t

Get struct size (also see get_struc_size(const struc_t *))

sptr: struc_t const *

get_struc_size(id) -> asize_t

id: tid_t

def is_anonymous_member_name(*args) ‑> bool

is_anonymous_member_name(name) -> bool

Is member name prefixed with "anonymous"?

name: (C++: const char *) char const *

def is_dummy_member_name(*args) ‑> bool

is_dummy_member_name(name) -> bool

Is member name an auto-generated name?

name: (C++: const char *) char const *

def is_member_id(*args) ‑> bool

is_member_id(mid) -> bool

Is a member id?

mid: (C++: tid_t)

def is_special_member(*args) ‑> bool

is_special_member(id) -> bool

Is a special member with the name beginning with ' '?

id: (C++: tid_t)

def is_union(*args) ‑> bool

is_union(id) -> bool

Is a union?

id: (C++: tid_t)

def is_varmember(*args) ‑> bool

is_varmember(mptr) -> bool

Is variable size member?

mptr: (C++: const member_t *) member_t const *

def is_varstr(*args) ‑> bool

is_varstr(id) -> bool

Is variable size structure?

id: (C++: tid_t)

def retrieve_member_info(*args) ‑> opinfo_t *

retrieve_member_info(buf, mptr) -> opinfo_t

Get operand type info for member.

buf: (C++: opinfo_t *)

mptr: (C++: const member_t *) member_t const *

def save_struc(*args) ‑> void

save_struc(sptr, may_update_ltypes=True)

Update struct information in the database (internal function)

sptr: (C++: const struc_t *) struc_t const *

may_update_ltypes: (C++: bool)

def set_member_cmt(*args) ‑> bool

set_member_cmt(mptr, cmt, repeatable) -> bool

Set member comment.

mptr: (C++: member_t *)

cmt: (C++: const char *) char const *

repeatable: (C++: bool)

def set_member_name(*args) ‑> bool

set_member_name(sptr, offset, name) -> bool

Set name of member at given offset.

sptr: (C++: struc_t *)

offset: (C++: ea_t)

name: (C++: const char *) char const *

def set_member_tinfo(*args) ‑> smt_code_t

set_member_tinfo(sptr, mptr, memoff, tif, flags) -> smt_code_t

Set tinfo for given member.

sptr: (C++: struc_t *) containing struct

mptr: (C++: member_t *) target member

memoff: (C++: uval_t) offset within member

tif: (C++: const tinfo_t &) type info

flags: (C++: int) Set member tinfo flags

def set_member_type(*args) ‑> bool

set_member_type(sptr, offset, flag, mt, nbytes) -> bool

Set type of member at given offset (also see add_struc_member())

sptr: (C++: struc_t *)

offset: (C++: ea_t)

flag: (C++: flags64_t)

mt: (C++: const opinfo_t *) opinfo_t const *

nbytes: (C++: asize_t)

def set_struc_align(*args) ‑> bool

set_struc_align(sptr, shift) -> bool

Set structure alignment (SF_ALIGN)

sptr: (C++: struc_t *)

shift: (C++: int)

def set_struc_cmt(*args) ‑> bool

set_struc_cmt(id, cmt, repeatable) -> bool

Set structure comment.

id: (C++: tid_t)

cmt: (C++: const char *) char const *

repeatable: (C++: bool)

def set_struc_hidden(*args) ‑> void

set_struc_hidden(sptr, is_hidden)

Hide/unhide a struct type.

sptr: (C++: struc_t *)

is_hidden: (C++: bool)

def set_struc_idx(*args) ‑> bool

set_struc_idx(sptr, idx) -> bool

Set internal number of struct. Also see get_struc_idx(), get_struc_by_idx().

sptr: (C++: const struc_t *) struc_t const *

idx: (C++: uval_t)

def set_struc_listed(*args) ‑> void

set_struc_listed(sptr, is_listed)

Add/remove a struct type from the struct list.

sptr: (C++: struc_t *)

is_listed: (C++: bool)

def set_struc_name(*args) ‑> bool

set_struc_name(id, name) -> bool

Set structure name.

id: (C++: tid_t)

name: (C++: const char *) char const *

def stroff_as_size(*args) ‑> bool

stroff_as_size(plen, sptr, value) -> bool

plen: int

sptr: struc_t const *

value: asize_t

stroff_as_size(plen, tif, value) -> bool

plen: int

tif: tinfo_t const &

value: asize_t

def unsync_and_delete_struc(*args) ‑> void

unsync_and_delete_struc(sptr)

Delete the structure but leave synced ltudt unchanged. Note del_struc() deletes both ASM struc and the corresponding local type

sptr: (C++: struc_t *)

def visit_stroff_fields(*args) ‑> adiff_t *

visit_stroff_fields(sfv, path, disp, appzero) -> flags64_t

sfv: struct_field_visitor_t &

path: tid_t const *

disp: adiff_t *

appzero: bool

def visit_stroff_udms(*args) ‑> adiff_t *

visit_stroff_udms(sfv, path, disp, appzero) -> int

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

sfv: (C++: udm_visitor_t &) visitor object

path: (C++: const tid_t *) struct path (path[0] contains the initial struct id)

disp: (C++: adiff_t *) offset into structure

appzero: (C++: bool) should visit field at offset zero?

return: visitor result

Classes

class dyn_member_ref_array (*args)

Proxy of C++ dynamic_wrapped_array_t< member_t > class.

__init__(self, _data, _count) -> dyn_member_ref_array

_data: member_t *

_count: size_t

Instance variables

var count: count
var data: data

class member_t (*args)

Proxy of C++ member_t class.

__init__(self) -> member_t

Instance variables

var eoff: end offset
var flag: type+representation bits
var id: name(), cmt, rptcmt
var props: Struct member properties
var soff: start offset (for unions - number of the member 0..n)

Methods

def by_til(self, *args) ‑> bool: by_til(self) -> bool
Was the member created due to the type system?
def get_size(self, *args) ‑> asize_t: get_size(self) -> asize_t
Get member size.
def get_soff(self, *args) ‑> ea_t: get_soff(self) -> ea_t
Get start offset (for unions - returns 0)
def has_ti(self, *args) ‑> bool: has_ti(self) -> bool
Has type information?
def has_union(self, *args) ‑> bool: has_union(self) -> bool
Has members of type "union"?
def is_baseclass(self, *args) ‑> bool: is_baseclass(self) -> bool
Is a base class member?
def is_destructor(self, *args) ‑> bool: is_destructor(self) -> bool
Is a virtual destructor?
def is_dupname(self, *args) ‑> bool: is_dupname(self) -> bool
Duplicate name was resolved during import?
def unimem(self, *args) ‑> bool: unimem(self) -> bool
Is a member of a union?

class struc_t (*args, **kwargs)

Proxy of C++ struc_t class.

Instance variables

var age: not used
var id: struct id
var members : dynamic_wrapped_array_t< member_t >: only defined members are stored here. there may be gaps between members.
var memqty: number of members
var ordinal: corresponding local type ordinal number
var props: Structure properties

Methods

def from_til(self, *args) ‑> bool: from_til(self) -> bool
Does structure come from a type library?
def get_alignment(self, *args) ‑> int: get_alignment(self) -> int
See SF_ALIGN.
def get_last_member(self, *args) ‑> member_t const *: get_last_member(self) -> member_t
def get_member(self, index)
def has_union(self, *args) ‑> bool: has_union(self) -> bool
Has members of type "union"?
def is_choosable(self, *args) ‑> bool: is_choosable(self) -> bool
Is included in chooser list? Use set_struc_listed to change the listed status
def is_copyof(self, *args) ‑> bool: is_copyof(self) -> bool
Is copied from a local type?
def is_frame(self, *args) ‑> bool: is_frame(self) -> bool
Is this structure a function frame?
def is_ghost(self, *args) ‑> bool: is_ghost(self) -> bool
Is a ghost copy of a local type?
def is_hidden(self, *args) ‑> bool: is_hidden(self) -> bool
Is the structure collapsed? Use set_struc_hidden to change the hidden status
def is_mappedto(self, *args) ‑> bool: is_mappedto(self) -> bool
Is mapped to a local type?
def is_synced(self, *args) ‑> bool: is_synced(self) -> bool
Is synced with a local type?
def is_union(self, *args) ‑> bool: is_union(self) -> bool
Is a union?
def is_varstr(self, *args) ‑> bool: is_varstr(self) -> bool
Is variable size structure?
def like_union(self, *args) ‑> bool: like_union(self) -> bool
Is a union or contains members of type "union"?
def set_alignment(self, *args) ‑> void: set_alignment(self, shift)
Do not use; use set_struc_align()

shift: (C++: int)

class struct_field_visitor_t (*args)

Proxy of C++ struct_field_visitor_t class.

__init__(self) -> struct_field_visitor_t

self: PyObject *

Methods

def visit_field(self, *args) ‑> int: visit_field(self, sptr, mptr) -> int
sptr: struc_t *

mptr: member_t *

class udm_visitor_t (*args)

Proxy of C++ udm_visitor_t class.

__init__(self) -> udm_visitor_t

self: PyObject *

Methods

def visit_udm(self, *args) ‑> int: visit_udm(self, tid, tif, udm) -> int
tid: (C++: tid_t) udt tid

tif: (C++: const tinfo_t *) udt tif (may be nullptr for corrupted idbs)

udm: (C++: const udm_t *) udm to visit (may be nullptr if udm was not found)