3.1.2. enumeration – Enumeration module

This module exposes a number of tools that can be used to interact with the enumerations or their members defined within the database. The base argument type for interacting with an enumeration is the enumeration identifier idaapi.enum_t. This is an opaque integer that will need to be passed to the different tools in order to reference the enumeration that the user is referring to.

There are a number of tools within the member namespace that can be used to enumerate or locate the members of an enumeration. As typically an enumeration is simply a constant, each result that is returned will either be a value or a name. The identifier for these is a idaapi.uval_t.

To list the different enumerations available in the database, one can use enumeration.list(...) specifying their preferred method of filtering. This will list all of the available enumerations at which point the user can then request it by passing an identifier to enumeration.by(...). The types that can be used to filter are as follows:

  • name - Match according to the enumeration name
  • like - Filter the enumeration names according to a glob
  • regex - Filter the enumeration names according to a regular-expression
  • index - Match the enumeration by its index
  • identifier or id - Match the enumeration by its identifier
  • predicate - Filter the enumerations by passing their identifier to a callable

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

enumeration.bitfield(enum)

Return whether the enumeration identified by enum is a bitfield or not.

Parameters:enum – the enumeration to return the bitfield flag for
enumeration.bitfield(enum, boolean)

Toggle the bitfield setting of the enumeration enum depending on the value of boolean.

Parameters:
  • enum – the enumeration to set the bitfield flag for
  • boolean (int or long or bool) – whether to set the flag or clear it
enumeration.bits(enum)

Return the number of bits for the enumeration enum.

Parameters:enum – the enumeration to return the width of
enumeration.bits(enum, width)

Set the number of bits for the enumeration enum to width.

Parameters:
  • enum – the enumeration to set the width for
  • width (int or long) – the number of bits to set the enumeration width to
enumeration.by(index)

Return the identifier for the enumeration at the specified index.

Parameters:index (int or long) – the index or id of the enumeration to return
enumeration.by(name)

Return the identifier for the enumeration with the specified name.

Parameters:name (str) – the name of the enumeration to return
enumeration.by(**type)

Return the identifier for the first enumeration matching the keyword specified by type.

Parameters:**type – any keyword that can be used to filter enumerations with
enumeration.by_identifier(eid)

Return the identifier for the enumeration using the specified eid.

Aliases: enumeration.byidentifier

Parameters:eid – the identifier of the enumeration to return
enumeration.by_index(index)

Return the identifier for the enumeration at the specified index.

Aliases: enumeration.byindex

Parameters:index – the index of the enumeration to return
enumeration.by_name(name)

Return the identifier for the enumeration with the given name.

Aliases: enumeration.byname

Parameters:name – the name of the enumeration to return
enumeration.comment(enum, **repeatable)

Return the comment for the enumeration enum.

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

Parameters:
  • enum – the enumeration to return the comment for
  • **repeatable – whether the returned comment should be repeatable or not
enumeration.comment(enum, comment, **repeatable)

Set the comment for the enumeration enum to comment.

If the bool repeatable is specified, then modify the repeatable comment.

Parameters:
  • enum – the enumeration to modify the comment for
  • comment (str) – the comment to apply
  • **repeatable – whether the comment should be repeatable or not
enumeration.comment(enum, none, **repeatable)

Remove the comment from the enumeration enum.

Parameters:
  • enum –
  • none (None) –
  • **repeatable –
enumeration.count()

Return the total number of enumerations in the database.

enumeration.delete(enum)

Delete the enumeration enum.

Aliases: enumeration.remove

Parameters:enum – the enumeration to remove
enumeration.flags(enum)

Return the flags for the enumeration identified by enum.

Parameters:enum – the enumeration to return the flags for
enumeration.flags(enum, flags)

Set the flags for the enumeration enum to the value specified by flags.

Parameters:
  • enum – the enumeration to return the flags for
  • flags (int or long) – the flags to apply to the enumeration
enumeration.has(enum)

Return truth if an enumeration with the identifier enum exists within the database.

Parameters:enum (int or long) – the enumeration identifier to check
enumeration.has(name)

Return truth if an enumeration with the specified name exists within the database.

Parameters:name (str) – the enumeration name to check
enumeration.index(enum)

Return the index in the enumeration list for the enumeration identified by enum.

Parameters:enum – the enumeration to return the index of
enumeration.index(enum, index)

Set the position in the enumeration list for the enumeration enum to the specified index.

Parameters:
  • enum – the enumeration to set the index for
  • index (int or long) – the index to change the enumeration to
enumeration.iterate(**type)

Iterate through all of the enumerations in the database that match the keyword specified by type.

Parameters:**type – any keyword that can be used to filter enumerations with
enumeration.list(string)

List any enumerations that match the glob in string.

