3.3.1. tags – Tags module

This module exposes tools for exporting the currently defined tags within the database. Once exported, these tags can then be pickled or then re-applied to the same or another database. Some options are allowed which will let a user apply translations to the tags before applying them to a target database.

To fetch all of the tags from the database:

> res = custom.tags.read()

To export only specific tags from the database:

> res = custom.tags.export('tag1', 'tag2', ...)

To apply previously read tags to the database:

> custom.tags.apply(res)

To apply previously read tags with different names to the database:

> custom.tags.apply(res, tag1='my_tag1', tag2='my_tag2', ...)

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

tags.addressToLocation(ea, chunks=None)

Convert the address ea to a (function, id, offset).

The fields id and offset represent the chunk index and the offset into the chunk for the function at ea. If the list chunks is specified as a parameter, then use it as a tuple of ranges in order to calculate the correct address.

Parameters:
  • ea – an address to possibly convert to a location
  • chunks – the list of chunks to convert the address with
tags.list()

Return the tags for the all of the function contents within the database as a set.

tags.locationToAddress(loc)

Convert the function location loc back into an address.

Parameters:loc – an address or a location tuple to convert to an address
tags.lvarNameQ(name)

Determine whether a name is something that IDA named automatically.

Parameters:name – the string to check for an IDA naming scheme

3.3.1.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.3.1.2.1. tags.apply

This namespace contains tools that can be used to apply tags that have been previously read back into the database.

Various functions defined within this namespace take a variable number of keyword arguments which represent a mapping for the tag names. When a tag name was specified, this mapping will be used to rename the tags before actually writing them back into the database.

tags.apply(Globals_Contents_Frames, **tagmap)

Apply the tags in the argument (Globals, Contents, Frames) from the Globals_Contents_Frames tuple back into the database.

Parameters:
  • Globals_Contents_Frames – a tuple composed of the global tags, contents tags, and frame members that were read
  • **tagmap – a dictionary used to translate the original tag names with before applying them to the database
apply.content(Contents, **tagmap)

Apply Contents back into a function’s contents within the database.

Parameters:
  • Contents – the contents tags to apply
  • **tagmap – a dictionary used to map the original tags with before applying them to the database
apply.contents(Contents, **tagmap)

Apply the tags in Contents back into each function within the database.

Parameters:
  • Contents – the contents tags to apply
  • **tagmap – a dictionary used to map the original tags with before applying them to the database
apply.everything(Globals_Contents_Frames, **tagmap)

Apply the tags in the argument (Globals, Contents, Frames) from the Globals_Contents_Frames tuple back into the database.

Parameters:
  • Globals_Contents_Frames – a tuple composed of the global tags, contents tags, and frame members that are to be applied
  • **tagmap – a dictionary used to translate the original tag names with before applying them to the database
apply.frame(ea, frame, **tagmap)

Apply the fields from frame back into the function at ea.

Parameters:
  • ea – the address of the function to apply the frame to
  • frame – the frame members to apply
  • **tagmap – a dictionary used to map the original tags with before applying them to the database
apply.frames(Frames, **tagmap)

Apply the fields from Frames back into each function’s frame.

Parameters:
  • Frames – the frame members to apply
  • **tagmap – a dictionary used to map the original tags with before applying them to the database
apply.globals(Globals, **tagmap)

Apply the tags in Globals back into the database.

Parameters:
  • Globals – the globals tags to apply
  • **tagmap – a dictionary used to map the original tags with before applying them to the database

3.3.1.2.2. tags.export

This namespace contains tools that can be used to quickly export specific tags out of the database using the cache.

If location is specified as true, then read each contents tag according to its location rather than an address. This allows one to perform a translation of the tags in case the function chunks are at different addresses than when the tags were read.

tags.export(*tags, **location)

Read the specified tags within the database using the cache.

Parameters:
  • *tags – an iterable of the tags to export
  • **location – if location is true, then export the contents tags as a location instead of an address
export.content(F, *tags, **location)

Iterate through the specified tags belonging to the contents of the function at ea using the cache.

Parameters:
  • F – the function to export the content from
  • *tags – an iterable of the contents tags to export
  • **location – if location is true, then export the contents tags as a location instead of an address
export.contents(*tags, **location)

Iterate through the specified contents tags within the database using the cache.

Each iteration yields a tuple of the format (location, tags) where location can be either an address or a chunk identifier and offset depending on whether location was specified as true or not.

Parameters:
  • *tags – an iterable of the contents tags to export
  • **location – if location is true, then export the contents tags as a location instead of an address
export.everything(*tags, **location)

Read all of the specified tags within the database using the cache.

Returns a tuple of the format (Globals, Contents, Frames). Each field is a dictionary keyed by location or offset that retains the tags that were read. If the boolean location was specified then key each contents tag by location instead of address.

Parameters:
  • *tags – an iterable of the tags to export
  • **location – if location is true, then export the contents tags as a location instead of an address
export.frame(F, *tags)

Iterate through each field containing the specified tags within the frame belonging to the function ea.

Parameters:
  • F – the function to export the frame members from
  • *tags – an iterable of the tags used to select the frame members to export
export.frames(*tags)

Iterate through the fields in each function’s frame containing the specified tags.

Parameters:*tags – an iterable of the tags used to select the frame members to export
export.globals(*tags)

Iterate through all of the specified global tags within the database using the cache.

Parameters:*tags – an iterable of the global tags to export

3.3.1.2.3. tags.read

This namespace contains tools that can be used to manually read tags out of the database without using the cache.

If location is specified as true, then read each contents tag according to its location rather than an address. This allows one to perform a translation of the tags in case the function chunks are at different addresses than when the tags were read.

tags.read(location=False)

Read all of the tags defined within the database.

Parameters:location – whether to read the contents tags as an address or a location
read.content(ea)

Iterate through every tag belonging to the contents of the function at ea.

Parameters:ea – the address of the function to yield the content for
read.contents(location=False)

Iterate through the contents tags for all the functions within the database.

Each iteration yields a tuple of the format (location, tags) where location can be either an address or a chunk identifier and offset depending on whether location was specified as true or not.

Parameters:location – whether to read the contents tags as an address or a location
read.everything(location=False)

Read all of the tags defined within the database.

Returns a tuple of the format (Globals, Contents, Frames). Each field is a dictionary keyed by location or offset that retains the tags that were read. If the boolean location was specified then key each contents tag by location instead of address.

Parameters:location – whether to read the contents tags as an address or a location
read.frame(ea)

Iterate through each field within the frame belonging to the function ea.

Parameters:ea – the address of the function containing the frame members to yield
read.frames()

Iterate through the fields of each frame for all the functions defined within the database.

read.globals()

Iterate through all of the tags defined globally witin the database.