Pro.Carbon — API for disassembling and decompiling native binaries

Overview

The Pro.Carbon module contains the API for disassembling and decompiling native binaries.

Carbon is an ultra-fast disassembler specifically designed for malware triage and for handling vast amount of data such as memory images and crash dumps.

Carbon is also extremely flexible: the address space represented by a single Carbon database can contain modules with different formats and multiple architectures. Moreover, a single analysis project in Cerbero Suite can contain multiple Carbon databases, even for the same file.

Core Concepts

Some of the most important classes are:

  • Carbon - This is the main class of Carbon. It provides the API for synchronous and asynchronous code analysis.

  • CarbonDB - This class handles the Carbon database.

  • CarbonLoader - This is the base class which Python extensions inherit to create Carbon loaders.

  • CarbonBasicTypeInfo - This class provides information about basic Carbon types such as integers and strings.

  • CarbonSleighDecompiler - This class provides an interface to use the Sleigh decompiler.

Note

The database type used by Carbon is SQLite3. The reason for this is not only reliability, but also the possibility for external code to access Carbon databases without the use of the Carbon API.

String Decryption

While string decryption is a very specific use-case, this section introduces important concepts when working with the Carbon API.

Let’s take as example the following C program:

#include <stdio.h>

unsigned char s1[13] = { 0x84, 0xA9, 0xA0, 0xA0, 0xA3, 0xE0, 0xEC, 0xBB, 0xA3, 0xBE, 0xA0, 0xA8, 0xED };
unsigned char s2[13] = { 0x84, 0xA9, 0xA0, 0xA0, 0xA3, 0xE0, 0xEC, 0xBB, 0xA3, 0xBE, 0xA0, 0xA8, 0xED };
unsigned char s3[13] = { 0x84, 0xA9, 0xA0, 0xA0, 0xA3, 0xE0, 0xEC, 0xBB, 0xA3, 0xBE, 0xA0, 0xA8, 0xED };

char *decrypt(unsigned char *s, size_t n)
{
    for (size_t i = 0; i < n; i++)
        s[i] ^= 0xCC;
    return (char *) s;
}

#define DS(s) decrypt(s, sizeof (s))

int main()
{
    puts(DS(s1));
    puts(DS(s2));
    puts(DS(s3));
    return 0;
}

In the dissembled output the decryption and output calls might look as follows:

0x0041145E        push   0xD
0x00411460        push   0x418000
0x00411465        call   decrypt
0x0041146A        add    esp, 8
0x0041146D        mov    esi, esp
0x0041146F        push   eax
0x00411470        call   dword ptr [0x419114] -> puts

The Carbon API offers various possible approaches to find all occurrences of encrypted strings. It would be possible, for instance, to enumerate all disassembled instructions. However, that’s not very efficient. A better approach is to get all cross references to the decrypt function and then proceed from there.

0x0041114A decrypt proc start
0x0041114A                                        ; CODE XREF: 0x00411465
0x0041114A                                        ; CODE XREF: 0x00411487
0x0041114A                                        ; CODE XREF: 0x004114A9
0x0041114A        jmp    sub_4113C0

The first step is to get the instance of the Carbon class. In this case, we’re retrieving it from the current analysis view.

from Pro.UI import proContext, ProView

view = proContext().getCurrentAnalysisView()
if view.type() == ProView.Type_Carbon:
    ca = view.getCarbon()

From there we can retrieve all the cross references to the decrypt function.

db = ca.getDB()
xrefs = db.getXRefs(0x0041114A, True)

Then we enumerate all cross references and we extract address and length of each string.

it = xrefs.iterator()
while it.hasNext():
    xref = it.next()
    # retrieve address and length of the string
    buf = ca.read(xref.origin - 6, 6)
    slen = buf[0]
    saddr = struct.unpack_from("<I", buf, 2)[0]

We decrypt each string.

s = ca.read(saddr, slen)
s = bytes([c ^ 0xCC for c in s]).decode("utf-8")

At this point we could add a comment to each push instruction referencing the string address with the decrypted string.

comment = caComment()
comment.address = xref.origin - 5
comment.text = s
db.setComment(comment)

As a final touch, we update the view, in order to reflect the changes we made to the underlying database.

view.update()

This would already create readable disassembly and decompiler outputs.

// decompiled code
void __stdcall _main(void)
{
    unk32_t uVar1;

    // Hello, world!
    uVar1 = decrypt(0x418000, 0xD);
    (*_puts)(uVar1);
    // Hello, world!
    uVar1 = decrypt(0x418010, 0xD);
    (*_puts)(uVar1);
    // Hello, world!
    uVar1 = decrypt(0x418020, 0xD);
    (*_puts)(uVar1);
    return;
}

Another solution would be to patch the strings in place with their decrypted counterparts. We can do this, since the decrypted size of a string matches the encrypted size.

ca.write(saddr, s)

This produces an even better result when decompiling.

void __stdcall main(void)
{
    unk32_t uVar1;

    uVar1 = decrypt("Hello, world!", 0xD);
    (*_puts)(uVar1);
    uVar1 = decrypt("Hello, world!", 0xD);
    (*_puts)(uVar1);
    uVar1 = decrypt("Hello, world!", 0xD);
    (*_puts)(uVar1);
    return;
}

Important

The method Carbon.write() is safe to use, since it doesn’t overwrite the original binary, but only bytes in the Carbon database.

Our final script for string decryption:

from Pro.UI import proContext, ProView
from Pro.Carbon import caComment
import struct

def decryptStrings():
    view = proContext().getCurrentAnalysisView()
    if view.type() == ProView.Type_Carbon:
        ca = view.getCarbon()
        db = ca.getDB()
        xrefs = db.getXRefs(0x0041114A, True)
        it = xrefs.iterator()
        while it.hasNext():
            xref = it.next()
            # retrieve the address and length of the string
            buf = ca.read(xref.origin - 6, 6)
            slen = buf[0]
            saddr = struct.unpack_from("<I", buf, 2)[0]
            s = ca.read(saddr, slen)
            s = bytes([c ^ 0xCC for c in s])
            # add comment
            comment = caComment()
            comment.address = xref.origin - 5
            comment.text = s.decode("utf-8")
            db.setComment(comment)
            # patch in place
            ca.write(saddr, s)
            # update the view
            view.update()

decryptStrings()

Disassembling Files

To disassemble a file programmatically is very simple:

from Pro.Core import *
from Pro.Carbon import *
from Pro.PE import *
import time

def disassemble(fname):
    s = createContainerFromFile(fname)
    if s.isNull():
        return False
    obj = PEObject()
    if not obj.Load(s):
        return False
    dbname = r"path/to/db"
    c = Carbon()
    c.setObject(obj, True)
    if c.createDB(dbname) != CARBON_OK:
        # couldn't create the database
        return False
    if c.load() != CARBON_OK:
        # couldn't load the file format in Carbon
        return False
    # start multi-threaded analysis
    c.resumeAnalysis()
    while c.isAnalyzing():
        time.sleep(0.1)
    return True

disassemble(r"path/to/exe")

Decompiling Functions

The following code decompiles a function using the Sleigh decompiler.

from Pro.UI import proContext, ProView
from Pro.Carbon import CarbonSleighDecompiler

def decompile(addr):
    view = proContext().getCurrentAnalysisView()
    if view.type() != ProView.Type_Carbon:
        return None
    ca = view.getCarbon()
    dec = CarbonSleighDecompiler(ca)
    return dec.decompileToString(addr)

s = decompile(0x00411440)
print(s)

Important

The address passed to CarbonDecompilerInterface.decompileToString() must be of a defined function.

Our multiprocessing module can be used to execute the decompiler in another process.

Creating Loaders

All our Carbon file format loaders are written in Python and can be found in the application folder ‘sdk/python/Pro/CarbonLdrs’.

For example, what follows is our file loader for raw binary blobs such as shellcode.

from Pro.Carbon import *

class RawLoader(CarbonLoader):

    def __init__(self):
        super(RawLoader, self).__init__()

    def load(self):
        # get parameters
        p = self.carbon().getParameters()
        try:
            arch = int(p.value("arch", str(CarbonType_I_x86)), 16)
        except:
            print("carbon error: invalid arch")
            arch = CarbonType_I_x86
        try:
            base = int(p.value("base", "0"), 16)
        except:
            print("carbon error: invalid base address")
            base = 0
        # load
        db = self.carbon().getDB()
        obj = self.carbon().getObject()
        # add region
        e = caRegion()
        e.def_type_id = arch
        e.flags = caRegion.READ | caRegion.WRITE | caRegion.EXEC
        e.start = base
        e.end = e.start + obj.GetSize()
        e.offset = 0
        db.addRegion(e)
        return CARBON_OK

def newRawLoader():
    return RawLoader()

The file loader is only a few lines of code. Writing a loader for a file format is usually not much more work: currently the loader for Portable Executable files is about 450 lines of code.

The configuration file to add your own loaders is called ‘caloaders.cfg’.

Hint

The best starting point to create a new file format loader is to use an existing loader as a template.

Module API

Pro.Carbon module API.

Attributes:

CARBON_ABORTED

Carbon error code.

CARBON_ARRAY_TOO_BIG_ERROR

Carbon error code.

CARBON_BUSY

Carbon error code.

CARBON_CLASH_ERROR

Carbon error code.

CARBON_DB_ERROR

Carbon error code.

CARBON_ERROR

Carbon error code.

CARBON_LOADER_ERROR

Carbon error code.

CARBON_MAX_REGION_CHUNK_SIZE

The maximum size for a region data chunk.

CARBON_NOT_PAUSED

Carbon error code.

CARBON_NULL

Carbon error code.

CARBON_OK

Carbon error code.

CARBON_PDB_FILE_ERROR

Carbon error code.

CARBON_PDB_FORMAT_ERROR

Carbon error code.

CARBON_RANGE_ERROR

Carbon error code.

CARBON_READ_ERROR

Carbon error code.

CARBON_REGION_DATA_TOO_BIG_ERROR

Carbon error code.

CARBON_UNSUPPORTED_ARCH

Carbon error code.

CARBON_UNSUPPORTED_FORMAT

Carbon error code.

CarbonDBOpt_ReadOnly

Opens a database as read-only.

CarbonType_I_ARM32

ARM32 data type.

CarbonType_I_ARM32_BE

ARM32 big-endian data type.

CarbonType_I_ARM32_LE

ARM32 little-endian data type.

CarbonType_I_ARM64

ARM64 data type.

CarbonType_I_ARM64_BE

ARM64 big-endian data type.

CarbonType_I_ARM64_LE

ARM64 little-endian data type.

CarbonType_I_Thumb

ARM-Thumb data type.

CarbonType_I_Thumb_BE

ARM-Thumb big-endian data type.

CarbonType_I_Thumb_LE

ARM-Thumb little-endian data type.

CarbonType_I_x64

x64 data type.

CarbonType_I_x86

x86 data type.

CarbonType_I_x86_16

x86 16-bit data type.

CarbonType_Invalid

Invalid data type.

CarbonType_N_d64

64-bit floating number data type.

CarbonType_N_d64_be

64-bit floating number big-endian data type.

CarbonType_N_d64_le

64-bit floating number little-endian data type.

CarbonType_N_f32

32-bit floating number data type.

CarbonType_N_f32_be

32-bit floating number big-endian data type.

CarbonType_N_f32_le

32-bit floating number little-endian data type.

CarbonType_N_i128

128-bit signed integer data type.

CarbonType_N_i128_be

128-bit signed integer big-endian data type.

CarbonType_N_i128_le

128-bit signed integer little-endian data type.

CarbonType_N_i16

16-bit signed integer data type.

CarbonType_N_i16_be

16-bit signed integer big-endian data type.

CarbonType_N_i16_le

16-bit signed integer little-endian data type.

CarbonType_N_i32

32-bit signed integer data type.

CarbonType_N_i32_be

32-bit signed integer big-endian data type.

CarbonType_N_i32_le

32-bit signed integer little-endian data type.

CarbonType_N_i64

64-bit signed integer data type.

CarbonType_N_i64_be

64-bit signed integer big-endian data type.

CarbonType_N_i64_le

64-bit signed integer little-endian data type.

CarbonType_N_i8

8-bit signed integer data type.

CarbonType_N_ptr16

16-bit pointer data type.

CarbonType_N_ptr16_be

16-bit pointer big-endian data type.

CarbonType_N_ptr16_le

16-bit pointer little-endian data type.

CarbonType_N_ptr32

32-bit pointer data type.

CarbonType_N_ptr32_be

32-bit pointer big-endian data type.

CarbonType_N_ptr32_le

32-bit pointer little-endian data type.

CarbonType_N_ptr64

64-bit pointer data type.

CarbonType_N_ptr64_be

64-bit pointer big-endian data type.

CarbonType_N_ptr64_le

64-bit pointer little-endian data type.

CarbonType_N_u128

128-bit unsigned integer data type.

CarbonType_N_u128_be

128-bit unsigned integer big-endian data type.

CarbonType_N_u128_le

128-bit unsigned integer little-endian data type.

CarbonType_N_u16

16-bit unsigned integer data type.

CarbonType_N_u16_be

16-bit unsigned integer big-endian data type.

CarbonType_N_u16_le

16-bit unsigned integer little-endian data type.

CarbonType_N_u32

32-bit unsigned integer data type.

CarbonType_N_u32_be

32-bit unsigned integer big-endian data type.

CarbonType_N_u32_le

32-bit unsigned integer little-endian data type.

CarbonType_N_u64

64-bit unsigned integer data type.

CarbonType_N_u64_be

64-bit unsigned integer big-endian data type.

CarbonType_N_u64_le

64-bit unsigned integer little-endian data type.

CarbonType_N_u8

8-bit unsigned integer data type.

CarbonType_S_ascii

Ascii string data type.

CarbonType_S_utf16

UTF-16 string data type.

CarbonType_S_utf16_be

UTF-16 string big-endian data type.

CarbonType_S_utf16_le

UTF-16 string little-endian data type.

CarbonType_S_utf32

UTF-32 string data type.

CarbonType_S_utf32_be

UTF-32 string big-endian data type.

CarbonType_S_utf32_le

UTF-32 string little-endian data type.

CarbonType_S_utf8

UTF-8 string data type.

DBGSYMOPT_ALL

Mask for all the debug symbol options.

DBGSYMOPT_IMPTYPES

Imports types into the local Carbon header.

DBGSYMOPT_IMPTYPES_GLOBAL

Imports types into the project header.

Classes:

Carbon()

This is the main class of Carbon and it provides the API for synchronous and asynchronous code analysis.

CarbonBasicTypeInfo(type_id)

This class provides information about built-in types.

CarbonDB()

This class handles the Carbon SQLite3 database.

CarbonDataResolver()

A helper class which uses heuristics to detect data types such as string literals.

CarbonDecompilerInterface(carbon)

This class represents the decompiler interface inherited by classes to provide decompiler functionality.

CarbonLoader()

This class represents the interface to implement file format loaders.

CarbonLoaderOptions()

This class contains options for the loader.

CarbonSleighDecompiler(carbon)

This class uses the Sleigh decompiler as a back-end decompiler.

CarbonUIContext()

An opaque class which represents the UI context for a Carbon view.

caASEntry()

This class represents an individual entry in the address space.

caAction()

This class represents an analysis action.

caActionsVisitor()

This class must be inherited to obtain a visitor for the actions queue.

caBelongingEntriesVisitor()

This class must be inherited to obtain a visitor for the belonging address space entries.

caComment()

This class represents a comment.

caCommon()

This class is inherited by those classes which rely on a SQLite3 provided index rather than defining their own unique index.

caDataValue()

This class represents a data value.

caEntryPoint()

This class represents an entry point.

caExceptionRecord()

This class represents an exception record.

caExceptionRecordList()

List of caExceptionRecord elements.

caExceptionRecordListIt(obj)

Iterator class for caExceptionRecordList.

caExport()

This class represents an exported symbol.

caFlaggedLocation()

This class represents a flagged location.

caFlaggedLocationList()

List of caFlaggedLocation elements.

caFlaggedLocationListIt(obj)

Iterator class for caFlaggedLocationList.

caFunction()

This class represents a function.

caFunctionsVisitor()

This class must be inherited to obtain a function visitor.

caImport()

This class represents an imported symbol.

caIntValue()

This class represents an integer value.

caLabel()

This class represents a label.

caLabelsVisitor()

TODO

caModule()

This class represents a module.

caModuleList()

List of caModule elements.

caModuleListIt(obj)

Iterator class for caModuleList.

caPage()

This class represents a memory page.

caRegion()

This class represents a memory region.

caRegionList()

List of caRegion elements.

caRegionListIt(obj)

Iterator class for caRegionList.

caReloc()

This class represents a relocation.

