Module index

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