Parameters:string (str) – the glob to filter the enumeration names with
enumeration.list(**type)

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

Parameters:**type – any keyword that can be used to filter enumerations with
enumeration.mask(enum)

Return the bitmask for the enumeration enum.

Parameters:enum – the enumeration to return the bitmask for
enumeration.name(enum)

Return the name of the enumeration enum.

Parameters:enum – the enumeration to return the name of
enumeration.name(enum, name)

Rename the enumeration enum to the string name.

Parameters:
  • enum – the enumeration to rename
  • name (str) – the name to rename the enumeration to
enumeration.names(enum)

Return a set of all of the names belonging to the enumeration enum.

Parameters:enum – the enumeration to return the names for
enumeration.new(name, flags=0)

Create an enumeration with the specified name and flags using idaapi.add_enum.

Aliases: enumeration.create

Parameters:
  • name – the name of the new enumeration
  • flags – any extra flags to pass to idaapi.add_enum
enumeration.repr(enum)

Return a printable summary of the enumeration enum.

Parameters:enum – the enumeration to summarize
enumeration.search(string)

Return the identifier of the first enumeration that matches the glob string.

Parameters:string (str) – the glob to match the enumeration name with
enumeration.search(**type)

Return the identifier of the first enumeration that matches the keyword specified by type.

Parameters:**type – any keyword that can be used to match an enumeration with
enumeration.size(enum)

Return the number of bytes for the enumeration enum.

Parameters:enum – the enumeration to return the width of
enumeration.size(enum, width)

Set the number of bytes for the enumeration enum to width.

Parameters:
  • enum – the enumeration to set the width for
  • width (int or long) – the number of bytes to set the enumeration width to
enumeration.up(enum)

Return all structure or frame members within the database that reference the specified enum.

Parameters:enum – the enumeration to return references for
enumeration.values(enum)

Return a set of all of the values belonging to the enumeration enum.

Parameters:enum – the enumeration to return the values of

3.1.2.2. Namespace list

These are the namespaces available within this module. Namespaces group similar functions that can be used typically for the same concept. Please see Classes as namespaces for more information on namespaces. For more information on multicase functions or aliases, please see Multicased functions or Aliases.

3.1.2.2.1. enumeration.masks

This namespace allows one to interact with a masks that are within an enumeration with its “bitfield” flag set. This is a very basic namespace that provides some minor utilities to deal with the naming of the bitmasks in an enumeration.

Some examples of how to use this namespace can be:

> values = enum.masks('example_enumeration')
> ok = enum.masks.has(eid, 'mask_name')
> mask = enum.masks.by(eid, 'mask_name')
> mask = enum.masks.by(eid, 0x1234)
enumeration.masks(enum)

Iterate through all of the masks belonging to the enumeration enum and yield their name and value.

Parameters:enum – the enumeration to return the masks of
masks.comment(enum, mask, **repeatable)

Return the comment for the mask belonging to the enumeration enum.

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

Parameters:
  • enum – the enumeration to fetch a mask comment from
  • mask (int or long) – the mask to fetch the comment from
  • **repeatable – whether to return the repeatable comment or not
masks.comment(enum, mask, comment, **repeatable)

Set the comment for the mask belonging to the enumeration enum to comment.

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

Parameters:
  • enum – the enumeration containing the mask to set the comment for
  • mask (int or long) – the mask to set the comment of
  • comment (str) – the comment to assign to the mask
  • **repeatable – whether to set the repeatable comment or not
masks.comment(enum, mask, none, **repeatable)

Remove the comment for the mask belonging to the enumeration enum.

Parameters:
  • enum – the enumeration containing the mask to clear the comment of
  • mask (int or long) – the mask to clear the comment of
  • none (None) – the python value None
  • **repeatable – whether to clear the repeatable comment or not
masks.has(enum, mask)

Return whether the enumeration enum uses the specified mask.

Parameters:
  • enum – the enumeration to check the masks of
  • mask – the bitmask to confirm
masks.iterate(enum)

Iterate through all of the masks belonging to the enumeration enum.

Parameters:enum – the enumeration to iterate through through the masks of
masks.list(enum)

List all the masks belonging to the enumeration identified by enum.

Parameters:enum – the enumeration containing the masks to list
masks.name(enum, mask)

Return the name for the given mask belonging to the enumeration enum.

Parameters:
  • enum – the enumeration containing the mask to fetch
  • mask (int or long) – the mask to return the name of
masks.name(enum, mask, name)

Set the name for the mask belonging to the enumeration enum to the provided name.

Parameters:
  • enum – the enumeration containing the mask to rename
  • mask (int or long) – the mask to set the name of
  • name (str or tuple) – the name to use when renaming the mask
masks.name(enum, mask, name, *suffix)

Set the name for the mask belonging to the enumeration enum to the provided name.