caStringValue()

This class represents a string value.

caType()

This class represents a custom type.

caVariable()

This class represents a variable.

caVariableList()

List of caVariable elements.

caVariableListIt(obj)

Iterator class for caVariableList.

caXRef()

This class represents a cross reference.

caXRefList()

List of caXRef elements.

caXRefListIt(obj)

Iterator class for caXRefList.

CARBON_ABORTED: Final[int]

Carbon error code.

CARBON_ARRAY_TOO_BIG_ERROR: Final[int]

Carbon error code.

CARBON_BUSY: Final[int]

Carbon error code.

CARBON_CLASH_ERROR: Final[int]

Carbon error code.

CARBON_DB_ERROR: Final[int]

Carbon error code.

CARBON_ERROR: Final[int]

Carbon error code.

CARBON_LOADER_ERROR: Final[int]

Carbon error code.

CARBON_MAX_REGION_CHUNK_SIZE: Final[int]

The maximum size for a region data chunk.

Available since Cerbero Suite 6.2 and Cerbero Engine 3.2.

CARBON_NOT_PAUSED: Final[int]

Carbon error code.

CARBON_NULL: Final[int]

Carbon error code.

CARBON_OK: Final[int]

Carbon error code.

CARBON_PDB_FILE_ERROR: Final[int]

Carbon error code.

CARBON_PDB_FORMAT_ERROR: Final[int]

Carbon error code.

CARBON_RANGE_ERROR: Final[int]

Carbon error code.

CARBON_READ_ERROR: Final[int]

Carbon error code.

CARBON_REGION_DATA_TOO_BIG_ERROR: Final[int]

Carbon error code.

Available since Cerbero Suite 6.2 and Cerbero Engine 3.2.

CARBON_UNSUPPORTED_ARCH: Final[int]

Carbon error code.

CARBON_UNSUPPORTED_FORMAT: Final[int]

Carbon error code.

class Carbon

This is the main class of Carbon and it provides the API for synchronous and asynchronous code analysis.

See also CarbonDB.

Methods:

analyzeRange(start, end)

Synchronously analyzes a range in the address space.

analyzeRangeAsync(start, end[, wo])

Asynchronously analyzes a range in the address space.

closeDB()

Closes the database.

createDB(dbname)

Creates a new database.

defineData(address_or_start, end_or_type_id)

Defines as data a range in the address space.

executeAction(uictx, cmd)

Executes an action in the Carbon UI context.

getDB()

Returns the database instance.

getHeaderFileName()

Returns the local header file name.

getObject()

Returns the internal Pro.Core.CFFObject.

getParameters()

Returns the parameters.

getProjectHeaderFileName()

Returns the project header file name.

isAnalyzing()

Returns True if an analysis in being performed; otherwise returns False.

isNull()

Returns True if the internal database is null; otherwise returns False.

isValid()

Returns True if the internal database is valid; otherwise returns False.

load()

Loads the object specified by setObject().

loadOptions()

Returns the options for the loader.

loadPDB(pdb_or_pdb_name, image_base[, options])

Loads debug symbols and types from a PDB file.

loadUI(uictx)

Loads the UI for the current Carbon loader.

makeCode(address_or_start[, end])

Synchronously defines code.

makeCodeAs(address_or_start, def_type_id_or_end)

Synchronously defines code with a specified type.

makeCodeAsAsync(address_or_start, …[, …])

Asynchronously defines code with a specified type.

makeCodeAsync(address_or_start[, end])

Asynchronously defines code.

openDB(dbname[, options])

Opens an existing database.

pauseAnalysis()

Pauses the analysis.

pauseAndRestartAnalysis()

Pauses and resumes the analysis.

read(address, size)

Reads data from the address space.

resumeAnalysis()

Resumes the analysis.

setLoadOptions(opts)

Sets the options for the loader.

setObject(weak_ptr_obj[, clone])

Sets the internal Pro.Core.CFFObject.

setParameters(params)

Sets the parameters.

setProjectHeaderFileName(fname)

Sets the project header file name.

toContainer([make_contiguous])

Returns the address space in the shape as a Pro.Core.NTContainer.

undefine(address_or_start[, end])

Synchronously undefines data in the address space.

undefineAsync(address_or_start[, end])

Asynchronously undefines data in the address space.

visitBelongingEntries(address, visitor)

Enumerates entries belonging to an address.

write(address, data)

Writes data to the address space.

analyzeRange(start: int, end: int)int

Synchronously analyzes a range in the address space.

Parameters
  • start (int) – The start address.

  • end (int) – The end address.

Returns

Returns CARBON_OK if successful; otherwise returns a different error code.

Return type

int

See also analyzeRangeAsync() and makeCodeAs().

analyzeRangeAsync(start: int, end: int, wo: Optional[Pro.Core.NTIWait] = None)int

Asynchronously analyzes a range in the address space.

Parameters
  • start (int) – The start address.

  • end (int) – The end address.

  • wo (NTIWait) – The wait object.

Returns

Returns CARBON_OK if successful; otherwise returns a different error code.

Return type

int

See also analyzeRange(), makeCodeAsAsync() and isAnalyzing().

closeDB()None

Closes the database.

See also createDB(), openDB() and getDB().

createDB(dbname: str)int

Creates a new database.

Parameters

dbname (str) – The name of the database to create.

Returns

Returns CARBON_OK if successful; otherwise returns a different error code.

Return type

int

See also openDB(), closeDB() and getDB().

defineData(address_or_start: int, end_or_type_id: int, type_id: Optional[int] = None)int

Defines as data a range in the address space.

Parameters
  • address_or_start (int) – The start address.

  • end_or_type_id (int) – The start address or the data type.

  • type_id (Optional[int]) – The data type.

Returns

Returns CARBON_OK if successful; otherwise returns a different error code.

Return type

int

See also undefine() and undefineAsync().

executeAction(uictx: Pro.Carbon.CarbonUIContext, cmd: int)None

Executes an action in the Carbon UI context.

This method internally calls CarbonLoader.executeAction().

Parameters
  • uictx (CarbonUIContext) – The UI context.

  • cmd (int) – The command to execute.

See also CarbonLoader.executeAction().

getDB()Pro.Carbon.CarbonDB
Returns

Returns the database instance.

Return type

CarbonDB

See also openDB(), createDB() and closeDB().

getHeaderFileName()str
Returns

Returns the local header file name.

Return type

str

See also getProjectHeaderFileName().

getObject()object
Returns

Returns the internal Pro.Core.CFFObject.

Return type

object

See also setObject().

getParameters()Pro.Core.NTUTF8StringHash
Returns

Returns the parameters.

Return type

NTUTF8StringHash

See also setParameters().

getProjectHeaderFileName()str
Returns

Returns the project header file name.

Return type

str

See also setProjectHeaderFileName() and getHeaderFileName().

isAnalyzing()bool
Returns

Returns True if an analysis in being performed; otherwise returns False.

Return type

bool

See also resumeAnalysis(), pauseAnalysis() and analyzeRangeAsync().

isNull()bool
Returns

Returns True if the internal database is null; otherwise returns False.

Return type

bool

See also isValid().

isValid()bool
Returns

Returns True if the internal database is valid; otherwise returns False.

Return type

bool

See also isNull().

load()int

Loads the object specified by setObject().

Returns

Returns CARBON_OK if successful; otherwise returns a different error code.

Return type

int

See also CarbonLoader.

loadOptions()Pro.Carbon.CarbonLoaderOptions
Returns

Returns the options for the loader.

Return type

CarbonLoaderOptions

Available since Cerbero Suite 6.2 and Cerbero Engine 3.2.

See also setLoadOptions() and CarbonLoaderOptions.

loadPDB(pdb_or_pdb_name: Union[PDBObject, str], image_base: int, options: int = DBGSYMOPT_ALL)int

Loads debug symbols and types from a PDB file.

Parameters
  • pdb_or_pdb_name (Union[PDBObject, str]) – The path of a PDB file or the PDB object.

  • image_base (int) – The image base of the module referred by the PDB.

  • options (int) – The load options.

Returns

Returns CARBON_OK if successful; otherwise returns a different error code.

Return type

int

loadUI(uictx: Pro.Carbon.CarbonUIContext)None

Loads the UI for the current Carbon loader.

This method internally calls CarbonLoader.loadUI().

Parameters

uictx (CarbonUIContext) – The UI context.

See also CarbonLoader.loadUI().

makeCode(address_or_start: int, end: Optional[int] = None)int

Synchronously defines code.

Parameters
  • address_or_start (int) – Either the address or the start address.

  • end (Optional[int]) – The end address.

Returns

Returns CARBON_OK if successful; otherwise returns a different error code.

Return type

int

See also makeCodeAs(), makeCodeAsync() and makeCodeAsAsync().

makeCodeAs(address_or_start: int, def_type_id_or_end: int, def_type_id: Optional[int] = None)int

Synchronously defines code with a specified type.

Parameters
  • address_or_start (int) – Either the address or the start address.

  • def_type_id_or_end (int) – Either the end address or the architecture type.

  • def_type_id (Optional[int]) – The architecture type.

Returns

Returns CARBON_OK if successful; otherwise returns a different error code.

Return type

int

See also makeCode(), makeCodeAsync() and makeCodeAsAsync().

makeCodeAsAsync(address_or_start: int, def_type_id_or_end: int, def_type_id: Optional[int] = None)int

Asynchronously defines code with a specified type.

Parameters
  • address_or_start (int) – Either the address or the start address.

  • def_type_id_or_end (int) – Either the end address or the architecture type.

  • def_type_id (Optional[int]) – The architecture type.

Returns

Returns CARBON_OK if successful; otherwise returns a different error code.

Return type

int

See also makeCodeAsync(), makeCode() and makeCodeAs().

makeCodeAsync(address_or_start: int, end: Optional[int] = None)int

Asynchronously defines code.

Parameters
  • address_or_start (int) – Either the address or the start address.

  • end (Optional[int]) – The end address.

Returns

Returns CARBON_OK if successful; otherwise returns a different error code.

Return type

int

See also makeCodeAsAsync(), makeCode() and makeCodeAs().

openDB(dbname: str, options: int = 0)int

Opens an existing database.

Parameters
  • dbname (str) – The name of the database to open.

  • options (int) – The options for opening the database (e.g., CarbonDBOpt_ReadOnly).

Returns

Returns CARBON_OK if successful; otherwise returns a different error code.

Return type

int

See also createDB(), closeDB() and getDB().

pauseAnalysis()int

Pauses the analysis.

Returns

Returns CARBON_OK if successful; otherwise returns a different error code.

Return type

int

See also resumeAnalysis() and isAnalyzing().

pauseAndRestartAnalysis()int

Pauses and resumes the analysis.

Returns

Returns CARBON_OK if successful; otherwise returns a different error code.

Return type

int

See also pauseAnalysis(), resumeAnalysis() and isAnalyzing().

read(address: int, size: int)bytes

Reads data from the address space.

This method takes into account changes made by calling write().

Parameters
  • address (int) – The address of the data to read.

  • size (int) – The size of the data to read.

Returns

Returns the requested bytes if successful; otherwise returns an empty bytes object.

Return type

bytes

See also write() and toContainer().

resumeAnalysis()int

Resumes the analysis.

Returns

Returns CARBON_OK if successful; otherwise returns a different error code.

Return type

int

See also pauseAnalysis() and isAnalyzing().

setLoadOptions(opts: Pro.Carbon.CarbonLoaderOptions)None

Sets the options for the loader.

Parameters

opts (CarbonLoaderOptions) – The options.

Available since Cerbero Suite 6.2 and Cerbero Engine 3.2.

See also loadOptions() and CarbonLoaderOptions.

setObject(weak_ptr_obj: Pro.Core.CFFObject, clone: bool = False)None

Sets the internal Pro.Core.CFFObject.

Parameters
  • weak_ptr_obj (CFFObject) – The object to set.

  • clone (bool) – If True, clones the object.

Important

The object must remain allocated as long as the Carbon instance references it. Unless clone is set to True, in which case this method creates an internal clone of the object.

See also getObject().

setParameters(params: Pro.Core.NTUTF8StringHash)None

Sets the parameters.

Note

Parameters are automatically retrieved from the XML string passed to Pro.Core.ScanProvider.addNativeCodeEntry().

For example:

self.addNativeCodeEntry(SEC_Intrinsic, "<carbon loader='PE'/>", "x64")
Parameters

params (NTUTF8StringHash) – The parameters.

See also getParameters().

setProjectHeaderFileName(fname: str)None

Sets the project header file name.

Parameters

fname (str) – The file name of the project header.

See also getProjectHeaderFileName().

toContainer(make_contiguous: bool = True)Pro.Core.NTContainer

Returns the address space in the shape as a Pro.Core.NTContainer.

The container uses the read() and write() and thus writing to it results in changes to the database and not to the internal Pro.Core.CFFObject.

Parameters

make_contiguous (bool) – If True, returns the address space without empty regions.

Returns

Returns the container if successful; otherwise returns an invalid container.

Return type

NTContainer

See also read() and write().

undefine(address_or_start: int, end: Optional[int] = None)int

Synchronously undefines data in the address space.

Parameters
  • address_or_start (int) – Either the address or the start address.

  • end (Optional[int]) – The end address.

Returns

Returns True if successful; otherwise returns False.

Return type

int

See also undefineAsync().

undefineAsync(address_or_start: int, end: Optional[int] = None)int

Asynchronously undefines data in the address space.

Parameters
  • address_or_start (int) – Either the address or the start address.

  • end (Optional[int]) – The end address.

Returns

Returns True if successful; otherwise returns False.

Return type

int

See also undefine().

visitBelongingEntries(address: int, visitor: Pro.Carbon.caBelongingEntriesVisitor)bool

Enumerates entries belonging to an address.

This method can be used to enumerate referenced code blocks.

Parameters
Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also caBelongingEntriesVisitor.

write(address: int, data: bytes)bool

Writes data to the address space.

This method modifies the database and doesn’t modify the data of the internal Pro.Core.CFFObject.

Parameters
  • address (int) – The address at which to write the data.

  • data (bytes) – The data to write.

Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also read() and toContainer().

class CarbonBasicTypeInfo(type_id: int)

This class provides information about built-in types.

For example:

from Pro.Carbon import *

ti = CarbonBasicTypeInfo(CarbonType_I_ARM32_BE)
print(ti.typeName())
print(ti.isCode())
print(ti.endianness() == caType.CA_BIG_ENDIAN)

Outputs:

arm32_be
True
True
Parameters

type_id (int) – The type id.

Methods:

endianness()

Returns the endianness of the type (caType.CA_LITTLE_ENDIAN or caType.CA_BIG_ENDIAN) if specified; otherwise returns 0.

isCode()

Returns True if the type represents code; otherwise returns False.

isData()

Returns True if the type represents data; otherwise returns False.

isPointer()

Returns True if the type represents a pointer; otherwise returns False.

isString()

Returns True if the type represents a string; otherwise returns False.

name()

Returns the fully qualified name of the type.

size()

Returns the granular size of the type.

typeName()

Returns the short name of the type.

endianness()int
Returns

Returns the endianness of the type (caType.CA_LITTLE_ENDIAN or caType.CA_BIG_ENDIAN) if specified; otherwise returns 0.

Return type

int

isCode()bool
Returns

Returns True if the type represents code; otherwise returns False.

Return type

bool

isData()bool
Returns

Returns True if the type represents data; otherwise returns False.

Return type

bool

isPointer()bool
Returns

Returns True if the type represents a pointer; otherwise returns False.

Return type

bool

isString()bool
Returns

Returns True if the type represents a string; otherwise returns False.

Return type

bool

name()str
Returns

Returns the fully qualified name of the type.

Return type

str

See also typeName().

size()int
Returns

Returns the granular size of the type.

Return type

int

typeName()str
Returns

Returns the short name of the type.

Return type

str

See also name().

class CarbonDB

This class handles the Carbon SQLite3 database.

Methods:

addASEntry(e)

Adds an entry in the address space.

addAction(e)

Adds an action to the action queue.

addComment(e)

Adds a comment.

addEntryPoint(e[, make_code])

Adds an entry point.

addExceptionRecord(e[, data_xref_origin])

Adds an exception record.

addExport(e)

Adds an exported symbol.

addFunction(e[, make_code_with_xref_type])

Adds a function.

addImport(e[, add_label])

Adds an imported symbol.

addLabel(e)

Adds a label.

addModule(e[, analyze])

Adds a module.

addPage(e)

Adds a memory page.

addProcessedQueueEntry(e)

Adds an item to the list of processed entries.

addQueueEntry(e[, timestamp])

Adds an entry to the queue of entries to process.

addRegion(e)

Adds a region of the address space.

addRegionData(region_id, data)

Saves the data for a region in the database.

