3.1.6. structure – Structure module¶

This module exposes a number of tools and defines some classes that can be used to interacting with the structures defined in the database. The classes defined by this module wrap IDAPython’s structure API and expose a simpler interface that can be used to perform various operations against a structure such as renaming or enumerating the structure’s members.

The base argument type for getting a structure_t can be either a name, an identifier, or an index. Typically one will call structure.by with either identifier type which will then return an instance of their structure_t.

To list the different structures available in the database, one can use structure.list with their chosen method of filtering. This will list all of the available structures at which point the user can then request it by passing an identifer to structure.by. The chosen methods of filtering are:

name - Match the structures to a structure name
like - Filter the structure names according to a glob
regex - Filter the structure names according to a regular-expression
index - Match the structures by its index
identifier or id - Match the structure by its id which is a idaapi.uval_t
size - Filter the structures for any matching the specified size
greater or ge - Match structures that are larger (inclusive) than the specified size
gt - Match structures that are larger (exclusive) than the specified size
less or le - Match structures that are smaller (inclusive) than the specified size
lt - Match structures that are smaller (exclusive) than the specified size
predicate - Filter the structures by passing the id (idaapi.uval_t) to a callable

Some examples of using these keywords are as follows:

> structure.list('my*')
> iterable = structure.iterate(regex='__.*')
> result = structure.search(index=42)

3.1.6.1. Function list¶

The functions that are available in this module use multicased functions and aliases. For more information on this, please see Aliases and Multicased functions.

structure.by(name, *suffix, **options)¶

Return the structure with the given name.

Parameters:	name (str) – the name of the structure to return suffix – any other numbers or strings that should be appended to the name *options – if `offset` is specified, then use it as the base offset of the structure

structure.by(id, **options)

Return the structure with the specified id or index.

Parameters:	id (int or long) – the identifier or the index of the structure to return **options – if `offset` is specified, then use it as the base offset of the structure

structure.by(sptr, **options)

Return the structure for the specified sptr.

Parameters:	sptr (idaapi.struc_t or structure_t) – the `idaapi.struc_t` to return **options – if `offset` is specified, then use it as the base offset of the structure

structure.by(tinfo, **options)

Return the structure for the specified tinfo.

Parameters:	tinfo (idaapi.tinfo_t) – the `idaapi.tinfo_t` to return the structure for **options –

structure.by(**type)

Return the structure matching the keyword specified by type.

Parameters:	**type – any keyword that can be used to match the structure with

structure.by_identifier(identifier, **options)¶

Return the structure identified by identifier.

Aliases: structure.byid, structure.by_id, structure.byidentifier

Parameters:	identifier – the identifier of the structure to return **options – if `offset` is specified, then use it as the base offset of the structure

structure.by_index(index, **options)¶

Return a structure by its index.

Aliases: structure.byindex

Parameters:	index – the index of the structure to return **options – if `offset` is specified, then use it as the base offset of the structure

structure.by_name(name, *suffix, **options)¶

Return a structure by its name.

Aliases: structure.byname

Parameters:	name – the name of the structure to return suffix – any other numbers or strings that should be appended to the name *options – if `offset` is specified, then use it as the base offset of the structure

structure.comment(id, **repeatable)¶

Return the comment of the structure identified by id.

If the bool repeatable is specified, return the repeatable comment.

Parameters:	id (int or long) – the identifier of the structure **repeatable – whether the comment should be repeatable or not

structure.comment(structure, **repeatable)

Return the comment for the specified structure.

Parameters:	structure (structure_t) – the `structure_t` to return the comment for **repeatable – whether the comment should be repeatable or not

structure.comment(structure, cmt, **repeatable)

Set the comment to cmt for the specified structure.

Parameters:	structure (structure_t) – the `structure_t` to apply the comment to cmt (str) – the comment to apply **repeatable – whether the comment should be repeatable or not

structure.comment(structure, none, **repeatable)

Remove the comment from the specified structure.