Parameters:
  • enum – the enumeration containing the mask to rename
  • mask (int or long) – the mask to set the name of
  • name (str) – the name to use when renaming the mask
  • *suffix – any other strings to append to the name

3.1.2.2.2. enumeration.member

This namespace allows one to interact with a member belonging to an enumeration once the enumeration’s id has been determined. This allows one to modify the property of any one of an enumeration’s members.

Some examples of how to use this namespace can be:

> eid = enum.by('example_enumeration')
> mid = enum.members.by_value(eid, 0x1000)
> oldname = enum.member.name(mid, 'somename')
> oldvalue = enum.member.value(mid, 0x100)
> oldcomment = enum.member.comment(mid, 'This is an example comment')
> ok = enum.member.remove(mid)
member.by(mid)

Return the enumeration member as specified by the provided mid.

Parameters:mid – the identifier of the member to return
member.comment(mid, **repeatable)

Return the comment for the enumeration member mid.

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

Parameters:
  • mid (int or long) – the identifier of an enumeration member to return the comment for
  • **repeatable – whether the returned comment should be repeatable or not
member.comment(enum, member, **repeatable)

Return the comment for the enumeration member belonging to enum.

Parameters:
  • enum – the enumeration containing the member to return the comment for
  • member – the member to return the comment for
  • **repeatable – whether the returned comment should be repeatable or not
member.comment(mid, comment, **repeatable)

Set the comment for the enumeration member id mid to comment.

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

Parameters:
  • mid (int or long) – the identifier of an enumeration containing the member to set the comment for
  • comment (str) – the comment to apply
  • **repeatable – whether the returned comment should be repeatable or not
member.comment(enum, member, comment, **repeatable)

Set the comment for the enumeration member belonging to enum to the string comment.

Parameters:
  • enum – the enumeration containing the member to set the comment for
  • member – the member to set the comment for
  • comment (str) – the comment to apply
  • **repeatable – whether the returned comment should be repeatable or not
member.comment(enum, member, none, **repeatable)

Remove the comment from the member belonging to the enumeration enum.

Parameters:
  • enum –
  • member –
  • none (None) –
  • **repeatable –
member.mask(mid)

Return the bitmask for the enumeration member mid.

Parameters:mid (int or long) – the identifier of an enumeration member to return the bitmask of
member.mask(enum, member)

Return the bitmask for the enumeration member belonging to enum.

Parameters:
  • enum – the enumeration containing the member to return the bitmask for
  • member – the member to return the bitmask for
member.name(mid)

Return the name of the enumeration member mid.

Parameters:mid (int or long) – the identifier of the member to return the name for
member.name(enum, member)

Return the name of the enumeration member belonging to enum.

Parameters:
  • enum – the enumeration containing the member to return the name for
  • member – the member to return the name for
member.name(mid, name)

Rename the enumeration member mid to name.

Aliases: enumeration.member.rename

Parameters:
  • mid (int or long) – the identifier of an enumeration member
  • name (str or tuple) – the name to rename the enumeration member to
member.name(enum, member, name, *suffix)

Rename the enumeration member belonging to enum to name.

Aliases: enumeration.member.rename

Parameters:
  • enum – the enumeration containing the member to rename
  • member – the member to rename
  • name (str) – the name to rename the enumeration member to
  • *suffix – any other names to append to the new name
member.parent(mid)

Return the id of the enumeration that owns the member mid.

Aliases: enumeration.member.owner

Parameters:mid – the identifier of the member to return the enumeration for
member.refs(mid)

Return the (address, opnum, type) of all the instructions that reference the enumeration member mid.

Parameters:mid – the enumeration member identifier to return references for
member.refs(enum, member)

Returns the (address, opnum, type) of all the instructions that reference the enumeration member belonging to enum.

Parameters:
  • enum – the enumeration to use
  • member – the member name or identifier to return references for
member.remove(mid)

Remove the enumeration member with the given mid.

Parameters:mid (int or long) – the identifier of the member to remove
member.remove(enum, member)

Remove the specified member of the enumeration enum.

Parameters:
  • enum – the enumeration to remove a member from
  • member – the member to remove
member.serial(mid)

Return the serial of the enumeration member mid.

Parameters:mid (int or long) – the identifier of an enumeration member to return the serial for
member.serial(enum, member)

Return the serial of the enumeration member belonging to enum.

Parameters:
  • enum – the enumeration containing the member to return the serial for
  • member – the member to return the serial of
member.value(mid)

Return the value of the enumeration member mid.

Parameters:mid (int or long) – the identifier of an enumeration member to return the value of
member.value(enum, member)

Return the value of the specified member belonging to the enumeration enum.

Parameters:
  • enum – the enumeration containing the member to return the value of
  • member – the member to return the value of