addReloc(e)

Adds a relocation.

addType(e)

Adds a type.

addVariable(e)

Adds a variable.

addXRef(e)

Adds a cross reference.

addressFromLine(i)

Converts a line to an address.

addressSpaceRange()

Returns the range of the address space.

addressSpaceSize()

Returns the size of the address space.

addressToOffset(address)

Converts an address to an offset.

beginTransaction()

Begins an SQL transaction.

computeFunctionFromOwnedAddress(address, e)

Retrieves a function from an address in it.

create(dbname)

Creates a new database.

dataBaseFileName()

Returns the database file name.

endTransaction()

Ends an SQL transaction.

flush()

Flushes changes to the database.

getASEntry(address, e)

Retrieves an address space entry by its address.

getASEntryByEnd(address, e)

Retrieves an address space entry by its end address.

getASEntryCount()

Returns the number of address space entries.

getActionCount()

Returns the number of queued actions.

getCachedDefaultEndianness()

Returns the cached default endianness of the database (caType.CA_LITTLE_ENDIAN or caType.CA_BIG_ENDIAN).

getCachedModules()

Returns the list of cached modules.

getCachedPageSize()

Returns the cached page size.

getCachedRegions()

Returns the list of cached regions.

getClashingASEntry(_from, e)

Retrieves an address space entry clashing with a specified address.

getClosestFunction(address, e)

Retrieves the closest function to an address.

getComment(address, e)

Retrieves a comment at a specified address.

getDataValue(key[, deflt])

Retrieves a data value.

getDataValueEx(key, e)

Retrieves a data value.

getDefaultEndianness()

Returns the default endianness of the database (caType.CA_LITTLE_ENDIAN or caType.CA_BIG_ENDIAN).

getEntryPoint(id, e)

Retrieves an entry point entry by its id.

getExceptionRecordsByAddress(address[, sort])

Retrieves a list of exception records from their address.

getExceptionRecordsByOwner(owner[, sort])

Retrieves a list of exception records from their owner address.

getExport(id, e)

Retrieves an exported symbol by its id.

getFirstModule(e)

Retrieves the first module added to the address space.

getFlaggedLocation(address, e)

Retrieves a flagged location by its address.

getFlaggedLocations([mask, sort])

Retrieves all flagged locations.

getFunction(address, e)

Retrieves a function by its address.

getFunctionByEndAddress(end, e)

Retrieves a function by its end address.

getHandle()

Returns the internal SQLite3 handle.

getImport(id, e)

Retrieves an imported symbol by its id.

getImportByAddress(address, e)

Retrieves an imported symbol by its address.

getIntValue(key[, deflt])

Retrieves an integer value.

getIntValueEx(key, e)

Retrieves an integer value.

getLabel(address, e)

Retrieves a label by its address.

getModule(id, e)

Retrieves a module by its id.

getModules([sort])

Retrieves the list of modules.

getNewestAction(e)

Retrieves the newest action based on its timestamp.

getNextASEntry(_from, e)

Retrieves an address space entry starting at or after the specified address.

getNextAddress(_from, e)

Retrieves the next address in the address space.

getNextQueueEntry(e[, timestamp])

Retrieves the next entry in queue.

getPage(address, e)

Retrieves a memory page by its address.

getPageCount()

Returns the number of memory pages.

getPrevASEntry(_from, e)

Retrieves the first address space entry before the specified address.

getPrevAddress(_from, e)

Retrieves the previous address in the address space.

getRegion(id, e)

Retrieves a region by its id.

getRegionData(region_id, data)

Retrieves the data of a region from the database.

getRegions([sort])

Retrieves the list of regions.

getStringValue(key[, deflt])

Retrieves a string value.

getStringValueEx(key, e)

Retrieves a string value.

getVariables(function[, type])

Retrieves a list of variables by their function address.

getXRef(id, e)

Retrieves a cross reference by its id.

getXRefs(address, only_code)

Retrieves a list of cross references by their address.

getXRefsByOrigin(origin, only_code)

Retrieves a list of cross references by their origin address.

hasXRefs(address)

Checks whether an address is cross referenced.

isAddressValid(address)

Check whether an address is valid.

isContiguousAddressSpace()

Returns True if the address space is contiguous; otherwise returns False.

isModified()

Returns True if the database was modified; otherwise returns False.

isNull()

Returns True if the database is invalid; otherwise returns False.

isQueueEnabled()

Returns True if the queue is enabled; otherwise returns False.

isValid()

Returns True if the database is valid; otherwise returns False.

lineFromAddress(address)

Converts an address into a line number.

load()

Initializes the database.

moduleFromAddress(address)

Retrieves the module which contains the specified address.

nextRegionFromAddress(obj, address)

Retrieves the region located after a specified address.

open(dbname[, options])

Opens a database.

prevRegionFromAddress(obj, address)

Retrieves the region located before a specified address.

regionFromAddress(obj, address)

Retrieves the region which contains the specified address.

removeASEntry(start)

Removes an address space entry.

removeAction(id)

Removes an action entry.

removeAllProcessedQueueEntries()

Removes all entries from the processed queue.

removeFlaggedLocation(address)

Removes a flagged location.

removeFunction(address[, remove_vars])

Removes a function.

removeLabel(address)

Removes a label.

removeQueueEntry(id)

Removes a queue entry.

removeVariable(id)

Removes a variable.

removeVariables(function)

Remove variables belonging to a function.

removeXRefByOrigin(origin)

Removes cross references by their origin address.

rollbackTransaction()

Rolls back an SQL transaction.

setComment(e)

Adds or updates a comment.

setContiguousAddressSpaceRange(start, end)

Set the contiguous address space range.

setDataValue(key, value)

Sets a data value.

setDefaultEndianness(def_endianness)

Sets the default endianness of the address space.

setFlaggedLocation(e)

Adds or updates a flagged location.

setFunction(e)

Updates a function.

setFunctionSignature(address, signature)

Updates a function signature.

setIntValue(key, value)

Sets an integer value.

setLabel(e)

Adds or updates a label.

setModified(b)

Sets the modification status of the database.

setModuleFlags(id, flags)

Updates the flags for a specified module.

setPage(e)

Adds or updates a memory page.

setQueueEnabled(b)

Sets the enabled status of the analysis queue.

setStringValue(key, value)

Sets a string value.

visitActionQueue(visitor)

Enumerates the entries of the action queue.

visitBelongingEntries(source, address, visitor)

Enumerates entries belonging to an input address.

visitFunctions(visitor)

Enumerates functions.

visitLabels(visitor)

TODO

addASEntry(e: Pro.Carbon.caASEntry)bool

Adds an entry in the address space.

Parameters

e (caASEntry) – The entry to add.

Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also removeASEntry().

addAction(e: Pro.Carbon.caAction)bool

Adds an action to the action queue.

Parameters

e (caAction) – The action to add.

Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also removeAction().

addComment(e: Pro.Carbon.caComment)bool

Adds a comment.

Parameters

e (caComment) – The comment to add.

Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also setComment().

addEntryPoint(e: Pro.Carbon.caEntryPoint, make_code: bool = True)bool

Adds an entry point.

Parameters
  • e (caEntryPoint) – The entry point to add.

  • make_code (bool) – If True, adds the entry point to the analysis queue.

Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also getEntryPoint().

addExceptionRecord(e: Pro.Carbon.caExceptionRecord, data_xref_origin: int = INVALID_STREAM_OFFSET)bool

Adds an exception record.

Parameters
  • e (caExceptionRecord) – The exception record to add.

  • data_xref_origin (int) – The optional data cross reference for the exception record.

Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also getExceptionRecordsByAddress() and getExceptionRecordsByOwner().

addExport(e: Pro.Carbon.caExport)bool

Adds an exported symbol.

Parameters

e (caExport) – The exported symbol to add.

Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also getExport().

addFunction(e: Pro.Carbon.caFunction, make_code_with_xref_type: Optional[int] = None)bool

Adds a function.

Parameters
  • e (caFunction) – The function to add.

  • make_code_with_xref_type (Optional[int]) – If specified (e.g., caXRef.AUTO), adds the function to the analysis queue.

Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also setFunction() and removeFunction().

addImport(e: Pro.Carbon.caImport, add_label: bool = True)bool

Adds an imported symbol.

Parameters
  • e (caImport) – The imported symbol to add.

  • add_label (bool) – If True, adds a label to the address of the symbol.

Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also getImport().

addLabel(e: Pro.Carbon.caLabel)bool

Adds a label.

Parameters

e (caLabel) – The label to add.

Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also getLabel(), setLabel() and removeLabel().

addModule(e: Pro.Carbon.caModule, analyze: bool = True)bool

Adds a module.

Parameters
  • e (caModule) – The module to add.

  • analyze (bool) – If True, adds an analysis action with the address range of the module.

Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also getModule(), moduleFromAddress() and getModules().

addPage(e: Pro.Carbon.caPage)bool

Adds a memory page.

Parameters

e (caPage) – The memory page to add.

Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also getPage(), setPage(), Carbon.read() and Carbon.write().

addProcessedQueueEntry(e: Pro.Carbon.caXRef)bool

Adds an item to the list of processed entries.

Parameters

e (caXRef) – The item to add.

Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also removeAllProcessedQueueEntries().

addQueueEntry(e: Pro.Carbon.caXRef, timestamp: int = 0)bool

Adds an entry to the queue of entries to process.

Note

Entries are only added to the queue if the queue is enabled (see setQueueEnabled()).

Parameters
  • e (caXRef) – The entry to add.

  • timestamp (int) – The timestamp of the entry (see caAction).

Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also addAction(), removeQueueEntry() and setQueueEnabled().

addRegion(e: Pro.Carbon.caRegion)bool

Adds a region of the address space.

Parameters

e (caRegion) – The region to add.

Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also getRegion(), regionFromAddress() and getRegions().

addRegionData(region_id: int, data: Union[Pro.Core.NTContainer, bytes])bool

Saves the data for a region in the database.

Parameters
  • region_id (int) – The region id.

  • data (Union[NTContainer, bytes]) – The data of the region.

Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also getRegionData().

addReloc(e: Pro.Carbon.caReloc)bool

Adds a relocation.

Parameters

e (caReloc) – The relocation to add.

Returns

Returns True if successful; otherwise returns False.

Return type

bool

addType(e: Pro.Carbon.caType)bool

Adds a type.

Parameters

e (caType) – The type to add.

Returns

Returns True if successful; otherwise returns False.

Return type

bool

addVariable(e: Pro.Carbon.caVariable)bool

Adds a variable.

Parameters

e (caVariable) – The variable to add.

Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also getVariables(), removeVariable() and removeVariables().

addXRef(e: Pro.Carbon.caXRef)bool

Adds a cross reference.

Parameters

e (caXRef) – The cross reference to add.

Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also getXRef(), getXRefs() and getXRefsByOrigin().

addressFromLine(i: int)int

Converts a line to an address.

Parameters

i (int) – The line number.

Returns

Returns the address.

Return type

int

See also lineFromAddress().

addressSpaceRange()Pro.Core.NTOffsetRange
Returns

Returns the range of the address space.

Return type

NTOffsetRange

See also addressSpaceSize(), addRegion() and setContiguousAddressSpaceRange().

addressSpaceSize()int
Returns

Returns the size of the address space.

Return type

int

See also addressSpaceRange().

addressToOffset(address: int)int

Converts an address to an offset.

Parameters

address (int) – The address to convert.

Returns

Returns the offset if successful; otherwise returns Pro.Core.INVALID_STREAM_OFFSET.

Return type

int

See also regionFromAddress().

beginTransaction()None

Begins an SQL transaction.

See also endTransaction() and rollbackTransaction().

computeFunctionFromOwnedAddress(address: int, e: Pro.Carbon.caFunction)bool

Retrieves a function from an address in it.

Parameters
  • address (int) – The address in the function.

  • e (caFunction) – The retrieved function.

Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also getClosestFunction().

create(dbname: str)bool

Creates a new database.

Parameters

dbname (str) – The file name of the database.

Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also open().

dataBaseFileName()str
Returns

Returns the database file name.

Return type

str

endTransaction()None

Ends an SQL transaction.

See also beginTransaction() and rollbackTransaction().

flush()None

Flushes changes to the database.

getASEntry(address: int, e: Pro.Carbon.caASEntry)bool

Retrieves an address space entry by its address.

Parameters
  • address (int) – The address of the entry.

  • e (caASEntry) – The entry.

Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also getNextASEntry(), getPrevASEntry() and getClashingASEntry().

getASEntryByEnd(address: int, e: Pro.Carbon.caASEntry)bool

Retrieves an address space entry by its end address.

Parameters
  • address (int) – The end address of the entry.

  • e (caASEntry) – The entry.

Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also getASEntry(), getNextASEntry() and getPrevASEntry().

getASEntryCount()int
Returns

Returns the number of address space entries.

Return type

int

See also addASEntry().

getActionCount()int
Returns

Returns the number of queued actions.

Return type

int

See also addAction().

getCachedDefaultEndianness()int
Returns

Returns the cached default endianness of the database (caType.CA_LITTLE_ENDIAN or caType.CA_BIG_ENDIAN).

Return type

int

See also setDefaultEndianness() and getDefaultEndianness().

getCachedModules()Pro.Carbon.caModuleList
Returns

Returns the list of cached modules.

Return type

caModuleList

See also getModules().

getCachedPageSize()int
Returns

Returns the cached page size.

Return type

int

getCachedRegions()Pro.Carbon.caRegionList
Returns

Returns the list of cached regions.

Return type

caRegionList

See also getRegions().

getClashingASEntry(_from: int, e: Pro.Carbon.caASEntry)bool

Retrieves an address space entry clashing with a specified address.

Parameters
  • _from (int) – The address.

  • e (caASEntry) – The clashing address space entry.

Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also getASEntry(), getNextASEntry() and getPrevASEntry().

getClosestFunction(address: int, e: Pro.Carbon.caFunction)bool

Retrieves the closest function to an address.

Parameters
  • address (int) – The address.

  • e (caFunction) – The retrieved function.

Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also computeFunctionFromOwnedAddress().

getComment(address: int, e: Pro.Carbon.caComment)bool

Retrieves a comment at a specified address.

Parameters
  • address (int) – The address.

  • e (caComment) – The retrieved comment.

Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also addComment() and setComment().

getDataValue(key: str, deflt: bytes = bytes())bytes

Retrieves a data value.

Parameters
  • key (str) – The name of the data value.

  • deflt (bytes) – The default value.

Returns

Returns the requested value if present; otherwise returns deflt.

Return type

bytes

See also setDataValue() and getDataValueEx().

getDataValueEx(key: str, e: Pro.Carbon.caDataValue)bool

Retrieves a data value.

Parameters
  • key (str) – The name of the data value.

  • e (caDataValue) – The retrieved data value.

Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also setDataValue() and getDataValue().

getDefaultEndianness()int
Returns

Returns the default endianness of the database (caType.CA_LITTLE_ENDIAN or caType.CA_BIG_ENDIAN).

Return type

int

See also setDefaultEndianness() and getCachedDefaultEndianness().

getEntryPoint(id: int, e: Pro.Carbon.caEntryPoint)bool

Retrieves an entry point entry by its id.

Parameters
  • id (int) – The entry point id.

  • e (caEntryPoint) – The retrieved entry point.

Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also addEntryPoint().

getExceptionRecordsByAddress(address: int, sort: bool = True)Pro.Carbon.caExceptionRecordList

Retrieves a list of exception records from their address.

Parameters
  • address (int) – The address.

  • sort (bool) – If True, sorts the list by the exception record type.

Returns

Returns the list of exception records.

Return type

caExceptionRecordList

See also getExceptionRecordsByOwner() and addExceptionRecord().

getExceptionRecordsByOwner(owner: int, sort: bool = True)Pro.Carbon.caExceptionRecordList

Retrieves a list of exception records from their owner address.

Parameters
  • owner (int) – The owner address.

  • sort (bool) – If True, sorts the list by the exception record type.

Returns

Returns the list of exception records.

Return type

caExceptionRecordList

See also getExceptionRecordsByAddress() and addExceptionRecord().

getExport(id: int, e: Pro.Carbon.caExport)bool

Retrieves an exported symbol by its id.

Parameters
  • id (int) – The exported symbol id.

  • e (caExport) – The retrieved exported symbol.

Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also addExport().

getFirstModule(e: Pro.Carbon.caModule)bool

Retrieves the first module added to the address space.

Parameters

e (caModule) – The retrieved module.

Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also getModule(), getModules() and moduleFromAddress().

getFlaggedLocation(address: int, e: Pro.Carbon.caFlaggedLocation)bool

Retrieves a flagged location by its address.

Parameters
  • address (int) – The address.

  • e (caFlaggedLocation) – The retrieved flagged location.

Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also setFlaggedLocation() and getFlaggedLocations().