Parameters:	structure (structure_t) – the `structure_t` to remove the comment from none (None) – the python value `None` **repeatable – whether the removed comment should be the repeatable one

structure.comment(id, cmt, **repeatable)

Set the comment of the structure identified by id to cmt.

If the bool repeatable is specified, set the repeatable comment.

Parameters:	id (int or long) – the identifier of the structure cmt (str) – the comment to apply **repeatable – whether the comment should be repeatable or not

structure.comment(id, none, **repeatable)

Remove the comment from the structure identified by id.

Parameters:	id (int or long) – the identifier of the structure none (None) – the python value `None` **repeatable – whether the removed comment should be the repeatable one

structure.fragment(structure, offset, **base)¶

Yield each member of the given structure from the specified offset as a tuple containing its attributes.

Parameters:	structure – the structure to yield the members from offset (int or long) – the starting offset of the fragment **base –

structure.fragment(structure, offset, size, **base)

Yield each member of the given structure from the specified offset up to size as a tuple containing its attributes.

Parameters:	structure – the structure to yield the members from offset (int or long) – the starting offset of the fragment size (int or long) – the size of the members to yield **base –

structure.fragment(id, offset, size, **base)

Yield each member of the structure with the specified id from the given offset up to size as a tuple containing its (offset, size, tags).

If the integer base is defined, then the offset of each member will be translated by the given value.

Parameters:	id (int or long) – the identifer of the structure to yield the members from offset (int or long) – the starting offset of the fragment size (int or long) – the size of the members to yield **base –

structure.has(id)¶

Return whether a structure with the specified id exists within the database.

Parameters:	id (int or long) – the identifier or the index of the structure to check

structure.has(name, *suffix)

Return if a structure with the specified name exists within the database.

Parameters:	name (str) – the name of the structure to check *suffix – any other numbers or strings that should be appended to the name

structure.has(structure)

Return whether the database includes the provided structure.

Parameters:	structure (idaapi.struc_t or structure_t) – the `idaapi.struc_t` or the `structure_t` to check

structure.index(id)¶

Return the index of the structure identified by id.

Parameters:	id (int or long) – the identifier of the structure to return the index for

structure.index(structure)

Return the index of the specified structure.

Parameters:	structure (structure_t) – the `structure_t` to return the index for

structure.index(id, index)

Move the structure identified by id to the specified index in the structure list.

Parameters:	id (int or long) – the identifier of the structure index (int or long) – the index to move the structure to

structure.index(structure, index)

Move the specified structure to the specified index in the structure list.

Parameters:	structure (structure_t) – the `structure_t` to move index (int or long) – the index to move the structure to

structure.is_frame(id)¶

Return whether the structure identified by id is a frame or not.

Aliases: structure.isframe, structure.frameQ

Parameters:	id (int or long) – the identifier of the structure to check

structure.is_frame(structure)

Return whether the provided structure is a frame or not.

Aliases: structure.isframe, structure.frameQ

Parameters:	structure (idaapi.struc_t or structure_t) – the `idaapi.struc_t` or `structure_t` to check

structure.is_union(id)¶

Return whether the structure identified by id is a union or not.

Aliases: structure.unionQ, structure.isunion

Parameters:	id (int or long) – the identifier of the structure to check

structure.is_union(structure)

Return whether the provided structure is defined as a union.

Aliases: structure.unionQ, structure.isunion

Parameters:	structure (idaapi.struc_t or structure_t) – the `idaapi.struc_t` or `structure_t` to check

structure.iterate(string, *suffix)¶

Iterate through all of the structures in the database with a glob that matches string.

Parameters:	string (str) – the glob to filter the structure names with *suffix – any other numbers or strings that should be appended to the name

structure.iterate(**type)

Iterate through all of the structures that match the keyword specified by type.

Parameters:	**type – any keyword that can be used to filter structures with

structure.list(string, *suffix)¶

List any structures that match the glob in string.

Parameters:	string (str) – the glob to filter the structure names with *suffix – any other numbers or strings that should be appended to the name

structure.list(**type)

