Module ida_lines

High level functions that deal with the generation of the disassembled text lines.

This file also contains definitions for the syntax highlighting.

Finally there are functions that deal with anterior/posterior user-defined lines.

Global variables

var COLOR_ADDR

hidden address marks. the address is represented as 8digit hex number: 01234567. it doesn't have COLOR_OFF pair. NB: for 64-bit IDA, the address is 16digit.

var COLOR_ADDR_SIZE

Size of a tagged address (see COLOR_ADDR)

var COLOR_ALTOP

Alternative operand.

var COLOR_ASMDIR

Assembler directive.

var COLOR_AUTOCMT

Automatic comment.

var COLOR_BG_MAX

Max color number.

var COLOR_BINPREF

Binary line prefix bytes.

var COLOR_CHAR

Char constant in instruction.

var COLOR_CNAME

Regular code name.

var COLOR_CODE

Single instruction.

var COLOR_CODNAME

Dummy code name.

var COLOR_COLLAPSED

Collapsed line.

var COLOR_CREF

Code reference.

var COLOR_CREFTAIL

Code reference to tail byte.

var COLOR_CURITEM

Current item.

var COLOR_CURLINE

Current line.

var COLOR_DATA

Data bytes.

var COLOR_DATNAME

Dummy Data Name.

var COLOR_DCHAR

Char constant in data directive.

var COLOR_DEFAULT

Default.

var COLOR_DEMNAME

Demangled Name.

var COLOR_DNAME

Regular Data Name.

var COLOR_DNUM

Numeric constant in data directive.

var COLOR_DREF

Data reference.

var COLOR_DREFTAIL

Data reference to tail byte.

var COLOR_DSTR

String constant in data directive.

var COLOR_ERROR

Error or problem.

var COLOR_ESC

Escape character (Quote next character). This is needed to output '\1' and '\2' characters.

var COLOR_EXTERN

External name definition segment.

var COLOR_EXTRA

Extra line.

var COLOR_FG_MAX

Max color number.

var COLOR_HIDLINE

Hidden line.

var COLOR_HIDNAME

Hidden name.

var COLOR_IMPNAME

Imported name.

var COLOR_INSN

Instruction.

var COLOR_INV

Escape character (Inverse foreground and background colors). This escape character has no corresponding COLOR_OFF. Its action continues until the next COLOR_INV or end of line.

var COLOR_KEYWORD

Keywords.

var COLOR_LIBFUNC

Library function.

var COLOR_LIBNAME

Library function name.

var COLOR_LOCNAME

Local variable name.

var COLOR_LUMFUNC

Lumina function.

var COLOR_LUMINA

Lumina-related, only for the navigation band.

var COLOR_MACRO

Macro.

var COLOR_NUMBER

Numeric constant in instruction.

var COLOR_OFF

Escape character (OFF). Followed by a color code (color_t).

var COLOR_ON

Escape character (ON). Followed by a color code (color_t).

var COLOR_OPND1

Instruction operand 1.

var COLOR_OPND2

Instruction operand 2.

var COLOR_OPND3

Instruction operand 3.

var COLOR_OPND4

Instruction operand 4.

var COLOR_OPND5

Instruction operand 5.

var COLOR_OPND6

Instruction operand 6.

var COLOR_OPND7

Instruction operand 7.

var COLOR_OPND8

Instruction operand 8.

var COLOR_PREFIX

Line prefix.

var COLOR_REG

Register name.

var COLOR_REGCMT

Regular comment.

var COLOR_REGFUNC

Regular function.

var COLOR_RESERVED1

This tag is reserved for internal IDA use.

var COLOR_RPTCMT

Repeatable comment (comment defined somewhere else)

var COLOR_SEGNAME

Segment name.

var COLOR_SELECTED

Selected.

var COLOR_STRING

String constant in instruction.

var COLOR_SYMBOL

Punctuation.

var COLOR_UNAME

Regular unknown name.

var COLOR_UNKNAME

Dummy unknown name.

var COLOR_UNKNOWN

Unexplored byte.

var COLOR_VOIDOP

Void operand.

var SCOLOR_ADDR

Hidden address mark.

var SCOLOR_ALTOP

Alternative operand.

var SCOLOR_ASMDIR

Assembler directive.

var SCOLOR_AUTOCMT

Automatic comment.

var SCOLOR_BINPREF

Binary line prefix bytes.

var SCOLOR_CHAR

Char constant in instruction.

var SCOLOR_CNAME

Regular code name.

var SCOLOR_CODNAME

Dummy code name.

var SCOLOR_COLLAPSED

Collapsed line.

var SCOLOR_CREF