getFlaggedLocations(mask: int = 0, sort: bool = True)Pro.Carbon.caFlaggedLocationList

Retrieves all flagged locations.

Parameters
Returns

Returns the list of flagged locations.

Return type

caFlaggedLocationList

See also getFlaggedLocation() and setFlaggedLocation().

getFunction(address: int, e: Pro.Carbon.caFunction)bool

Retrieves a function by its address.

Parameters
  • address (int) – The address.

  • e (caFunction) – The retrieved function.

Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also getFunctionByEndAddress(), addFunction() and setFunction().

getFunctionByEndAddress(end: int, e: Pro.Carbon.caFunction)bool

Retrieves a function by its end address.

Parameters
  • end (int) – The end address.

  • e (caFunction) – The retrieved function.

Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also getFunction().

getHandle()sqlite3
Returns

Returns the internal SQLite3 handle.

Return type

sqlite3

getImport(id: int, e: Pro.Carbon.caImport)bool

Retrieves an imported symbol by its id.

Parameters
  • id (int) – The imported symbol id.

  • e (caImport) – The retrieved imported symbol.

Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also getImportByAddress() and addImport().

getImportByAddress(address: int, e: Pro.Carbon.caImport)bool

Retrieves an imported symbol by its address.

Parameters
  • address (int) – The imported symbol address.

  • e (caImport) – The retrieved imported symbol.

Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also getImport() and addImport().

getIntValue(key: str, deflt: int = 0)int

Retrieves an integer value.

Parameters
  • key (str) – The name of the integer value.

  • deflt (int) – The default value.

Returns

Returns the requested value if present; otherwise returns deflt.

Return type

int

See also setIntValue() and getIntValueEx().

getIntValueEx(key: str, e: Pro.Carbon.caIntValue)bool

Retrieves an integer value.

Parameters
  • key (str) – The name of the integer value.

  • e (caIntValue) – The retrieved integer value.

Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also setIntValue() and getIntValue().

getLabel(address: int, e: Pro.Carbon.caLabel)bool

Retrieves a label by its address.

Parameters
  • address (int) – The label address.

  • e (caLabel) – The retrieved label.

Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also addLabel() and setLabel().

getModule(id: int, e: Pro.Carbon.caModule)bool

Retrieves a module by its id.

Parameters
  • id (int) – The module id.

  • e (caModule) – The retrieved module.

Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also getModules() and moduleFromAddress().

getModules(sort: bool = True)Pro.Carbon.caModuleList

Retrieves the list of modules.

Parameters

sort (bool) – If True, sorts the returned list of modules.

Returns

Returns the list of modules.

Return type

caModuleList

See also getModule() and moduleFromAddress().

getNewestAction(e: Pro.Carbon.caAction)bool

Retrieves the newest action based on its timestamp.

Parameters

e (caAction) – The retrieved action.

Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also addAction().

getNextASEntry(_from: int, e: Pro.Carbon.caASEntry)bool

Retrieves an address space entry starting at or after the specified address.

Parameters
  • _from (int) – The input address.

  • e (caASEntry) – The retrieved address space entry.

Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also getPrevASEntry(), getASEntry() and getClashingASEntry().

getNextAddress(_from: int, e: Pro.Carbon.caASEntry)bool

Retrieves the next address in the address space.

The difference with getNextASEntry() is that this method returns unallocated space as well as address space entries.

Parameters
  • _from (int) – The input address.

  • e (caASEntry) – The retrieved address space entry or a single byte of unallocated space.

Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also getPrevAddress() and getNextASEntry().

getNextQueueEntry(e: Pro.Carbon.caXRef, timestamp: Optional[int] = None)bool

Retrieves the next entry in queue.

Parameters
  • e (caXRef) – The retrieved entry.

  • timestamp (Optional[int]) – An optional timestamp to be matched.

Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also addQueueEntry() and setQueueEnabled().

getPage(address: int, e: Pro.Carbon.caPage)bool

Retrieves a memory page by its address.

Parameters
  • address (int) – The page address.

  • e (caPage) – The retrieved page.

Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also addPage(), setPage(), Carbon.read() and Carbon.write().

getPageCount()int
Returns

Returns the number of memory pages.

Return type

int

See also addPage(), getPage(), Carbon.read() and Carbon.write().

getPrevASEntry(_from: int, e: Pro.Carbon.caASEntry)bool

Retrieves the first address space entry before the specified address.

Parameters
  • _from (int) – The input address.

  • e (caASEntry) – The retrieved address space entry.

Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also getNextASEntry(), getASEntry() and getClashingASEntry().

getPrevAddress(_from: int, e: Pro.Carbon.caASEntry)bool

Retrieves the previous address in the address space.

The difference with getPrevASEntry() is that this method returns unallocated space as well as address space entries.

Parameters
  • _from (int) – The input address.

  • e (caASEntry) – The retrieved address space entry or a single byte of unallocated space.

Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also getNextAddress() and getPrevASEntry().

getRegion(id: int, e: Pro.Carbon.caRegion)bool

Retrieves a region by its id.

Parameters
  • id (int) – The region id.

  • e (caRegion) – The retrieved region.

Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also getRegions(), addRegion() and regionFromAddress().

getRegionData(region_id: int, data: Pro.Core.NTContainer)bool

Retrieves the data of a region from the database.

Parameters
  • region_id (int) – The region id.

  • data (NTContainer) – The output container for the data.

Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also addRegionData().

getRegions(sort: bool = True)Pro.Carbon.caRegionList

Retrieves the list of regions.

Parameters

sort (bool) – If True, sorts the returned list of regions.

Returns

Returns the list of regions.

Return type

caRegionList

See also getRegion(), addRegion() and regionFromAddress().

getStringValue(key: str, deflt: str = str())bytes

Retrieves a string value.

Parameters
  • key (str) – The name of the string value.

  • deflt (str) – The default value.

Returns

Returns the requested value if present; otherwise returns deflt.

Return type

bytes

See also setStringValue() and getStringValueEx().

getStringValueEx(key: str, e: Pro.Carbon.caStringValue)bool

Retrieves a string value.

Parameters
  • key (str) – The name of the string value.

  • e (caStringValue) – The retrieved string value.

Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also setStringValue() and getStringValue().

getVariables(function: int, type: int = 0)Pro.Carbon.caVariableList

Retrieves a list of variables by their function address.

Parameters
  • function (int) – The function address.

  • type (int) – The type of variables to retrieve (e.g., caVariable.VT_SLEIGH).

Returns

Returns the list of requested variables.

Return type

caVariableList

See also addVariable(), removeVariable() and removeVariables().

getXRef(id: int, e: Pro.Carbon.caXRef)bool

Retrieves a cross reference by its id.

Parameters
  • id (int) – The cross reference id.

  • e (caXRef) – The retrieved cross reference.

Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also getXRefs(), getXRefsByOrigin() and addXRef().

getXRefs(address: int, only_code: bool)Pro.Carbon.caXRefList

Retrieves a list of cross references by their address.

Parameters
  • address (int) – The cross reference address.

  • only_code (bool) – If True, returns only code cross references.

Returns

Returns the list of cross references.

Return type

caXRefList

See also getXRef(), getXRefsByOrigin() and addXRef().

getXRefsByOrigin(origin: int, only_code: bool)Pro.Carbon.caXRefList

Retrieves a list of cross references by their origin address.

Parameters
  • origin (int) – The cross reference origin address.

  • only_code (bool) – If True, returns only code cross references.

Returns

Returns the list of cross references.

Return type

caXRefList

See also getXRefs(), getXRef() and addXRef().

hasXRefs(address: int)bool

Checks whether an address is cross referenced.

Parameters

address (int) – The input address.

Returns

Returns True if the address is cross referenced; otherwise returns False.

Return type

bool

See also getXRefs() and getXRefsByOrigin().

isAddressValid(address: int)bool

Check whether an address is valid.

Parameters

address (int) – The input address.

Returns

Returns True if the address is valid; otherwise returns False.

Return type

bool

See also addressSpaceRange() and regionFromAddress().

isContiguousAddressSpace()bool
Returns

Returns True if the address space is contiguous; otherwise returns False.

Return type

bool

See also setContiguousAddressSpaceRange().

isModified()bool
Returns

Returns True if the database was modified; otherwise returns False.

Return type

bool

See also setModified().

isNull()bool
Returns

Returns True if the database is invalid; otherwise returns False.

Return type

bool

See also isValid().

isQueueEnabled()bool
Returns

Returns True if the queue is enabled; otherwise returns False.

Return type

bool

See also setQueueEnabled().

isValid()bool
Returns

Returns True if the database is valid; otherwise returns False.

Return type

bool

See also isNull().

lineFromAddress(address: int)int

Converts an address into a line number.

Parameters

address (int) – The address to convert.

Returns

Returns the line number.

Return type

int

See also addressFromLine().

load()bool

Initializes the database.

Warning

This method is called internally by Carbon and should therefore be called only when handling databases outside of Carbon instances.

Returns

Returns True if successful; otherwise returns False.

Return type

bool

moduleFromAddress(address: int)Pro.Carbon.caModule

Retrieves the module which contains the specified address.

Parameters

address (int) – The input address.

Returns

Retrieves the module if available; otherwise returns an invalid caModule object.

Return type

caModule

See also getModules() and regionFromAddress().

nextRegionFromAddress(obj: Pro.Core.CFFObject, address: int)Pro.Carbon.caRegion

Retrieves the region located after a specified address.

Parameters
  • obj (CFFObject) – The internal object.

  • address (int) – The input address.

Returns

Retrieves the region if available; otherwise returns an invalid caRegion object.

Return type

caRegion

See also prevRegionFromAddress().

open(dbname: str, options: int = 0)bool

Opens a database.

Parameters
  • dbname (str) – The database file name.

  • options (int) – The options for opening the database (e.g., CarbonDBOpt_ReadOnly).

Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also create().

prevRegionFromAddress(obj: Pro.Core.CFFObject, address: int)Pro.Carbon.caRegion

Retrieves the region located before a specified address.

Parameters
  • obj (CFFObject) – The internal object.

  • address (int) – The input address.

Returns

Retrieves the region if available; otherwise returns an invalid caRegion object.

Return type

caRegion

See also nextRegionFromAddress().

regionFromAddress(obj: Pro.Core.CFFObject, address: int)Pro.Carbon.caRegion

Retrieves the region which contains the specified address.

Parameters
  • obj (CFFObject) – The internal object.

  • address (int) – The input address.

Returns

Retrieves the region if available; otherwise returns an invalid caRegion object.

Return type

caRegion

See also getRegions() and moduleFromAddress().

removeASEntry(start: int)bool

Removes an address space entry.

Parameters

start (int) – The start address of the entry.

Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also addASEntry(), getASEntry() and getNextASEntry().

removeAction(id: int)bool

Removes an action entry.

Parameters

id (int) – The action entry id.

Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also addAction().

removeAllProcessedQueueEntries()bool

Removes all entries from the processed queue.

Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also addProcessedQueueEntry().

removeFlaggedLocation(address: int)bool

Removes a flagged location.

Parameters

address (int) – The flagged location address.

Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also setFlaggedLocation() and getFlaggedLocation().

removeFunction(address: int, remove_vars: bool = True)bool

Removes a function.

Parameters
  • address (int) – The function address.

  • remove_vars (bool) – If True, removes the variables belonging to the function.

Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also addFunction(), setFunction() and getFunction().

removeLabel(address: int)bool

Removes a label.

Parameters

address (int) – The label address.

Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also addLabel(), setLabel() and getLabel().

removeQueueEntry(id: int)bool

Removes a queue entry.

Parameters

id (int) – The queue entry id.

Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also addQueueEntry(), getNextQueueEntry() and setQueueEnabled().

removeVariable(id: int)bool

Removes a variable.

Parameters

id (int) – The variable id.

Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also addVariable(), removeVariables() and getVariables().

removeVariables(function: int)bool

Remove variables belonging to a function.

Parameters

function (int) – The function address.

Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also addVariable(), removeVariable() and getVariables().

removeXRefByOrigin(origin: int)bool

Removes cross references by their origin address.

Parameters

origin (int) – The origin address.

Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also addXRef(), getXRefsByOrigin() and getXRef().

rollbackTransaction()None

Rolls back an SQL transaction.

See also beginTransaction() and endTransaction().

setComment(e: Pro.Carbon.caComment)bool

Adds or updates a comment.

Important

This method deletes the comment if the text is empty.

Parameters

e (caComment) – The comment.

Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also addComment() and getComment().

setContiguousAddressSpaceRange(start: int, end: int)bool

Set the contiguous address space range.

Parameters
  • start (int) – The start address of the address space.

  • end (int) – The end address of the address space.

Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also isContiguousAddressSpace().

setDataValue(key: str, value: bytes)bool

Sets a data value.

Parameters
  • key (str) – The name of the data value.

  • value (bytes) – The data value.

Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also getDataValue() and getDataValueEx().

setDefaultEndianness(def_endianness: int)bool

Sets the default endianness of the address space.

Parameters

def_endianness (int) – The default endianness (caType.CA_LITTLE_ENDIAN or caType.CA_BIG_ENDIAN).

Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also getDefaultEndianness() and getCachedDefaultEndianness().

setFlaggedLocation(e: Pro.Carbon.caFlaggedLocation)bool

Adds or updates a flagged location.

Important

This method deletes the flagged location if the description is empty.

Parameters

e (caFlaggedLocation) – The flagged location.

Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also getFlaggedLocation() and removeFlaggedLocation().

setFunction(e: Pro.Carbon.caFunction)bool

Updates a function.

Parameters

e (caFunction) – The function.

Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also addFunction(), getFunction() and removeFunction().

setFunctionSignature(address: int, signature: str)bool

Updates a function signature.

Parameters
  • address (int) – The function address.

  • signature (str) – The signature to set.

Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also addFunction(), setFunction() and getFunction().

setIntValue(key: str, value: int)bool

Sets an integer value.

Parameters
  • key (str) – The name of the integer value.

  • value (int) – The integer value.

Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also getIntValue() and getIntValueEx().

setLabel(e: Pro.Carbon.caLabel)bool

Adds or updates a label.

Important

This method deletes the label if the text is empty.

Parameters

e (caLabel) – The label.

Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also addLabel(), getLabel() and removeLabel().

setModified(b: bool)None

Sets the modification status of the database.

Parameters

b (bool) – If True, flags the database as modified.

See also isModified().

setModuleFlags(id: int, flags: int)bool

Updates the flags for a specified module.

Parameters
Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also addModule(), getModule() and moduleFromAddress().

setPage(e: Pro.Carbon.caPage)bool

Adds or updates a memory page.

Parameters

e (caPage) – The memory page.

Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also addPage(), getPage(), Carbon.read() and Carbon.write().

setQueueEnabled(b: bool)None

Sets the enabled status of the analysis queue.

Parameters

b (bool) – If False, disables the queue.

See also isQueueEnabled().

setStringValue(key: str, value: str)bool

Sets a string value.

Parameters
  • key (str) – The name of the string value.

  • value (str) – The string value.

Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also getStringValue() and getStringValueEx().

visitActionQueue(visitor: Pro.Carbon.caActionsVisitor)bool

Enumerates the entries of the action queue.

Parameters

visitor (caActionsVisitor) – The visitor object.

Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also caActionsVisitor.

visitBelongingEntries(source: Pro.Core.CFFObject, address: int, visitor: Pro.Carbon.caBelongingEntriesVisitor)bool

Enumerates entries belonging to an input address.

Parameters
Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also caBelongingEntriesVisitor.

visitFunctions(visitor: Pro.Carbon.caFunctionsVisitor)bool

Enumerates functions.

Parameters

visitor (caFunctionsVisitor) – The visitor object.

Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also caFunctionsVisitor.

visitLabels(visitor: Pro.Carbon.caLabelsVisitor)bool

TODO

Parameters

visitor (caLabelsVisitor) – TODO

Returns

TODO

Return type

bool

Available since Cerbero Suite 6.4 and Cerbero Engine 3.4.

CarbonDBOpt_ReadOnly: Final[int]

Opens a database as read-only.

Available since Cerbero Suite 5.2 and Cerbero Engine 2.2.

See also CarbonDB.open().

class CarbonDataResolver

A helper class which uses heuristics to detect data types such as string literals.

This class is used internally by the disassembler and the decompiler.

For example, given the following assembly code:

0x100001191        mov    rsi, qword ptr [0x1000218A8] ; ptr:"unsignedIntegerValue"

The value 0x1000218A8 points to another pointer which in turn points to the string literal.

The following code:

from Pro.UI import proContext, ProView
from Pro.Carbon import *

def resolveData(address):
    view = proContext().getCurrentAnalysisView()
    if view.type() == ProView.Type_Carbon:
        ca = view.getCarbon()
        dr = CarbonDataResolver()
        dr.setAddress(address)
        if dr.resolve(ca):
            print(dr.resolvedDataString())