List all the structures within the database that match the keyword specified by type.

Parameters:	**type – any keyword that can be used to filter structures with

structure.members(structure, **base)¶

Yield each member of the given structure as a tuple containing its attributes.

Parameters:	structure – the structure to yield the members from **base – a base address to translate the offset of each yielded member with

structure.members(id, **base)

Yield each member of the structure with the specified id as a tuple of containing its (offset, size, tags).

If the integer base is defined, then the offset of each member will be translated by the given value.

Parameters:	id (int or long) – the identifier of the structure to yield the members from **base – a base address to translate the offset of each yielded member with

structure.name(id)¶

Return the name of the structure identified by id.

Parameters:	id – the identifier of the structure to return the name of

structure.name(structure)

Parameters:	structure (structure_t) – the `structure_t` to return the name of

structure.name(id, string, *suffix)

Set the name of the structure identified by id to string.

Parameters:	id – the identifier of the structure to return the name for string (str) – the name to rename the structure to *suffix – any other numbers or strings to append to the base name

structure.name(structure, string, *suffix)

Set the name of the specified structure to string.

Parameters:	structure (structure_t) – the `structure_t` to rename string (str) – the name to rename the structure to *suffix – any other numbers or strings to append to the base name

structure.new(string, *suffix, **offset)¶

Return a new structure using the name specified by string.

If the integer offset is provided, then use it as the base offset for the newly created structure.

Parameters:	string (str or tuple) – a string to use as the name suffix – any other numbers or strings to append to the name *offset – the base offset of the structure that is being created

structure.remove(structure)¶

Remove the specified structure from the database.

Aliases: structure.delete

Parameters:	structure (structure_t) – the `structure_t` to remove from the database

structure.remove(name, *suffix)

Remove the structure with the specified name.

Aliases: structure.delete

Parameters:	name (str) – the name of the structure to remove from the database *suffix – any other numbers or strings that should be appended to the name

structure.remove(id)

Remove a structure by its index or id.

Aliases: structure.delete

Parameters:	id (int or long) – the identifier of the structure to remove from the database

structure.remove(**type)

Remove the first structure that matches the result described by type.

Aliases: structure.delete

Parameters:	**type – any keyword that can be used to match the structure with

structure.search(string, *suffix)¶

Search through all the structure names matching the glob string.

Parameters:	string (str) – the glob to match the structure name with *suffix – any other numbers or strings that should be appended to the name

structure.search(**type)

Search through all of the structures and return the first result matching the keyword specified by type.

Parameters:	**type – any keyword that can be used to filter the structures with

structure.select(tag, *And, **boolean)¶

Query all of the structure tags for the specified tag and any others specified as And.

Parameters:	tag (str) – a required tag name to search for And – any other required tag names *boolean – either `And` or `Or` which specifies required or optional tags (respectively)

structure.select(**boolean)

Query all the structures (linearly) for any tags specified by boolean. Yields each address found along with the matching tags as a dictionary.

If And contains an iterable then require the returned structure contains them. If Or contains an iterable then include any other tags that are specified.

Parameters:	**boolean – either `And` or `Or` which specifies required or optional tags (respectively)

structure.size(structure)¶

Return the size of the specified structure.

Parameters:	structure (structure_t) – the `structure_t` to return the size for

structure.size(id)

Return the size of the structure identified by id.

Parameters:	id (int or long) – the identifier of the structure to return the size for

3.1.6.2. Class list¶

Classes provide the definition necessary to instantiate an object. In most cases, a class is returned when calling one of the prior listed functions and thus have no need to be manually instantiated. Classes may also have aliases defined for them. Please refer to the documentation for the class to see what is available. For more information on aliases, please see Aliases.

3.1.6.2.1. member_t¶

class structure.member_t¶

This object is an abstraction around a single member belonging to a structure. A member within a structue contains a number of properties which this object will expose. Some of these properties allow for a user to modify the member’s type or name. The tag method is also provided to allow for a user to annotate the member similar to the database or a function’s contents. Another method, refs will allow one to enumerate everything in the database that references said member.