member.value(mid, value)

Assign the integer specified by value to the enumeration member mid.

Parameters:
  • mid (int or long) – the identifier of the member to set the value of
  • value (int or long) – the value to set the member to
member.value(enum, member, value, **bitmask)

Set the value for the enumeration member belonging to enum.

Parameters:
  • enum – the enumeration containing the member to set the value for
  • member – the member to set the value of
  • value (int or long) – the value to apply
  • **bitmask – if bitmask is specified as an integer, then use it as the bitmask to assign to the value

3.1.2.2.3. enumeration.members

This namespace allows one to interact with the members belonging to an enumeration once the enumeration’s id has been determined. This allows one to iterate through all of its members or add and remove values to the enumeration.

By default this namespace will yield the names of all of the members of an enumeration.

Some examples of using this namespace are:

> eid = enum.by('example_enumeration')
> mid = enum.members.add(eid, 'name', 0x1000)
> ok = enum.members.remove(eid, mid)
> mid = enum.members.by_name(eid, 'name')
> mid = enum.members.by_value(eid, 0x1000)
> for mid in enum.members.iterate(eid): ...
> enum.members.list(e)
enumeration.members(enum)

Yield the name, and value of each member from the enumeration enum.

If the enumeration enum is a bitfield, then yield each member’s name, value, and bitmask.

Parameters:enum – the enumeration to yield the names for
members.add(enum, name, value, **bitmask)

Add an enumeration member name with the specified value to the enumeration enum.

If the integral, bitmask, is specified then use it as the bitmask for the enumeration.

Aliases: enumeration.member.new, enumeration.member.create

Parameters:
  • enum – the enumeration to add a member to
  • name – the name of the enumeration member
  • value – the value of the enumeration member
  • **bitmask – if bitmask is specified as an integer, then use it as the bitmask for the enumeration
members.by(enum, n)

Return the member belonging to enum identified by its index or id in n.

Parameters:
  • enum – the enumeration to return a member for
  • n (int or long) – an index or an identifier of the enumeration to return
members.by(enum, name)

Return the member of the enumeration enum with the given name.

Parameters:
  • enum – the enumeration to return a member for
  • name (str) – the name of the member to return
members.by_identifier(enum, mid)

Return the member of the enumeration specified by enum and its mid.

Parameters:
  • enum – the enumeration to return a member for
  • mid – the identifier of the enumeration member to return
members.by_index(enum, index)

Return the member identifier for the member of the enumeration enum at the specified index.

Parameters:
  • enum – the enumeration to return a member for
  • index – the index of the enumeration member to return
members.by_name(enum, name)

Return the member identifier for the member of the enumeration enum with the specified name.

Aliases: enumeration.member.byname

Parameters:
  • enum – the enumeration to return a member for
  • name – the name of the enumeration member to return
members.by_value(enum, value, **filters)

Return the member identifier for the member of the enumeration enum with the specified value.

If the integrals, bitmask or serial, is specified then use them to filter the returned enumeration members.

Aliases: enumeration.member.byvalue

Parameters:
  • enum – the enumeration to return a member for
  • value – the value of the enumeration member to return
  • **filters – the filters to use when choosing the enumeration member
members.has(enum, name)

Return whether the enumeration enum contains a member with the specified name.

Parameters:
  • enum – the enumeration to use
  • name (str) – the name of the enumeration member to check
members.has(enum, value, **bitmask)

Return whether the enumeration enum contains a member with the specified value.

If an integral is provided for bitmask or serial, then only return true if the member is within the specified bitmask, or uses the provided serial.

Parameters:
  • enum – the enumeration to use
  • value (int or long) – the value of the enumeration member to check
  • **bitmask – if bitmask is specified as an integer, then check the value within the specified bitmask
members.iterate(enum)

Iterate through all ids of each member associated with the enumeration enum.

Parameters:enum – the enumeration containing the members to iterate through
members.list(enum)

List all the members belonging to the enumeration identified by enum.

Parameters:enum – the enumeration containing the members to list
members.mapping(enum)

Return a dictionary mapping all the values values to their names for the enumeration enum.

Parameters:enum – the enumeration containing the names and values to return
members.names(enum)

Return a set of all the names belonging to the enumeration enum.

Parameters:enum – the enumeration to return the names for
members.remove(mid)

Remove the member identified by mid from the enumeration that owns it.

Parameters:mid (int or long) –
members.remove(enum, member)

Remove the specified member of the enumeration enum.

Parameters:
  • enum – the enumeration containing the member to remove
  • member – the identifier or index of an enumeration member to remove
members.values(enum)

Return a set of all the values belonging to the enumeration enum.

If the enumeration is a bitfield, then each item in the result is the value and its bitmask.

Parameters:enum – the enumeration to return the values of