resolveData(0x1000218A8)

Correctly prints out:

unsignedIntegerValue

Methods:

clear()

Resets the options of this instance to their defaults.

getAddress()

Returns the address of the data to resolve.

getBufferSize()

Returns the internal buffer size.

getCheckPointerIndirection()

Returns True if the data should be checked for pointer indirection; otherwise returns False.

getEndianness()

Returns the endianness of the data (caType.CA_LITTLE_ENDIAN or caType.CA_BIG_ENDIAN).

getMaximumBufferSize()

Returns the maximum buffer size.

getPointerSize()

Returns the pointer size.

getPointerValidationRangeEnd()

Returns the end address of the validation range.

getPointerValidationRangeStart()

Returns the start address of the validation range.

resolve(ca)

Resolves the data address specified with setAddress() if possible.

resolvedDataString()

Returns the resolved data string if available; otherwise returns and empty string.

resolvedDataType()

Returns the resolved data type (e.g., CarbonType_S_utf16).

resolvedDataWasTruncated()

Returns True if the resolved data was truncated; otherwise returns False.

resolvedFromPointer()

Returns True if the data was resolved by following a pointer indirection; otherwise returns False.

setAddress(addr)

Sets the address of the data to resolve.

setBufferSize(size)

Sets the internal buffer size.

setCheckPointerIndirection(b)

Sets whether to check for pointer indirection.

setEndianness(e)

Sets the endianness of the data.

setMaximumBufferSize(size)

Sets the maximum buffer size.

setPointerSize(size)

Sets the pointer size.

setPointerValidationRange(start, end)

Sets the pointer validation range.

clear()None

Resets the options of this instance to their defaults.

getAddress()int
Returns

Returns the address of the data to resolve.

Return type

int

See also setAddress().

getBufferSize()int
Returns

Returns the internal buffer size.

Return type

int

See also setBufferSize().

getCheckPointerIndirection()bool
Returns

Returns True if the data should be checked for pointer indirection; otherwise returns False.

Return type

bool

See also setCheckPointerIndirection().

getEndianness()int
Returns

Returns the endianness of the data (caType.CA_LITTLE_ENDIAN or caType.CA_BIG_ENDIAN).

Return type

int

See also setEndianness().

getMaximumBufferSize()int
Returns

Returns the maximum buffer size.

Return type

int

See also setMaximumBufferSize().

getPointerSize()int
Returns

Returns the pointer size.

Return type

int

See also setPointerSize().

getPointerValidationRangeEnd()int
Returns

Returns the end address of the validation range.

Return type

int

See also getPointerValidationRangeStart() and setPointerValidationRange().

getPointerValidationRangeStart()int
Returns

Returns the start address of the validation range.

Return type

int

See also getPointerValidationRangeEnd() and setPointerValidationRange().

resolve(ca: Pro.Carbon.Carbon)bool

Resolves the data address specified with setAddress() if possible.

Parameters

ca (Carbon) – The instance of Carbon.

Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also setAddress() and resolvedDataString().

resolvedDataString()str
Returns

Returns the resolved data string if available; otherwise returns and empty string.

Return type

str

See also resolve() and resolvedDataType().

resolvedDataType()int
Returns

Returns the resolved data type (e.g., CarbonType_S_utf16).

Return type

int

See also resolve() and resolvedDataString().

resolvedDataWasTruncated()bool
Returns

Returns True if the resolved data was truncated; otherwise returns False.

Return type

bool

See also resolvedFromPointer().

resolvedFromPointer()bool
Returns

Returns True if the data was resolved by following a pointer indirection; otherwise returns False.

Return type

bool

See also resolvedDataWasTruncated().

setAddress(addr: int)None

Sets the address of the data to resolve.

Parameters

addr (int) – The address of the data to resolve.

See also getAddress().

setBufferSize(size: int)None

Sets the internal buffer size.

Parameters

size (int) – The internal buffer size.

See also getBufferSize().

setCheckPointerIndirection(b: bool)None

Sets whether to check for pointer indirection.

Parameters

b (bool) – If True, the data resolution process checks for pointer indirection.

See also getCheckPointerIndirection().

setEndianness(e: int)None

Sets the endianness of the data.

Parameters

e (int) – The endianness of the data (caType.CA_LITTLE_ENDIAN or caType.CA_BIG_ENDIAN).

See also getEndianness().

setMaximumBufferSize(size: int)None

Sets the maximum buffer size.

Parameters

size (int) – The maximum buffer size.

See also getMaximumBufferSize().

setPointerSize(size: int)None

Sets the pointer size.

Parameters

size (int) – The pointer size.

See also getPointerSize().

setPointerValidationRange(start: int, end: int)None

Sets the pointer validation range.

By default the validation range is represented by the entire address space.

Parameters
  • start (int) – The start address of the validation range.

  • end (int) – The end address of the validation range.

See also getPointerValidationRangeStart() and getPointerValidationRangeEnd().

class CarbonDecompilerInterface(carbon: Pro.Carbon.Carbon)

This class represents the decompiler interface inherited by classes to provide decompiler functionality.

Parameters

carbon (Carbon) – The instance of Carbon.

See also CarbonSleighDecompiler.

Methods:

decompileToString(address)

Decompiles a function to C code.

decompileToString(address: int)str

Decompiles a function to C code.

Parameters

address (int) – The address of a function.

Returns

Returns the decompiled C code if successful; otherwise returns an empty string.

Return type

str

class CarbonLoader

This class represents the interface to implement file format loaders.

Methods:

aborted()

Returns True if the load operation was aborted; otherwise returns False.

carbon()

Returns the Carbon instance.

executeAction(uictx, cmd)

This method must be implemented to receive the notification of executed UI actions.

load()

This method must be implemented to load the file format.

loadUI(uictx)

This method must be implemented to create dependent views or loader actions if required.

setStatus(m)

Sets the current load status information.

aborted()bool
Returns

Returns True if the load operation was aborted; otherwise returns False.

Return type

bool

carbon()Pro.Carbon.Carbon
Returns

Returns the Carbon instance.

Return type

Carbon

See also Carbon.

executeAction(uictx: Pro.Carbon.CarbonUIContext, cmd: int)None

This method must be implemented to receive the notification of executed UI actions.

Parameters
  • uictx (CarbonUIContext) – The UI context.

  • cmd (int) – The command id of the executed action.

See also Pro.UI.ProCarbonView.addLoaderAction().

load()int

This method must be implemented to load the file format.

Returns

Returns a Carbon error code (e.g., CARBON_OK).

Return type

int

loadUI(uictx: Pro.Carbon.CarbonUIContext)None

This method must be implemented to create dependent views or loader actions if required.

Parameters

uictx (CarbonUIContext) – The UI context.

See also Pro.UI.ProView.addDependentView() and Pro.UI.ProCarbonView.addLoaderAction().

setStatus(m: str)None

Sets the current load status information.

Parameters

m (str) – The current load status message to be provided to the user.

class CarbonLoaderOptions

This class contains options for the loader.

Available since Cerbero Suite 6.2 and Cerbero Engine 3.2.

See also Carbon.loadOptions() and Carbon.setLoadOptions().

Attributes:

add_entry_points

Specifies whether the loader should add entry points.

add_exceptions

Specifies whether the loader should add exceptions.

add_exports

Specifies whether the loader should add exports.

add_imports

Specifies whether the loader should add imports.

add_relocs

Specifies whether the loader should add relocs.

add_entry_points

Specifies whether the loader should add entry points.

add_exceptions

Specifies whether the loader should add exceptions.

add_exports

Specifies whether the loader should add exports.

add_imports

Specifies whether the loader should add imports.

add_relocs

Specifies whether the loader should add relocs.

class CarbonSleighDecompiler(carbon: Pro.Carbon.Carbon)

Bases: Pro.Carbon.CarbonDecompilerInterface

This class uses the Sleigh decompiler as a back-end decompiler.

See also CarbonDecompilerInterface.

Parameters

carbon (Carbon) – The instance of Carbon.

See also CarbonSleighDecompiler.

CarbonType_I_ARM32: Final[int]

ARM32 data type.

This type uses the default endianness of the database.

See also CarbonBasicTypeInfo.

CarbonType_I_ARM32_BE: Final[int]

ARM32 big-endian data type.

See also CarbonBasicTypeInfo.

CarbonType_I_ARM32_LE: Final[int]

ARM32 little-endian data type.

See also CarbonBasicTypeInfo.

CarbonType_I_ARM64: Final[int]

ARM64 data type.

This type uses the default endianness of the database.

See also CarbonBasicTypeInfo.

CarbonType_I_ARM64_BE: Final[int]

ARM64 big-endian data type.

See also CarbonBasicTypeInfo.

CarbonType_I_ARM64_LE: Final[int]

ARM64 little-endian data type.

See also CarbonBasicTypeInfo.

CarbonType_I_Thumb: Final[int]

ARM-Thumb data type.

This type uses the default endianness of the database.

See also CarbonBasicTypeInfo.

CarbonType_I_Thumb_BE: Final[int]

ARM-Thumb big-endian data type.

See also CarbonBasicTypeInfo.

CarbonType_I_Thumb_LE: Final[int]

ARM-Thumb little-endian data type.

See also CarbonBasicTypeInfo.

CarbonType_I_x64: Final[int]

x64 data type.

See also CarbonBasicTypeInfo.

CarbonType_I_x86: Final[int]

x86 data type.

See also CarbonBasicTypeInfo.

CarbonType_I_x86_16: Final[int]

x86 16-bit data type.

See also CarbonBasicTypeInfo.

CarbonType_Invalid: Final[int]

Invalid data type.

See also CarbonBasicTypeInfo.

CarbonType_N_d64: Final[int]

64-bit floating number data type.

This type uses the default endianness of the database.

See also CarbonBasicTypeInfo.

CarbonType_N_d64_be: Final[int]

64-bit floating number big-endian data type.

See also CarbonBasicTypeInfo.

CarbonType_N_d64_le: Final[int]

64-bit floating number little-endian data type.

CarbonType_N_f32: Final[int]

32-bit floating number data type.

This type uses the default endianness of the database.

See also CarbonBasicTypeInfo.

CarbonType_N_f32_be: Final[int]

32-bit floating number big-endian data type.

See also CarbonBasicTypeInfo.

CarbonType_N_f32_le: Final[int]

32-bit floating number little-endian data type.

See also CarbonBasicTypeInfo.

CarbonType_N_i128: Final[int]

128-bit signed integer data type.

This type uses the default endianness of the database.

See also CarbonBasicTypeInfo.

CarbonType_N_i128_be: Final[int]

128-bit signed integer big-endian data type.

See also CarbonBasicTypeInfo.

CarbonType_N_i128_le: Final[int]

128-bit signed integer little-endian data type.

See also CarbonBasicTypeInfo.

CarbonType_N_i16: Final[int]

16-bit signed integer data type.

This type uses the default endianness of the database.

See also CarbonBasicTypeInfo.

CarbonType_N_i16_be: Final[int]

16-bit signed integer big-endian data type.

See also CarbonBasicTypeInfo.

CarbonType_N_i16_le: Final[int]

16-bit signed integer little-endian data type.

See also CarbonBasicTypeInfo.

CarbonType_N_i32: Final[int]

32-bit signed integer data type.

This type uses the default endianness of the database.

See also CarbonBasicTypeInfo.

CarbonType_N_i32_be: Final[int]

32-bit signed integer big-endian data type.

See also CarbonBasicTypeInfo.

CarbonType_N_i32_le: Final[int]

32-bit signed integer little-endian data type.

See also CarbonBasicTypeInfo.

CarbonType_N_i64: Final[int]

64-bit signed integer data type.

This type uses the default endianness of the database.

See also CarbonBasicTypeInfo.

CarbonType_N_i64_be: Final[int]

64-bit signed integer big-endian data type.

See also CarbonBasicTypeInfo.

CarbonType_N_i64_le: Final[int]

64-bit signed integer little-endian data type.

See also CarbonBasicTypeInfo.

CarbonType_N_i8: Final[int]

8-bit signed integer data type.

See also CarbonBasicTypeInfo.

CarbonType_N_ptr16: Final[int]

16-bit pointer data type.

This type uses the default endianness of the database.

See also CarbonBasicTypeInfo.

CarbonType_N_ptr16_be: Final[int]

16-bit pointer big-endian data type.

See also CarbonBasicTypeInfo.

CarbonType_N_ptr16_le: Final[int]

16-bit pointer little-endian data type.

See also CarbonBasicTypeInfo.

CarbonType_N_ptr32: Final[int]

32-bit pointer data type.

This type uses the default endianness of the database.

See also CarbonBasicTypeInfo.

CarbonType_N_ptr32_be: Final[int]

32-bit pointer big-endian data type.

See also CarbonBasicTypeInfo.

CarbonType_N_ptr32_le: Final[int]

32-bit pointer little-endian data type.

See also CarbonBasicTypeInfo.

CarbonType_N_ptr64: Final[int]

64-bit pointer data type.

This type uses the default endianness of the database.

See also CarbonBasicTypeInfo.

CarbonType_N_ptr64_be: Final[int]

64-bit pointer big-endian data type.

See also CarbonBasicTypeInfo.

CarbonType_N_ptr64_le: Final[int]

64-bit pointer little-endian data type.

See also CarbonBasicTypeInfo.

CarbonType_N_u128: Final[int]

128-bit unsigned integer data type.

This type uses the default endianness of the database.

See also CarbonBasicTypeInfo.

CarbonType_N_u128_be: Final[int]

128-bit unsigned integer big-endian data type.

See also CarbonBasicTypeInfo.

CarbonType_N_u128_le: Final[int]

128-bit unsigned integer little-endian data type.

See also CarbonBasicTypeInfo.

CarbonType_N_u16: Final[int]

16-bit unsigned integer data type.

This type uses the default endianness of the database.

See also CarbonBasicTypeInfo.

CarbonType_N_u16_be: Final[int]

16-bit unsigned integer big-endian data type.

See also CarbonBasicTypeInfo.

CarbonType_N_u16_le: Final[int]

16-bit unsigned integer little-endian data type.

CarbonType_N_u32: Final[int]

32-bit unsigned integer data type.

This type uses the default endianness of the database.

See also CarbonBasicTypeInfo.

CarbonType_N_u32_be: Final[int]

32-bit unsigned integer big-endian data type.

See also CarbonBasicTypeInfo.

CarbonType_N_u32_le: Final[int]

32-bit unsigned integer little-endian data type.

See also CarbonBasicTypeInfo.

CarbonType_N_u64: Final[int]

64-bit unsigned integer data type.

This type uses the default endianness of the database.

See also CarbonBasicTypeInfo.

CarbonType_N_u64_be: Final[int]

64-bit unsigned integer big-endian data type.

See also CarbonBasicTypeInfo.

CarbonType_N_u64_le: Final[int]

64-bit unsigned integer little-endian data type.

See also CarbonBasicTypeInfo.

CarbonType_N_u8: Final[int]

8-bit unsigned integer data type.

See also CarbonBasicTypeInfo.

CarbonType_S_ascii: Final[int]

Ascii string data type.

See also CarbonBasicTypeInfo.

CarbonType_S_utf16: Final[int]

UTF-16 string data type.

This type uses the default endianness of the database.

See also CarbonBasicTypeInfo.

CarbonType_S_utf16_be: Final[int]

UTF-16 string big-endian data type.

See also CarbonBasicTypeInfo.

CarbonType_S_utf16_le: Final[int]

UTF-16 string little-endian data type.

See also CarbonBasicTypeInfo.

CarbonType_S_utf32: Final[int]

UTF-32 string data type.

This type uses the default endianness of the database.

See also CarbonBasicTypeInfo.

CarbonType_S_utf32_be: Final[int]

UTF-32 string big-endian data type.

See also CarbonBasicTypeInfo.

CarbonType_S_utf32_le: Final[int]

UTF-32 string little-endian data type.

See also CarbonBasicTypeInfo.

CarbonType_S_utf8: Final[int]

UTF-8 string data type.

See also CarbonBasicTypeInfo.

class CarbonUIContext

An opaque class which represents the UI context for a Carbon view.

Pro.UI.ProCarbonView.fromCarbonUIContext() must be called to convert this class into a view.

See also Pro.UI.ProCarbonView.fromCarbonUIContext() and Pro.UI.ProCarbonView.

DBGSYMOPT_ALL: Final[int]

Mask for all the debug symbol options.

Note

DBGSYMOPT_IMPTYPES_GLOBAL must be specified explicitly.

See also Carbon.loadPDB().

DBGSYMOPT_IMPTYPES: Final[int]

Imports types into the local Carbon header.

See also Carbon.loadPDB().