bounds¶

Parameters:	getter – Return the boundaries of the member.

comment¶

The comment of this member_t.

param repeatable:
param getter:	Return the repeatable comment of the member.
	whether the comment should be repeatable or not
param setter:	Set the repeatable comment of the member to `value`.
param value:	the comment to apply to the member
param repeatable:
	whether the comment should be repeatable or not

dt_type¶

The "dt_type" attribute of the idaapi.member_t that is wrapped by this member_t.

param getter:	Return the `dt_type` attribute of the member.

flag¶

The flags for this specific member_t.

param getter:	Return the “flag” attribute of the member.

fullname¶

The full name for this member_t including its structure’s name.

param getter:	Return the fullname of the member.

id¶

The member identifier for this member_t.

param getter:	Return the identifier of the member.

index¶

The index of this member_t into its structure.

param getter:	Return the index of the member.

left¶

The starting offset of the member_t.

param getter:	Return the beginning offset of the member.

name¶

The name of this member_t.

param getter:	Return the name of the member.
param setter:	Set the name of the member to `string`.
param string:	the new name to rename the member to

offset¶

Parameters:	getter – Return the offset of the member.

parent¶

Parameters:	getter – Return the structure_t that owns the member.

properties¶

The "props" field of the idaapi.member_t that this member_t wraps.

param getter:	Return the properties for the current member.

ptr¶

The idaapi.member_t that this member_t wraps.

param getter:	Return the pointer of the `idaapi.member_t`.

realbounds¶

The structure_t that owns this member_t.

param getter:	Return the real boundaries of the member.

realoffset¶

The offset of this member_t relative to the structure’s base offset.

param getter:	Return the real offset of the member.

right¶

The ending offset of the member_t (starting offset plus its size).

param getter:	Return the ending offset of the member.

size¶

The size of this member_t.

param getter:	Return the size of the member.

type¶

The pythonic type that is associated with this member_t.

param getter:	Return the type of the member in its pythonic form.
param setter:	Set the type of the member to the provided `type`.
param type:	the pythonic type to set the member type to

typeid¶

The type identifier for this member_t.

param getter:	Return the identifier of the type of the member.

typeinfo¶

Parameters:	getter – Return the type information of the current member. setter – Set the type information of the current member to `info`. info – the type information to apply to the member

refs(self)¶

Return the (address, opnum, type) of all the code and data references to this member within the database.

If opnum is None, then the returned address has the structure applied to it. If opnum is defined, then the instruction at the returned address references a field that contains the specified structure.

tag(self)¶: Return the tags associated with the member.

tag(self, key)

Return the tag identified by key belonging to the member.

Parameters:	key (str) – a string representing the tag name

tag(self, key, value)

Set the tag identified by key to value for the member.

Parameters:	key (str) – a string representing the tag name value – a python object to store at the tag

tag(self, key, none)

Removes the tag specified by key from the member.

Parameters:	key (str) – a string representing the tag name none (None) – the python value `None`

3.1.6.2.2. members_t¶

class structure.members_t¶

This object is an abstraction around all the members belonging to a specific IDA structure. This object is implicitly part of a structure_t and allows one to access each member of the structure by its index as well as create new members and remove existing ones from the structure.

To list the different members available in the structure, one can use structure.list with a chosen method of filtering. This will list all of the available members that match the keyword that they specified. The keywords that are available to filter members are:

name - Match the structure member by a name
offset - Match the structure member by its offset
like - Filter the structure members according to a glob
regex - Filter the structure members according to a regular-expression
index - Match the structure member by its index
fullname - Filter the structure members by matching its full name according to a glob
comment or comments - Filter the structure members by applying a glob to its comment
identifier or id - Match the structure member by its identifier
greater or ge - Filter the structure members for any after the specified offset (inclusive)
gt - Filter the structure members for any after the specified offset (exclusive)
less or le - Filter the structure members for any before the specified offset (inclusive)
lt - Filter the structure members for any before the specified offset (exclusive)
predicate - Filter the structure members by passing the member_t to a callable