Code reference.

var SCOLOR_CREFTAIL

Code reference to tail byte.

var SCOLOR_DATNAME

Dummy Data Name.

var SCOLOR_DCHAR

Char constant in data directive.

var SCOLOR_DEFAULT

Default.

var SCOLOR_DEMNAME

Demangled Name.

var SCOLOR_DNAME

Regular Data Name.

var SCOLOR_DNUM

Numeric constant in data directive.

var SCOLOR_DREF

Data reference.

var SCOLOR_DREFTAIL

Data reference to tail byte.

var SCOLOR_DSTR

String constant in data directive.

var SCOLOR_ERROR

Error or problem.

var SCOLOR_ESC

Escape character (Quote next character)

var SCOLOR_EXTRA

Extra line.

var SCOLOR_HIDNAME

Hidden name.

var SCOLOR_IMPNAME

Imported name.

var SCOLOR_INSN

Instruction.

var SCOLOR_INV

Escape character (Inverse colors)

var SCOLOR_KEYWORD

Keywords.

var SCOLOR_LIBNAME

Library function name.

var SCOLOR_LOCNAME

Local variable name.

var SCOLOR_MACRO

Macro.

var SCOLOR_NUMBER

Numeric constant in instruction.

var SCOLOR_OFF

Escape character (OFF)

var SCOLOR_ON

Escape character (ON)

var SCOLOR_PREFIX

Line prefix.

var SCOLOR_REG

Register name.

var SCOLOR_REGCMT

Regular comment.

var SCOLOR_RPTCMT

Repeatable comment (defined not here)

var SCOLOR_SEGNAME

Segment name.

var SCOLOR_STRING

String constant in instruction.

var SCOLOR_SYMBOL

Punctuation.

var SCOLOR_UNAME

Regular unknown name.

var SCOLOR_UNKNAME

Dummy unknown name.

var SCOLOR_VOIDOP

Void operand.

var VEL_CMT

append comment line

var VEL_POST

append posterior line

Functions

def COLSTR(str, tag)

Utility function to create a colored line @param str: The string @param tag: Color tag constant. One of SCOLOR_XXXX

def add_extra_cmt(*args) ‑> bool

add_extra_cmt(ea, isprev, format) -> bool Add anterior/posterior comment line(s).

@param ea: (C++: ea_t) linear address @param isprev: (C++: bool) do we add anterior lines? (0-no, posterior) @param format: (C++: const char *) printf() style format string. may contain \n to denote new lines. The resulting string should not contain comment characters (;), the kernel will add them automatically. @return: true if success

def add_extra_line(*args) ‑> bool

add_extra_line(ea, isprev, format) -> bool Add anterior/posterior non-comment line(s).

@param ea: (C++: ea_t) linear address @param isprev: (C++: bool) do we add anterior lines? (0-no, posterior) @param format: (C++: const char *) printf() style format string. may contain \n to denote new lines. @return: true if success

def add_pgm_cmt(*args) ‑> bool

add_pgm_cmt(format) -> bool Add anterior comment line(s) at the start of program.

@param format: (C++: const char *) printf() style format string. may contain \n to denote new lines. The resulting string should not contain comment characters (;), the kernel will add them automatically. @return: true if success

def add_sourcefile(ea1: ea_t, ea2: ea_t, filename: char const *)

add_sourcefile(ea1, ea2, filename) -> bool Mark a range of address as belonging to a source file. An address range may belong only to one source file. A source file may be represented by several address ranges.

@param ea1: (C++: ea_t) linear address of start of the address range @param ea2: (C++: ea_t) linear address of end of the address range (excluded) @param filename: (C++: const char *) name of source file. @return: success

def calc_bg_color(ea: ea_t)

calc_bg_color(ea) -> bgcolor_t Get background color for line at 'ea'

@param ea: (C++: ea_t) @return: RGB color

def calc_prefix_color(ea: ea_t)

calc_prefix_color(ea) -> color_t Get prefix color for line at 'ea'

@param ea: (C++: ea_t) @return: Line prefix colors

def create_encoding_helper(*args)

create_encoding_helper(encidx=-1, nr=nr_once) -> encoder_t

@param encidx: int @param nr: enum encoder_t::notify_recerr_t

def del_extra_cmt(ea: ea_t, what: int)

del_extra_cmt(ea, what) -> bool

@param ea: ea_t @param what: int

def del_sourcefile(ea: ea_t)

del_sourcefile(ea) -> bool Delete information about the source file.

@param ea: (C++: ea_t) linear address @return: success

def delete_extra_cmts(ea: ea_t, what: int)

delete_extra_cmts(ea, what)