DBGSYMOPT_IMPTYPES_GLOBAL: Final[int]

Imports types into the project header.

See also Carbon.loadPDB().

class caASEntry

This class represents an individual entry in the address space.

See also CarbonDB.addASEntry(), CarbonDB.getASEntry() and CarbonDB.getNextASEntry().

Attributes:

end

The end address of the entry.

start

The start address of the entry.

type_id

The type id of the entry (e.g., CarbonType_I_x64).

end

The end address of the entry.

start

The start address of the entry.

type_id

The type id of the entry (e.g., CarbonType_I_x64).

class caAction

Bases: Pro.Carbon.caCommon

This class represents an analysis action.

See also CarbonDB.addAction(), CarbonDB.getNewestAction() and Carbon.resumeAnalysis().

Attributes:

ANALYSIS

Analysis action type.

MAKE_CODE

Make code action type.

NONE

Invalid action type.

UNDEFINE

Undefine action type.

end

The end address of the action.

options

The options of the action.

start

The start address of the action.

timestamp

The timestamp of the action.

type

The type of the action (e.g., ANALYSIS).

type_id

The data type id for the action (e.g., CarbonType_I_x64).

Methods:

isNull()

Returns True if the action is invalid; otherwise returns False.

ANALYSIS: Final[int]

Analysis action type.

See also type.

MAKE_CODE: Final[int]

Make code action type.

See also type.

NONE: Final[int]

Invalid action type.

See also type.

UNDEFINE: Final[int]

Undefine action type.

See also type.

end

The end address of the action.

isNull()bool
Returns

Returns True if the action is invalid; otherwise returns False.

Return type

bool

options

The options of the action.

This field is reserved for future use.

start

The start address of the action.

timestamp

The timestamp of the action.

type

The type of the action (e.g., ANALYSIS).

type_id

The data type id for the action (e.g., CarbonType_I_x64).

class caActionsVisitor

This class must be inherited to obtain a visitor for the actions queue.

See also CarbonDB.visitActionQueue().

Methods:

visit(db, e)

This method is called for every visited action.

visit(db: Pro.Carbon.CarbonDB, e: Pro.Carbon.caAction)bool

This method is called for every visited action.

Parameters
Returns

Returns True to continue the enumeration; otherwise returns False.

Return type

bool

class caBelongingEntriesVisitor

This class must be inherited to obtain a visitor for the belonging address space entries.

See also Carbon.visitBelongingEntries() and CarbonDB.visitBelongingEntries().

Methods:

visit(db, e, insn)

This method is called for every visited entry.

visit(db: CarbonDB, e: caASEntry, insn: CarbonCapstoneBase)bool

This method is called for every visited entry.

Parameters
  • db (CarbonDB) – The database instance.

  • e (caASEntry) – The address space entry.

  • insn (CarbonCapstoneBase) – An opaque structure representing the architecture disassembler.

Returns

Returns True to continue the enumeration; otherwise returns False.

Return type

bool

class caComment

This class represents a comment.

See also CarbonDB.addComment(), CarbonDB.getComment() and CarbonDB.setComment().

Attributes:

address

The address of the comment.

text

The text of the comment.

address

The address of the comment.

text

The text of the comment.

class caCommon

This class is inherited by those classes which rely on a SQLite3 provided index rather than defining their own unique index.

Attributes:

id

The SQLite3 index of the entry.

id

The SQLite3 index of the entry.

class caDataValue

Bases: Pro.Carbon.caCommon

This class represents a data value.

See also CarbonDB.getDataValue(), CarbonDB.getDataValueEx() and CarbonDB.setDataValue().

Attributes:

key

The name of the data value.

value

The data value.

key

The name of the data value.

value

The data value.

class caEntryPoint

Bases: Pro.Carbon.caCommon

This class represents an entry point.

See also CarbonDB.addEntryPoint() and CarbonDB.getEntryPoint().

Attributes:

address

The address of entry point.

name

The name of the entry point.

type_id

The type id of the entry point (e.g., CarbonType_I_x64).

address

The address of entry point.

name

The name of the entry point.

type_id

The type id of the entry point (e.g., CarbonType_I_x64).

class caExceptionRecord

Bases: Pro.Carbon.caCommon

This class represents an exception record.

Hint

Exception records are a complex topic. The best way to understand how to add exception records to a Carbon database is by looking at the implementation of a file format loader, like the Portable Executable one, which implements them.

See also CarbonDB.addExceptionRecord(), CarbonDB.getExceptionRecordsByAddress() and CarbonDB.getExceptionRecordsByOwner().

Attributes:

EXCEPT_END

Exception clause end.

EXCEPT_START

Exception clause start.

FILTER_END

Exception filter end.

FILTER_START

Exception filter start.

FINALLY_END

Exception final end.

FINALLY_START

Exception final start.

INVALID

Invalid exception record type.

TRY_END

Try clause end.

TRY_START

Try clause start.

UNWIND_END

Unwind clause end.

UNWIND_START

Unwind clause start.

address

The address of the exception clause.

handler

The address of the handler of the exception.

owner

The address of the owner of the exception.

start

The start address of the exception clause.

type

The type of the exception record (e.g., EXCEPT_START).

Methods:

hasHandler()

Returns True if the exception has a handler; otherwise returns False.

EXCEPT_END: Final[int]

Exception clause end.

See also type.

EXCEPT_START: Final[int]

Exception clause start.

See also type.

FILTER_END: Final[int]

Exception filter end.

See also type.

FILTER_START: Final[int]

Exception filter start.

See also type.

FINALLY_END: Final[int]

Exception final end.

See also type.

FINALLY_START: Final[int]

Exception final start.

See also type.

INVALID: Final[int]

Invalid exception record type.

See also type.

TRY_END: Final[int]

Try clause end.

See also type.

TRY_START: Final[int]

Try clause start.

See also type.

UNWIND_END: Final[int]

Unwind clause end.

See also type.

UNWIND_START: Final[int]

Unwind clause start.

See also type.

address

The address of the exception clause.

handler

The address of the handler of the exception.

hasHandler()bool
Returns

Returns True if the exception has a handler; otherwise returns False.

Return type

bool

owner

The address of the owner of the exception.

start

The start address of the exception clause.

This value differs from address for end exception records (e.g., UNWIND_END).

type

The type of the exception record (e.g., EXCEPT_START).

class caExceptionRecordList

List of caExceptionRecord elements.

Methods:

append(value)

Inserts value at the end of the list.

at(i)

Returns the item at index position i in the list.

clear()

Removes all items from the list.

contains(value)

Checks the presence of an element in the list.

count(value)

Returns the number of occurrences of value in the list.

indexOf(value[, start])

Searches for an element in the list.

insert(i, value)

Inserts value at index position i in the list.

isEmpty()

Checks whether the list is empty.

iterator()

Creates an iterator for the list.

removeAll(value)

Removes all occurrences of value in the list and returns the number of entries removed.

removeAt(i)

Removes the item at index position i.

reserve(alloc)

Reserve space for alloc elements.

size()

Returns the number of items in the list.

takeAt(i)

Removes the item at index position i and returns it.

append(value: Pro.Carbon.caExceptionRecord)None

Inserts value at the end of the list.

Parameters

value (caExceptionRecord) – The value to add to the list.

See also insert().

at(i: int)Pro.Carbon.caExceptionRecord

Returns the item at index position i in the list. i must be a valid index position in the list (i.e., 0 <= i < size()).

Parameters

i (int) – The index of the element to return.

Returns

Returns the requested element.

Return type

caExceptionRecord

clear()None

Removes all items from the list.

contains(value: Pro.Carbon.caExceptionRecord)bool

Checks the presence of an element in the list.

Parameters

value (caExceptionRecord) – The value to check for.

Returns

Returns True if the list contains an occurrence of value; otherwise returns False.

Return type

bool

See also indexOf() and count().

count(value: Pro.Carbon.caExceptionRecord)int

Returns the number of occurrences of value in the list.

Parameters

value (caExceptionRecord) – The value to count.

Returns

Returns the number of occurrences.

Return type

int

See also indexOf() and contains().

indexOf(value: Pro.Carbon.caExceptionRecord, start: int = 0)int

Searches for an element in the list.

Parameters
  • value (caExceptionRecord) – The value to search for.

  • start (int) – The start index.

Returns

Returns the index position of the first occurrence of value in the list. Returns -1 if no item was found.

Return type

int

See also contains().

insert(i: int, value: Pro.Carbon.caExceptionRecord)None

Inserts value at index position i in the list. If i is 0, the value is prepended to the list. If i is size(), the value is appended to the list.

Parameters
  • i (int) – The position at which to add the value.

  • value (caExceptionRecord) – The value to add.

See also append() and removeAt().

isEmpty()bool

Checks whether the list is empty.

Returns

Returns True if the list contains no items; otherwise returns False.

Return type

bool

See also size().

iterator()Pro.Carbon.caExceptionRecordListIt

Creates an iterator for the list.

Returns

Returns the iterator.

Return type

caExceptionRecordListIt

removeAll(value: Pro.Carbon.caExceptionRecord)int

Removes all occurrences of value in the list and returns the number of entries removed.

Parameters

value (caExceptionRecord) – The value to remove from the list.

Returns

Returns the number of entries removed.

Return type

int

See also removeAt().

removeAt(i: int)None

Removes the item at index position i. i must be a valid index position in the list (i.e., 0 <= i < size()).

Parameters

i (int) – The index of the item to remove.

See also removeAll().

reserve(alloc: int)None

Reserve space for alloc elements. Calling this method doesn’t change the size of the list.

Parameters

alloc (int) – The amount of elements to reserve space for.

size()int
Returns

Returns the number of items in the list.

Return type

int

See also isEmpty().

takeAt(i: int)Pro.Carbon.caExceptionRecord

Removes the item at index position i and returns it. i must be a valid index position in the list (i.e., 0 <= i < size()).

Parameters

i (int) – The index of the element to remove from the list.

Returns

Returns the removed element. If you don’t use the return value, removeAt() is more efficient.

Return type

caExceptionRecord

See also removeAt().

class caExceptionRecordListIt(obj: Pro.Carbon.caExceptionRecordList)

Iterator class for caExceptionRecordList.

Parameters

obj (caExceptionRecordList) – The object to iterate over.

Methods:

hasNext()

Returns True if there is at least one item ahead of the iterator, i.e. the iterator is not at the back of the container; otherwise returns False.

hasPrevious()

Returns True if there is at least one item behind the iterator, i.e. the iterator is not at the front of the container; otherwise returns False.

next()

Returns the next item and advances the iterator by one position.

previous()

Returns the previous item and moves the iterator back by one position.

toBack()

Moves the iterator to the back of the container (after the last item).

toFront()

Moves the iterator to the front of the container (before the first item).

hasNext()bool
Returns

Returns True if there is at least one item ahead of the iterator, i.e. the iterator is not at the back of the container; otherwise returns False.

Return type

bool

See also hasPrevious() and next().

hasPrevious()bool
Returns

Returns True if there is at least one item behind the iterator, i.e. the iterator is not at the front of the container; otherwise returns False.

Return type

bool

See also hasNext() and previous().

next()Pro.Carbon.caExceptionRecord
Returns

Returns the next item and advances the iterator by one position.

Return type

caExceptionRecord

See also hasNext() and previous().

previous()Pro.Carbon.caExceptionRecord
Returns

Returns the previous item and moves the iterator back by one position.

Return type

caExceptionRecord

See also hasPrevious() and next().

toBack()None

Moves the iterator to the back of the container (after the last item).

See also toFront() and previous().

toFront()None

Moves the iterator to the front of the container (before the first item).

See also toBack() and next().

class caExport

Bases: Pro.Carbon.caCommon

This class represents an exported symbol.

See also CarbonDB.addExport() and CarbonDB.getExport().

Attributes:

address

The address of the exported symbol.

flags

The flags of the exported symbol.

name

The name of the exported symbol.

ordinal

The ordinal of the exported symbol.

type_id

The data type id of the exported symbol (e.g., CarbonType_I_x64).

address

The address of the exported symbol.

flags

The flags of the exported symbol.

This field is reserved for future use.

name

The name of the exported symbol.

ordinal

The ordinal of the exported symbol.

type_id

The data type id of the exported symbol (e.g., CarbonType_I_x64).

class caFlaggedLocation

This class represents a flagged location.

See also CarbonDB.getFlaggedLocation() and CarbonDB.setFlaggedLocation().

Attributes:

USER

Flag for a location flagged by the user.

address

The address of the flagged location.

description

The description of the flagged location.

flags

The flags of the flagged location (e.g., USER).

position

The column position of the flagged location.

USER: Final[int]

Flag for a location flagged by the user.

See also flags.

address

The address of the flagged location.

description

The description of the flagged location.

flags

The flags of the flagged location (e.g., USER).

position

The column position of the flagged location.

class caFlaggedLocationList

List of caFlaggedLocation elements.

Methods:

append(value)

Inserts value at the end of the list.

at(i)

Returns the item at index position i in the list.

clear()

Removes all items from the list.

contains(value)

Checks the presence of an element in the list.

count(value)

Returns the number of occurrences of value in the list.

indexOf(value[, start])

Searches for an element in the list.

insert(i, value)

Inserts value at index position i in the list.

isEmpty()

Checks whether the list is empty.

iterator()

Creates an iterator for the list.

removeAll(value)

Removes all occurrences of value in the list and returns the number of entries removed.

removeAt(i)

Removes the item at index position i.

reserve(alloc)

Reserve space for alloc elements.

size()

Returns the number of items in the list.

takeAt(i)

Removes the item at index position i and returns it.

append(value: Pro.Carbon.caFlaggedLocation)None

Inserts value at the end of the list.

Parameters

value (caFlaggedLocation) – The value to add to the list.

See also insert().

at(i: int)Pro.Carbon.caFlaggedLocation

Returns the item at index position i in the list. i must be a valid index position in the list (i.e., 0 <= i < size()).

Parameters

i (int) – The index of the element to return.

Returns

Returns the requested element.

Return type

caFlaggedLocation

clear()None

Removes all items from the list.

contains(value: Pro.Carbon.caFlaggedLocation)bool

Checks the presence of an element in the list.

Parameters

value (caFlaggedLocation) – The value to check for.

Returns

Returns True if the list contains an occurrence of value; otherwise returns False.

Return type

bool

See also indexOf() and count().

count(value: Pro.Carbon.caFlaggedLocation)int

Returns the number of occurrences of value in the list.

Parameters

value (caFlaggedLocation) – The value to count.

Returns

Returns the number of occurrences.

Return type

int

See also indexOf() and contains().

indexOf(value: Pro.Carbon.caFlaggedLocation, start: int = 0)int

Searches for an element in the list.

Parameters
  • value (caFlaggedLocation) – The value to search for.

  • start (int) – The start index.

Returns

Returns the index position of the first occurrence of value in the list. Returns -1 if no item was found.

Return type

int

See also contains().

insert(i: int, value: Pro.Carbon.caFlaggedLocation)None

Inserts value at index position i in the list. If i is 0, the value is prepended to the list. If i is size(), the value is appended to the list.

Parameters
  • i (int) – The position at which to add the value.

  • value (caFlaggedLocation) – The value to add.

See also append() and removeAt().

isEmpty()bool

Checks whether the list is empty.

Returns

Returns True if the list contains no items; otherwise returns False.

Return type

bool

See also size().

iterator()Pro.Carbon.caFlaggedLocationListIt

Creates an iterator for the list.

Returns

Returns the iterator.

Return type

caFlaggedLocationListIt

removeAll(value: Pro.Carbon.caFlaggedLocation)int

Removes all occurrences of value in the list and returns the number of entries removed.

Parameters

value (caFlaggedLocation) – The value to remove from the list.

Returns

Returns the number of entries removed.

Return type

int

See also removeAt().

removeAt(i: int)None

Removes the item at index position i. i must be a valid index position in the list (i.e., 0 <= i < size()).

Parameters

i (int) – The index of the item to remove.

See also removeAll().

reserve(alloc: int)None

Reserve space for alloc elements. Calling this method doesn’t change the size of the list.

Parameters

alloc (int) – The amount of elements to reserve space for.

size()int
Returns

Returns the number of items in the list.

Return type

int

See also isEmpty().

takeAt(i: int)Pro.Carbon.caFlaggedLocation

Removes the item at index position i and returns it. i must be a valid index position in the list (i.e., 0 <= i < size()).

Parameters

i (int) – The index of the element to remove from the list.

Returns

Returns the removed element. If you don’t use the return value, removeAt() is more efficient.

Return type

caFlaggedLocation

See also removeAt().

class caFlaggedLocationListIt(obj: Pro.Carbon.caFlaggedLocationList)

Iterator class for caFlaggedLocationList.

Parameters