Some examples of using these keywords are as follows:

> st.members.list('field_4*')
> iterable = st.members.iterate(like='p_*')
> result = st.members.by(offset=0x2a)

owner¶

The structure_t that owns this members_t.

param getter:	Return the owner `structure_t` for this `members_t`.

ptr¶

The idaapi.member_t that this members_t wraps.

param getter:	Return the pointer to the `idaapi.member_t` that contains all the members.

add(self, name)¶

Append the specified member name with the default type at the end of the structure.

Parameters:	name (str or tuple) – the name of the member to add

add(self, name, type)

Append the specified member name with the given type at the end of the structure.

Parameters:	name (str or tuple) – the name of the member to add type – the pythonic type of the new member to add

add(self, name, type, offset)

Add a member at offset with the given name and type.

To specify a particular size, type can be a tuple with the second element referring to the size.

Parameters:	name (str or tuple) – the name of the member to add type – the pythonic type of the new member to add offset (int or long) – the offset to add the member at

by(self, **type)¶

Return the member that matches the keyword specified by type.

Parameters:	**type – any keyword that can be used to match the structure member with

by(self, name, *suffix)

Return the member with the specified name.

Parameters:	name (str) – the name of the member to return *suffix – any other numbers or strings that should be appended to the name

by(self, offset)

Return the member at the specified offset.

Parameters:	offset (int or long) – the offset of the member to return

by(self, location)

Return the member at the specified location.

Parameters:	location (tuple) – a tuple containing the offset and exact size to use when locating the member

by_fullname(self, fullname, *suffix)¶

Return the member with the specified fullname.

Aliases: structure.members_t.byfullname

Parameters:	fullname – the full name of the member to return *suffix – any other numbers or strings that should be appended to the name

by_identifier(self, id)¶

Return the member in the structure that has the specified id.

Aliases: structure.members_t.byid, structure.members_t.by_id

Parameters:	id – the identifier of the member to return

by_name(self, name, *suffix)¶

Return the member with the specified name.

Aliases: structure.members_t.byname

Parameters:	name – the name of the member to return *suffix – any other numbers or strings that should be appended to the name

by_offset(self, offset)¶

Return the member at the specified offset from the base offset of the structure.

Aliases: structure.members_t.byoffset

Parameters:	offset – the offset of the member to return

by_realoffset(self, offset)¶

Return the member at the specified offset of the structure.

Aliases: structure.members_t.byrealoffset

Parameters:	offset – the real offset of the member to return

index(self, member)¶

Return the index of the specified member.

Parameters:	member – the `member_t` to return the index for

iterate(self, **type)¶

Iterate through all of the members in the structure that match the keyword specified by type.

Parameters:	**type – any keyword that can be used to filter the structure members with

iterate(self, string, *suffix)

Iterate through all of the members in the structure with a name that matches the glob in string.

Parameters:	string (str) – the glob to filter the structure member names with *suffix – any other numbers or strings that should be appended to the name

list(self, string, *suffix)¶

List any members that match the glob in string.

Parameters:	string (str) – the glob to filter the structure member names with *suffix – any other numbers or strings that should be appended to the name

list(self, **type)

List all the members within the structure that match the keyword specified by type.

Parameters:	**type – any keyword that can be used to filter the structure members with

near_offset(self, offset)¶

Return the member nearest to the specified offset from the base offset of the structure.

Aliases: structure.members_t.nearoffset, structure.members_t.near

Parameters:	offset – the offset nearest to the member to return

near_realoffset(self, offset)¶

Return the member nearest to the specified offset.

Parameters:	offset – the real offset nearest to the member to return

pop(self, index)¶

Remove the member at the specified index.

Parameters:	index – the index of the member to remove

remove(self, offset)¶

Remove the member at offset from the structure.

Parameters:	offset – the offset of the member to remove

remove(self, offset, size)

Remove all the members from the structure from the specified offset up to size bytes.