@param ea: ea_t @param what: int

def generate_disasm_line(ea: ea_t, flags: int = 0)

generate_disasm_line(ea, flags=0) -> bool

@param ea: ea_t @param flags: int

def generate_disassembly(ea: ea_t, max_lines: int, as_stack: bool, notags: bool)

generate_disassembly(ea, max_lines, as_stack, notags) -> (int, [str, …]) Generate disassembly lines (many lines) and put them into a buffer

@param ea: address to generate disassembly for @param max_lines: how many lines max to generate @param as_stack: Display undefined items as 2/4/8 bytes @param notags: bool @return: - None on failure - tuple(most_important_line_number, list(lines)) : Returns a tuple containing the most important line number and a list of generated lines

def get_extra_cmt(ea: ea_t, what: int)

get_extra_cmt(ea, what) -> ssize_t

@param ea: ea_t @param what: int

def get_first_free_extra_cmtidx(ea: ea_t, start: int)

get_first_free_extra_cmtidx(ea, start) -> int

@param ea: ea_t @param start: int

def get_sourcefile(ea: ea_t, bounds: range_t = None)

get_sourcefile(ea, bounds=None) -> char const Get name of source file occupying the given address.

@param ea: (C++: ea_t) linear address @param bounds: (C++: range_t *) pointer to the output buffer with the address range for the current file. May be nullptr. @return: nullptr if source file information is not found, otherwise returns pointer to file name

def install_user_defined_prefix(*args) ‑> bool

install_user_defined_prefix(prefix_len, udp, owner) -> bool User-defined line-prefixes are displayed just after the autogenerated line prefixes in the disassembly listing. There is no need to call this function explicitly. Use the user_defined_prefix_t class.

@param prefix_len: (C++: size_t) prefixed length. if 0, then uninstall UDP @param udp: (C++: struct user_defined_prefix_t ) object to generate user-defined prefix @param owner: (C++: const void ) pointer to the plugin_t that owns UDP if non-nullptr, then the object will be uninstalled and destroyed when the plugin gets unloaded

def requires_color_esc(c)

Checks if the given character requires escaping Is the given char a color escape character?

def tag_addr(ea: ea_t)

tag_addr(ea) -> PyObject * Insert an address mark into a string.

@param ea: (C++: ea_t) address to include

def tag_advance(line: char const *, cnt: int)

tag_advance(line, cnt) -> int Move pointer to a 'line' to 'cnt' positions right. Take into account escape sequences.

@param line: (C++: const char *) pointer to string @param cnt: (C++: int) number of positions to move right @return: moved pointer

def tag_remove(nonnul_instr: char const *)

tag_remove(nonnul_instr) -> str

@param nonnul_instr: char const *

def tag_skipcode(line: char const *)

tag_skipcode(line) -> int Skip one color code. This function should be used if you are interested in color codes and want to analyze all of them. Otherwise tag_skipcodes() function is better since it will skip all colors at once. This function will skip the current color code if there is one. If the current symbol is not a color code, it will return the input.

@param line: (C++: const char *) char const * @return: moved pointer

def tag_skipcodes(line: char const *)

tag_skipcodes(line) -> int Move the pointer past all color codes.

@param line: (C++: const char *) can't be nullptr @return: moved pointer, can't be nullptr

def tag_strlen(line: char const *)

tag_strlen(line) -> ssize_t Calculate length of a colored string This function computes the length in unicode codepoints of a line

@param line: (C++: const char *) char const * @return: the number of codepoints in the line, or -1 on error

def update_extra_cmt(ea: ea_t, what: int, str: char const *)

update_extra_cmt(ea, what, str) -> bool

@param ea: ea_t @param what: int @param str: char const *

Classes

class user_defined_prefix_t (*args)

Proxy of C++ user_defined_prefix_t class.

init(self, prefix_len, owner) -> user_defined_prefix_t

@param prefix_len: size_t @param owner: void const *

Instance variables

var thisown

The membership flag

Methods

def get_user_defined_prefix(self, ea: ea_t, insn: insn_t const &, lnnum: int, indent: int, line: char const *)

get_user_defined_prefix(self, ea, insn, lnnum, indent, line) This callback must be overridden by the derived class.

@param ea: (C++: ea_t) the current address @param insn: (C++: const class insn_t &) the current instruction. if the current item is not an instruction, then insn.itype is zero. @param lnnum: (C++: int) number of the current line (each address may have several listing lines for it). 0 means the very first line for the current address. @param indent: (C++: int) see explanations for gen_printf() @param line: (C++: const char *) the line to be generated. the line usually contains color tags. this argument can be examined to decide whether to generate the prefix.