obj (caFlaggedLocationList) – The object to iterate over.

Methods:

hasNext()

Returns True if there is at least one item ahead of the iterator, i.e. the iterator is not at the back of the container; otherwise returns False.

hasPrevious()

Returns True if there is at least one item behind the iterator, i.e. the iterator is not at the front of the container; otherwise returns False.

next()

Returns the next item and advances the iterator by one position.

previous()

Returns the previous item and moves the iterator back by one position.

toBack()

Moves the iterator to the back of the container (after the last item).

toFront()

Moves the iterator to the front of the container (before the first item).

hasNext()bool
Returns

Returns True if there is at least one item ahead of the iterator, i.e. the iterator is not at the back of the container; otherwise returns False.

Return type

bool

See also hasPrevious() and next().

hasPrevious()bool
Returns

Returns True if there is at least one item behind the iterator, i.e. the iterator is not at the front of the container; otherwise returns False.

Return type

bool

See also hasNext() and previous().

next()Pro.Carbon.caFlaggedLocation
Returns

Returns the next item and advances the iterator by one position.

Return type

caFlaggedLocation

See also hasNext() and previous().

previous()Pro.Carbon.caFlaggedLocation
Returns

Returns the previous item and moves the iterator back by one position.

Return type

caFlaggedLocation

See also hasPrevious() and next().

toBack()None

Moves the iterator to the back of the container (after the last item).

See also toFront() and previous().

toFront()None

Moves the iterator to the front of the container (before the first item).

See also toBack() and next().

class caFunction

This class represents a function.

See also CarbonDB.addFunction(), CarbonDB.getFunction() and CarbonDB.setFunction().

Attributes:

address

The address of the function.

end

The optional end address of the function.

flags

The flags of the function.

signature

The signature of the function.

type_id

The data type id for the function (e.g., CarbonType_I_x64).

Methods:

hasEndAddress()

Returns True if the function has an end address; otherwise returns False.

address

The address of the function.

end

The optional end address of the function.

flags

The flags of the function.

This field is reserved for future use.

hasEndAddress()bool
Returns

Returns True if the function has an end address; otherwise returns False.

Return type

bool

signature

The signature of the function.

type_id

The data type id for the function (e.g., CarbonType_I_x64).

class caFunctionsVisitor

This class must be inherited to obtain a function visitor.

See also CarbonDB.visitFunctions().

Methods:

visit(db, e)

This method is called for every visited function.

visit(db: Pro.Carbon.CarbonDB, e: Pro.Carbon.caFunction)bool

This method is called for every visited function.

Parameters
Returns

Returns True to continue the enumeration; otherwise returns False.

Return type

bool

class caImport

Bases: Pro.Carbon.caCommon

This class represents an imported symbol.

See also CarbonDB.addImport() and CarbonDB.getImport().

Attributes:

address

The address of the imported symbol.

flags

The flags of the imported symbol.

module_name

The module name of the imported symbol.

name

The name of the imported symbol.

ordinal

The ordinal of the imported symbol.

type_id

The data type id of the imported symbol (e.g., CarbonType_I_x64).

address

The address of the imported symbol.

flags

The flags of the imported symbol.

This field is reserved for future use.

module_name

The module name of the imported symbol.

name

The name of the imported symbol.

ordinal

The ordinal of the imported symbol.

type_id

The data type id of the imported symbol (e.g., CarbonType_I_x64).

class caIntValue

Bases: Pro.Carbon.caCommon

This class represents an integer value.

See also CarbonDB.getIntValue(), CarbonDB.getIntValueEx() and CarbonDB.setIntValue().

Attributes:

key

The name of the integer value.

value

The integer value.

key

The name of the integer value.

value

The integer value.

class caLabel

This class represents a label.

See also CarbonDB.addLabel(), CarbonDB.getLabel() and CarbonDB.setLabel().

Attributes:

address

The address of the label.

name

The name of the label.

address

The address of the label.

name

The name of the label.

class caLabelsVisitor

TODO

Available since Cerbero Suite 6.4 and Cerbero Engine 3.4.

Methods:

visit(db, e)

TODO

visit(db: Pro.Carbon.CarbonDB, e: Pro.Carbon.caLabel)bool

TODO

Parameters
Returns

TODO

Return type

bool

class caModule

Bases: Pro.Carbon.caCommon

This class represents a module.

See also CarbonDB.addModule(), CarbonDB.getModule() and CarbonDB.getModules().

Attributes:

DEBUG_SYMBOLS_LOADED

This flag is set when debug symbols are loaded for the module.

dbg_symbols

The debug symbols association string.

end

The end address of the module.

flags

The flags of the module (e.g., DEBUG_SYMBOLS_LOADED).

format

The format of the module.

name

The name of the module.

path

The path of the module.

start

The start address of the module.

Methods:

contains(addr)

Checks whether a specified address is contained in the address range of the module.

isNull()

Returns True if the module is invalid; otherwise returns False.

shortName()

Returns the short name of the module.

size()

Returns the size of the module.

DEBUG_SYMBOLS_LOADED: Final[int]

This flag is set when debug symbols are loaded for the module.

See also flags.

contains(addr: int)bool

Checks whether a specified address is contained in the address range of the module.

Parameters

addr (int) – The input address.

Returns

Returns True if the input address belongs to the module; otherwise returns False.

Return type

bool

dbg_symbols

The debug symbols association string.

See also Pro.Core.PDBAssociationInfo.

end

The end address of the module.

flags

The flags of the module (e.g., DEBUG_SYMBOLS_LOADED).

format

The format of the module.

isNull()bool
Returns

Returns True if the module is invalid; otherwise returns False.

Return type

bool

name

The name of the module.

path

The path of the module.

shortName()str
Returns

Returns the short name of the module.

Return type

str

size()int
Returns

Returns the size of the module.

Return type

int

start

The start address of the module.

class caModuleList

List of caModule elements.

Methods:

append(value)

Inserts value at the end of the list.

at(i)

Returns the item at index position i in the list.

clear()

Removes all items from the list.

contains(value)

Checks the presence of an element in the list.

count(value)

Returns the number of occurrences of value in the list.

indexOf(value[, start])

Searches for an element in the list.

insert(i, value)

Inserts value at index position i in the list.

isEmpty()

Checks whether the list is empty.

iterator()

Creates an iterator for the list.

removeAll(value)

Removes all occurrences of value in the list and returns the number of entries removed.

removeAt(i)

Removes the item at index position i.

reserve(alloc)

Reserve space for alloc elements.

size()

Returns the number of items in the list.

takeAt(i)

Removes the item at index position i and returns it.

append(value: Pro.Carbon.caModule)None

Inserts value at the end of the list.

Parameters

value (caModule) – The value to add to the list.

See also insert().

at(i: int)Pro.Carbon.caModule

Returns the item at index position i in the list. i must be a valid index position in the list (i.e., 0 <= i < size()).

Parameters

i (int) – The index of the element to return.

Returns

Returns the requested element.

Return type

caModule

clear()None

Removes all items from the list.

contains(value: Pro.Carbon.caModule)bool

Checks the presence of an element in the list.

Parameters

value (caModule) – The value to check for.

Returns

Returns True if the list contains an occurrence of value; otherwise returns False.

Return type

bool

See also indexOf() and count().

count(value: Pro.Carbon.caModule)int

Returns the number of occurrences of value in the list.

Parameters

value (caModule) – The value to count.

Returns

Returns the number of occurrences.

Return type

int

See also indexOf() and contains().

indexOf(value: Pro.Carbon.caModule, start: int = 0)int

Searches for an element in the list.

Parameters
  • value (caModule) – The value to search for.

  • start (int) – The start index.

Returns

Returns the index position of the first occurrence of value in the list. Returns -1 if no item was found.

Return type

int

See also contains().

insert(i: int, value: Pro.Carbon.caModule)None

Inserts value at index position i in the list. If i is 0, the value is prepended to the list. If i is size(), the value is appended to the list.

Parameters
  • i (int) – The position at which to add the value.

  • value (caModule) – The value to add.

See also append() and removeAt().

isEmpty()bool

Checks whether the list is empty.

Returns

Returns True if the list contains no items; otherwise returns False.

Return type

bool

See also size().

iterator()Pro.Carbon.caModuleListIt

Creates an iterator for the list.

Returns

Returns the iterator.

Return type

caModuleListIt

removeAll(value: Pro.Carbon.caModule)int

Removes all occurrences of value in the list and returns the number of entries removed.

Parameters

value (caModule) – The value to remove from the list.

Returns

Returns the number of entries removed.

Return type

int

See also removeAt().

removeAt(i: int)None

Removes the item at index position i. i must be a valid index position in the list (i.e., 0 <= i < size()).

Parameters

i (int) – The index of the item to remove.

See also removeAll().

reserve(alloc: int)None

Reserve space for alloc elements. Calling this method doesn’t change the size of the list.

Parameters

alloc (int) – The amount of elements to reserve space for.

size()int
Returns

Returns the number of items in the list.

Return type

int

See also isEmpty().

takeAt(i: int)Pro.Carbon.caModule

Removes the item at index position i and returns it. i must be a valid index position in the list (i.e., 0 <= i < size()).

Parameters

i (int) – The index of the element to remove from the list.

Returns

Returns the removed element. If you don’t use the return value, removeAt() is more efficient.

Return type

caModule

See also removeAt().

class caModuleListIt(obj: Pro.Carbon.caModuleList)

Iterator class for caModuleList.

Parameters

obj (caModuleList) – The object to iterate over.

Methods:

hasNext()

Returns True if there is at least one item ahead of the iterator, i.e. the iterator is not at the back of the container; otherwise returns False.

hasPrevious()

Returns True if there is at least one item behind the iterator, i.e. the iterator is not at the front of the container; otherwise returns False.

next()

Returns the next item and advances the iterator by one position.

previous()

Returns the previous item and moves the iterator back by one position.

toBack()

Moves the iterator to the back of the container (after the last item).

toFront()

Moves the iterator to the front of the container (before the first item).

hasNext()bool
Returns

Returns True if there is at least one item ahead of the iterator, i.e. the iterator is not at the back of the container; otherwise returns False.

Return type

bool

See also hasPrevious() and next().

hasPrevious()bool
Returns

Returns True if there is at least one item behind the iterator, i.e. the iterator is not at the front of the container; otherwise returns False.

Return type

bool

See also hasNext() and previous().

next()Pro.Carbon.caModule
Returns

Returns the next item and advances the iterator by one position.

Return type

caModule

See also hasNext() and previous().

previous()Pro.Carbon.caModule
Returns

Returns the previous item and moves the iterator back by one position.

Return type

caModule

See also hasPrevious() and next().

toBack()None

Moves the iterator to the back of the container (after the last item).

See also toFront() and previous().

toFront()None

Moves the iterator to the front of the container (before the first item).

See also toBack() and next().

class caPage

This class represents a memory page.

See also CarbonDB.addPage(), CarbonDB.getPage() and CarbonDB.setPage().

Attributes:

address

The address of the memory page.

data

The data of the memory page.

flags

The flags of the memory page.

address

The address of the memory page.

data

The data of the memory page.

flags

The flags of the memory page.

This field is reserved for future use.

class caRegion

Bases: Pro.Carbon.caCommon

This class represents a memory region.

See also CarbonDB.addRegion(), CarbonDB.getRegion() and CarbonDB.getRegions().

Attributes:

EXEC

Flag for executable memory.

NA

Flag for not available memory.

READ

Flag for readable memory.

RELOC

Flag for relocatable memory.

WRITE

Flag for writable memory.

def_type_id

The default data type id for the memory region (e.g., CarbonType_I_x64).

end

The end address of the memory region.

flags

The flags of the memory region (e.g., EXEC).

name

The name of the memory region.

offset

The file offset of the memory region.

start

The start address of the memory region.

Methods:

contains(addr)

Checks whether a specified address is contained in the address range of the memory region.

isNull()

Returns True if the memory region is invalid; otherwise returns False.

memoryFlagsDescr()

Returns a description of the flags of the memory region.

size()

Returns the size of the memory region.

EXEC: Final[int]

Flag for executable memory.

See also flags.

NA: Final[int]

Flag for not available memory.

See also flags.

READ: Final[int]

Flag for readable memory.

See also flags.

RELOC: Final[int]

Flag for relocatable memory.

See also flags.

WRITE: Final[int]

Flag for writable memory.

See also flags.

contains(addr: int)bool

Checks whether a specified address is contained in the address range of the memory region.

Parameters

addr (int) – The input address.

Returns

Returns True if the input address belongs to the memory region; otherwise returns False.

Return type

bool

def_type_id

The default data type id for the memory region (e.g., CarbonType_I_x64).

end

The end address of the memory region.

flags

The flags of the memory region (e.g., EXEC).

isNull()bool
Returns

Returns True if the memory region is invalid; otherwise returns False.

Return type

bool

memoryFlagsDescr()str
Returns

Returns a description of the flags of the memory region.

Return type

str

name

The name of the memory region.

offset

The file offset of the memory region.

size()int
Returns

Returns the size of the memory region.

Return type

int

start

The start address of the memory region.

class caRegionList

List of caRegion elements.

Methods:

append(value)

Inserts value at the end of the list.

at(i)

Returns the item at index position i in the list.

clear()

Removes all items from the list.

contains(value)

Checks the presence of an element in the list.

count(value)

Returns the number of occurrences of value in the list.

indexOf(value[, start])

Searches for an element in the list.

insert(i, value)

Inserts value at index position i in the list.

isEmpty()

Checks whether the list is empty.

iterator()

Creates an iterator for the list.

removeAll(value)

Removes all occurrences of value in the list and returns the number of entries removed.

removeAt(i)

Removes the item at index position i.

reserve(alloc)

Reserve space for alloc elements.

size()

Returns the number of items in the list.

takeAt(i)

Removes the item at index position i and returns it.

append(value: Pro.Carbon.caRegion)None

Inserts value at the end of the list.

Parameters

value (caRegion) – The value to add to the list.

See also insert().

at(i: int)Pro.Carbon.caRegion

Returns the item at index position i in the list. i must be a valid index position in the list (i.e., 0 <= i < size()).

Parameters

i (int) – The index of the element to return.

Returns

Returns the requested element.

Return type

caRegion

clear()None

Removes all items from the list.

contains(value: Pro.Carbon.caRegion)bool

Checks the presence of an element in the list.

Parameters

value (caRegion) – The value to check for.

Returns

Returns True if the list contains an occurrence of value; otherwise returns False.

Return type

bool

See also indexOf() and count().

count(value: Pro.Carbon.caRegion)int

Returns the number of occurrences of value in the list.

Parameters

value (caRegion) – The value to count.

Returns

Returns the number of occurrences.

Return type

int

See also indexOf() and contains().

indexOf(value: Pro.Carbon.caRegion, start: int = 0)int

Searches for an element in the list.

Parameters
  • value (caRegion) – The value to search for.

  • start (int) – The start index.

Returns

Returns the index position of the first occurrence of value in the list. Returns -1 if no item was found.

Return type

int

See also contains().

insert(i: int, value: Pro.Carbon.caRegion)None

Inserts value at index position i in the list. If i is 0, the value is prepended to the list. If i is size(), the value is appended to the list.

Parameters
  • i (int) – The position at which to add the value.

  • value (caRegion) – The value to add.

See also append() and removeAt().

isEmpty()bool

Checks whether the list is empty.

Returns

Returns True if the list contains no items; otherwise returns False.

Return type

bool

See also size().

iterator()Pro.Carbon.caRegionListIt

Creates an iterator for the list.

Returns

Returns the iterator.

Return type

caRegionListIt

removeAll(value: Pro.Carbon.caRegion)int

Removes all occurrences of value in the list and returns the number of entries removed.

Parameters

value (caRegion) – The value to remove from the list.

Returns

Returns the number of entries removed.

Return type

int

See also removeAt().

removeAt(i: int)None

Removes the item at index position i. i must be a valid index position in the list (i.e., 0 <= i < size()).

Parameters

i (int) – The index of the item to remove.

See also removeAll().

reserve(alloc: int)None

Reserve space for alloc elements. Calling this method doesn’t change the size of the list.

Parameters

alloc (int) – The amount of elements to reserve space for.

size()int
Returns

Returns the number of items in the list.

Return type

int

See also isEmpty().

takeAt(i: int)Pro.Carbon.caRegion

Removes the item at index position i and returns it. i must be a valid index position in the list (i.e., 0 <= i < size()).

Parameters

i (int) – The index of the element to remove from the list.

Returns

Returns the removed element. If you don’t use the return value, removeAt() is more efficient.

Return type

caRegion

See also removeAt().

class caRegionListIt(obj: Pro.Carbon.caRegionList)

Iterator class for caRegionList.

Parameters

obj (caRegionList) – The object to iterate over.