Parameters:	offset – the offset of the starting member to remove size – the size of the members that follow to remove

select(self, tag, *And, **boolean)¶

Query all of the members for the specified tag and any others specified as And.

Parameters:	tag (str) – a required tag name to search for And – any other required tag names *boolean – either `And` or `Or` which specifies required or optional tags (respectively)

select(self, **boolean)

Query all of the members (linearly) for any tags specified by boolean. Yields each member found along with the matching tags as a dictionary.

If And contains an iterable then require the returned members contains them. If Or contains an iterable then include any other tags that are specified.

Parameters:	**boolean – either `And` or `Or` which specifies required or optional tags (respectively)

3.1.6.2.3. structure_t¶

class structure.structure_t¶

This object is an abstraction around an IDA structure type. This allows for one to treat an IDA structure as a regular python object. A number of methods and properties are provided in order to access certain attributes of the structure.

To access the members belonging to the structure, one can use the members property. This property is intended to be treated as an array in order to access the different elements available. This property also allows a user to create a new member or remove an already existing one.

bounds¶

The interface.bounds_t describing the boundaries of this structure relative to its base offset.

param getter:

comment¶

The comment belonging to the structure_t.

param repeatable:
param getter:	Return the repeatable comment for the structure.

param setter:	Set the repeatable comment for the structure to `value`.
param value:	a string repesenting the comment to apply
param repeatable:
	whether the comment should be repeatable or not

id¶

The identifier for this structure_t.

param getter:	Return the identifier of the structure.

index¶

The index of this structure_t within the IDA’s structure list.

param getter:	Return the index of the structure.
param setter:	Set the index of the structure to `idx`.
param index:	the new index to move the structure to

members¶

The members_t for accessing the structure members.

param getter:	Return the members belonging to the structure.

name¶

The name of the structure_t.

param getter:	Return the name of the structure.
param setter:	Set the name of the structure to `string`.
param string:	a string representing the new name of the structure

offset¶

The base offset of the structure_t.

param getter:	Return the base offset of the structure.
param setter:	Set the base offset of the structure to `offset`.
param offset:	the new base offset to assign to the structure

ordinal¶

Parameters:	getter – Return the ordinal number of the structure within the current type library.

properties¶

The "props" field of the idaapi.struc_t that this structure_t wraps.

param getter:	Return the properties for the current structure.

ptr¶

The idaapi.struc_t that this structure_t wraps.

param getter:	Return the pointer of the `idaapi.struc_t`.

realbounds¶

The interface.bounds_t describing the boundaries of this structure.

param getter:

size¶

The total size of the structure_t.

param getter:	Return the size of the structure.
param setter:	Expand the structure to the new `size` that is specified.
param size:	an integer representing the new size to expand the structure to

typeinfo¶

Parameters:	getter – Return the type information of the current structure. setter – Sets the type information of the current structure to `info`. info –

contains(self, offset)¶

Return whether the specified offset is contained by the structure.

Parameters:	offset – the offset to check

destroy(self)¶: Remove the structure from the database.

field(self, offset)¶

Return the member at the specified offset.

Parameters:	offset – the offset of the member to return

refs(self)¶: Return all the structure members and operand references which reference this specific structure.

tag(self)¶: Return the tags associated with the structure.

tag(self, key)

Return the tag identified by key belonging to the structure.

Parameters:	key (str) – a string representing the tag name

tag(self, key, value)

Set the tag identified by key to value for the structure.

Parameters:	key (str) – a string representing the tag name value – a python object to store at the tag

tag(self, key, none)

Removes the tag specified by key from the structure.

Parameters:	key (str) – a string representing the tag name none (None) – the python value `None`

up(self)¶: Return all structure or frame members within the database that reference this particular structure.

3.1.6. structure – Structure module¶

3.1.6.1. Function list¶

3.1.6.2. Class list¶

3.1.6.2.1. member_t¶

3.1.6.2.2. members_t¶

3.1.6.2.3. structure_t¶

IDA-minsc

Navigation

Contents

Search

Indices

This Page