Methods:

hasNext()

Returns True if there is at least one item ahead of the iterator, i.e. the iterator is not at the back of the container; otherwise returns False.

hasPrevious()

Returns True if there is at least one item behind the iterator, i.e. the iterator is not at the front of the container; otherwise returns False.

next()

Returns the next item and advances the iterator by one position.

previous()

Returns the previous item and moves the iterator back by one position.

toBack()

Moves the iterator to the back of the container (after the last item).

toFront()

Moves the iterator to the front of the container (before the first item).

hasNext()bool
Returns

Returns True if there is at least one item ahead of the iterator, i.e. the iterator is not at the back of the container; otherwise returns False.

Return type

bool

See also hasPrevious() and next().

hasPrevious()bool
Returns

Returns True if there is at least one item behind the iterator, i.e. the iterator is not at the front of the container; otherwise returns False.

Return type

bool

See also hasNext() and previous().

next()Pro.Carbon.caRegion
Returns

Returns the next item and advances the iterator by one position.

Return type

caRegion

See also hasNext() and previous().

previous()Pro.Carbon.caRegion
Returns

Returns the previous item and moves the iterator back by one position.

Return type

caRegion

See also hasPrevious() and next().

toBack()None

Moves the iterator to the back of the container (after the last item).

See also toFront() and previous().

toFront()None

Moves the iterator to the front of the container (before the first item).

See also toBack() and next().

class caReloc

Bases: Pro.Carbon.caCommon

This class represents a relocation.

See also CarbonDB.addReloc().

Attributes:

RELOC_32

Relocation type.

RELOC_32_ADJ

Relocation type.

RELOC_32_HIGH_16

Relocation type.

RELOC_32_HIGH_16_ADJ

Relocation type.

RELOC_32_LOW_16

Relocation type.

RELOC_64

Relocation type.

RELOC_64_ADJ

Relocation type.

RELOC_INVALID

Invalid relocation type.

address

The address of the data to relocate.

adjust

The additional parameter to adjust the relocation value.

type

The relocation type (e.g., RELOC_64).

RELOC_32: Final[int]

Relocation type.

See also type.

RELOC_32_ADJ: Final[int]

Relocation type.

See also type.

RELOC_32_HIGH_16: Final[int]

Relocation type.

See also type.

RELOC_32_HIGH_16_ADJ: Final[int]

Relocation type.

See also type.

RELOC_32_LOW_16: Final[int]

Relocation type.

See also type.

RELOC_64: Final[int]

Relocation type.

See also type.

RELOC_64_ADJ: Final[int]

Relocation type.

See also type.

RELOC_INVALID: Final[int]

Invalid relocation type.

See also type.

address

The address of the data to relocate.

adjust

The additional parameter to adjust the relocation value.

type

The relocation type (e.g., RELOC_64).

class caStringValue

Bases: Pro.Carbon.caCommon

This class represents a string value.

See also CarbonDB.getStringValue(), CarbonDB.getStringValueEx() and CarbonDB.setStringValue().

Attributes:

key

The name of the string value.

value

The string value.

key

The name of the string value.

value

The string value.

class caType

Bases: Pro.Carbon.caCommon

This class represents a custom type.

See also CarbonDB.addType().

Attributes:

CA_BIG_ENDIAN

Big endianness flag.

CA_LITTLE_ENDIAN

Little endianness flag.

flags

The flags of the type.

name

The name of the type.

CA_BIG_ENDIAN: Final[int]

Big endianness flag.

CA_LITTLE_ENDIAN: Final[int]

Little endianness flag.

flags

The flags of the type.

name

The name of the type.

class caVariable

Bases: Pro.Carbon.caCommon

This class represents a variable.

See also CarbonDB.addVariable() and CarbonDB.getVariables().

Attributes:

VT_CARBON

Carbon disassembly variable type.

VT_SLEIGH

Sleigh decompiler variable type.

auto_name

The automatic name provided for the variable.

flags

The flags of the variable.

function

The address of the function to which the variable belongs.

idx

The index of the variable.

name

The name of the variable.

type

The type of the variable (e.g., VT_SLEIGH).

type_id

The data type id of the variable (e.g., CarbonType_N_i32).

VT_CARBON: Final[int]

Carbon disassembly variable type.

See also type.

VT_SLEIGH: Final[int]

Sleigh decompiler variable type.

See also type.

auto_name

The automatic name provided for the variable.

flags

The flags of the variable.

This field is reserved for future use.

function

The address of the function to which the variable belongs.

idx

The index of the variable.

name

The name of the variable.

type

The type of the variable (e.g., VT_SLEIGH).

type_id

The data type id of the variable (e.g., CarbonType_N_i32).

class caVariableList

List of caVariable elements.

Methods:

append(value)

Inserts value at the end of the list.

at(i)

Returns the item at index position i in the list.

clear()

Removes all items from the list.

contains(value)

Checks the presence of an element in the list.

count(value)

Returns the number of occurrences of value in the list.

indexOf(value[, start])

Searches for an element in the list.

insert(i, value)

Inserts value at index position i in the list.

isEmpty()

Checks whether the list is empty.

iterator()

Creates an iterator for the list.

removeAll(value)

Removes all occurrences of value in the list and returns the number of entries removed.

removeAt(i)

Removes the item at index position i.

reserve(alloc)

Reserve space for alloc elements.

size()

Returns the number of items in the list.

takeAt(i)

Removes the item at index position i and returns it.

append(value: Pro.Carbon.caVariable)None

Inserts value at the end of the list.

Parameters

value (caVariable) – The value to add to the list.

See also insert().

at(i: int)Pro.Carbon.caVariable

Returns the item at index position i in the list. i must be a valid index position in the list (i.e., 0 <= i < size()).

Parameters

i (int) – The index of the element to return.

Returns

Returns the requested element.

Return type

caVariable

clear()None

Removes all items from the list.

contains(value: Pro.Carbon.caVariable)bool

Checks the presence of an element in the list.

Parameters

value (caVariable) – The value to check for.

Returns

Returns True if the list contains an occurrence of value; otherwise returns False.

Return type

bool

See also indexOf() and count().

count(value: Pro.Carbon.caVariable)int

Returns the number of occurrences of value in the list.

Parameters

value (caVariable) – The value to count.

Returns

Returns the number of occurrences.

Return type

int

See also indexOf() and contains().

indexOf(value: Pro.Carbon.caVariable, start: int = 0)int

Searches for an element in the list.

Parameters
  • value (caVariable) – The value to search for.

  • start (int) – The start index.

Returns

Returns the index position of the first occurrence of value in the list. Returns -1 if no item was found.

Return type

int

See also contains().

insert(i: int, value: Pro.Carbon.caVariable)None

Inserts value at index position i in the list. If i is 0, the value is prepended to the list. If i is size(), the value is appended to the list.

Parameters
  • i (int) – The position at which to add the value.

  • value (caVariable) – The value to add.

See also append() and removeAt().

isEmpty()bool

Checks whether the list is empty.

Returns

Returns True if the list contains no items; otherwise returns False.

Return type

bool

See also size().

iterator()Pro.Carbon.caVariableListIt

Creates an iterator for the list.

Returns

Returns the iterator.

Return type

caVariableListIt

removeAll(value: Pro.Carbon.caVariable)int

Removes all occurrences of value in the list and returns the number of entries removed.

Parameters

value (caVariable) – The value to remove from the list.

Returns

Returns the number of entries removed.

Return type

int

See also removeAt().

removeAt(i: int)None

Removes the item at index position i. i must be a valid index position in the list (i.e., 0 <= i < size()).

Parameters

i (int) – The index of the item to remove.

See also removeAll().

reserve(alloc: int)None

Reserve space for alloc elements. Calling this method doesn’t change the size of the list.

Parameters

alloc (int) – The amount of elements to reserve space for.

size()int
Returns

Returns the number of items in the list.

Return type

int

See also isEmpty().

takeAt(i: int)Pro.Carbon.caVariable

Removes the item at index position i and returns it. i must be a valid index position in the list (i.e., 0 <= i < size()).

Parameters

i (int) – The index of the element to remove from the list.

Returns

Returns the removed element. If you don’t use the return value, removeAt() is more efficient.

Return type

caVariable

See also removeAt().

class caVariableListIt(obj: Pro.Carbon.caVariableList)

Iterator class for caVariableList.

Parameters

obj (caVariableList) – The object to iterate over.

Methods:

hasNext()

Returns True if there is at least one item ahead of the iterator, i.e. the iterator is not at the back of the container; otherwise returns False.

hasPrevious()

Returns True if there is at least one item behind the iterator, i.e. the iterator is not at the front of the container; otherwise returns False.

next()

Returns the next item and advances the iterator by one position.

previous()

Returns the previous item and moves the iterator back by one position.

toBack()

Moves the iterator to the back of the container (after the last item).

toFront()

Moves the iterator to the front of the container (before the first item).

hasNext()bool
Returns

Returns True if there is at least one item ahead of the iterator, i.e. the iterator is not at the back of the container; otherwise returns False.

Return type

bool

See also hasPrevious() and next().

hasPrevious()bool
Returns

Returns True if there is at least one item behind the iterator, i.e. the iterator is not at the front of the container; otherwise returns False.

Return type

bool

See also hasNext() and previous().

next()Pro.Carbon.caVariable
Returns

Returns the next item and advances the iterator by one position.

Return type

caVariable

See also hasNext() and previous().

previous()Pro.Carbon.caVariable
Returns

Returns the previous item and moves the iterator back by one position.

Return type

caVariable

See also hasPrevious() and next().

toBack()None

Moves the iterator to the back of the container (after the last item).

See also toFront() and previous().

toFront()None

Moves the iterator to the front of the container (before the first item).

See also toBack() and next().

class caXRef

Bases: Pro.Carbon.caCommon

This class represents a cross reference.

See also CarbonDB.addXRef(), CarbonDB.getXRef() and CarbonDB.getXRefs().

Attributes:

AUTO

Automatic cross reference type.

CALL

Call cross reference type.

COND

Conditional branch cross reference type.

DATA

Data cross reference type.

ENTRYPOINT

Entry point cross reference type.

EXCEPTION

Exception cross reference type.

EXPORT

Export cross reference type.

FUNCSTART

Function start cross reference type.

INVALID

Invalid cross reference type.

JUMP

Unconditional jump cross reference type.

address

The address of the cross reference.

origin

The origin of the cross reference.

type

The type of the cross reference (e.g., JUMP).

type_id

The data type id of the cross reference (e.g., CarbonType_I_x64).

Methods:

isCodeXRef()

Returns True if it’s a code cross reference; otherwise returns False.

typeDescr()

Returns a type description of the cross reference.

AUTO: Final[int]

Automatic cross reference type.

See also type.

CALL: Final[int]

Call cross reference type.

See also type.

COND: Final[int]

Conditional branch cross reference type.

See also type.

DATA: Final[int]

Data cross reference type.

See also type.

ENTRYPOINT: Final[int]

Entry point cross reference type.

See also type.

EXCEPTION: Final[int]

Exception cross reference type.

See also type.

EXPORT: Final[int]

Export cross reference type.

See also type.

FUNCSTART: Final[int]

Function start cross reference type.

See also type.

INVALID: Final[int]

Invalid cross reference type.

See also type.

JUMP: Final[int]

Unconditional jump cross reference type.

See also type.

address

The address of the cross reference.

isCodeXRef()bool
Returns

Returns True if it’s a code cross reference; otherwise returns False.

Return type

bool

origin

The origin of the cross reference.

type

The type of the cross reference (e.g., JUMP).

typeDescr()str
Returns

Returns a type description of the cross reference.

Return type

str

type_id

The data type id of the cross reference (e.g., CarbonType_I_x64).

class caXRefList

List of caXRef elements.

Methods:

append(value)

Inserts value at the end of the list.

at(i)

Returns the item at index position i in the list.

clear()

Removes all items from the list.

contains(value)

Checks the presence of an element in the list.

count(value)

Returns the number of occurrences of value in the list.

indexOf(value[, start])

Searches for an element in the list.

insert(i, value)

Inserts value at index position i in the list.

isEmpty()

Checks whether the list is empty.

iterator()

Creates an iterator for the list.

removeAll(value)

Removes all occurrences of value in the list and returns the number of entries removed.

removeAt(i)

Removes the item at index position i.

reserve(alloc)

Reserve space for alloc elements.

size()

Returns the number of items in the list.

takeAt(i)

Removes the item at index position i and returns it.

append(value: Pro.Carbon.caXRef)None

Inserts value at the end of the list.

Parameters

value (caXRef) – The value to add to the list.

See also insert().

at(i: int)Pro.Carbon.caXRef

Returns the item at index position i in the list. i must be a valid index position in the list (i.e., 0 <= i < size()).

Parameters

i (int) – The index of the element to return.

Returns

Returns the requested element.

Return type

caXRef

clear()None

Removes all items from the list.

contains(value: Pro.Carbon.caXRef)bool

Checks the presence of an element in the list.

Parameters

value (caXRef) – The value to check for.

Returns

Returns True if the list contains an occurrence of value; otherwise returns False.

Return type

bool

See also indexOf() and count().

count(value: Pro.Carbon.caXRef)int

Returns the number of occurrences of value in the list.

Parameters

value (caXRef) – The value to count.

Returns

Returns the number of occurrences.

Return type

int

See also indexOf() and contains().

indexOf(value: Pro.Carbon.caXRef, start: int = 0)int

Searches for an element in the list.

Parameters
  • value (caXRef) – The value to search for.

  • start (int) – The start index.

Returns

Returns the index position of the first occurrence of value in the list. Returns -1 if no item was found.

Return type

int

See also contains().

insert(i: int, value: Pro.Carbon.caXRef)None

Inserts value at index position i in the list. If i is 0, the value is prepended to the list. If i is size(), the value is appended to the list.

Parameters
  • i (int) – The position at which to add the value.

  • value (caXRef) – The value to add.

See also append() and removeAt().

isEmpty()bool

Checks whether the list is empty.

Returns

Returns True if the list contains no items; otherwise returns False.

Return type

bool

See also size().

iterator()Pro.Carbon.caXRefListIt

Creates an iterator for the list.

Returns

Returns the iterator.

Return type

caXRefListIt

removeAll(value: Pro.Carbon.caXRef)int

Removes all occurrences of value in the list and returns the number of entries removed.

Parameters

value (caXRef) – The value to remove from the list.

Returns

Returns the number of entries removed.

Return type

int

See also removeAt().

removeAt(i: int)None

Removes the item at index position i. i must be a valid index position in the list (i.e., 0 <= i < size()).

Parameters

i (int) – The index of the item to remove.

See also removeAll().

reserve(alloc: int)None

Reserve space for alloc elements. Calling this method doesn’t change the size of the list.

Parameters

alloc (int) – The amount of elements to reserve space for.

size()int
Returns

Returns the number of items in the list.

Return type

int

See also isEmpty().

takeAt(i: int)Pro.Carbon.caXRef

Removes the item at index position i and returns it. i must be a valid index position in the list (i.e., 0 <= i < size()).

Parameters

i (int) – The index of the element to remove from the list.

Returns

Returns the removed element. If you don’t use the return value, removeAt() is more efficient.

Return type

caXRef

See also removeAt().

class caXRefListIt(obj: Pro.Carbon.caXRefList)

Iterator class for caXRefList.

Parameters

obj (caXRefList) – The object to iterate over.

Methods:

hasNext()

Returns True if there is at least one item ahead of the iterator, i.e. the iterator is not at the back of the container; otherwise returns False.

hasPrevious()

Returns True if there is at least one item behind the iterator, i.e. the iterator is not at the front of the container; otherwise returns False.

next()

Returns the next item and advances the iterator by one position.

previous()

Returns the previous item and moves the iterator back by one position.

toBack()

Moves the iterator to the back of the container (after the last item).

toFront()

Moves the iterator to the front of the container (before the first item).

hasNext()bool
Returns

Returns True if there is at least one item ahead of the iterator, i.e. the iterator is not at the back of the container; otherwise returns False.

Return type

bool

See also hasPrevious() and next().

hasPrevious()bool
Returns

Returns True if there is at least one item behind the iterator, i.e. the iterator is not at the front of the container; otherwise returns False.

Return type

bool

See also hasNext() and previous().

next()Pro.Carbon.caXRef
Returns

Returns the next item and advances the iterator by one position.

Return type

caXRef

See also hasNext() and previous().

previous()Pro.Carbon.caXRef
Returns

Returns the previous item and moves the iterator back by one position.

Return type

caXRef

See also hasPrevious() and next().

toBack()None

Moves the iterator to the back of the container (after the last item).

See also toFront() and previous().

toFront()None

Moves the iterator to the front of the container (before the first item).

See also toBack() and next().