Function capstone_sys::cs_disasm_iter [−] [src]

pub unsafe extern "C" fn cs_disasm_iter(
    handle: csh, 
    code: *mut *const u8, 
    size: *mut usize, 
    address: *mut u64, 
    insn: *mut cs_insn
) -> bool

Fast API to disassemble binary code, given the code buffer, size, address and number of instructions to be decoded. This API put the resulted instruction into a given cache in @insn. See tests/test_iter.c for sample code demonstrating this API.

NOTE 1: this API will update code, size & address to point to the next instruction in the input buffer. Therefore, it is convenient to use cs_disasm_iter() inside a loop to quickly iterate all the instructions. While decoding one instruction at a time can also be achieved with cs_disasm(count=1), some benchmarks shown that cs_disasm_iter() can be 30% faster on random input.

NOTE 2: the cache in insn can be created with cs_malloc() API.

NOTE 3: for system with scarce memory to be dynamically allocated such as OS kernel or firmware, this API is recommended over cs_disasm(), which allocates memory based on the number of instructions to be disassembled. The reason is that with cs_disasm(), based on limited available memory, we have to calculate in advance how many instructions to be disassembled, which complicates things. This is especially troublesome for the case count=0, when cs_disasm() runs uncontrollably (until either end of input buffer, or when it encounters an invalid instruction).

  • handle: handle returned by cs_open()
  • code: buffer containing raw binary code to be disassembled
  • code_size: size of above code
  • address: address of the first insn in given raw code buffer
  • insn: pointer to instruction to be filled in by this API.

return: true if this API successfully decode 1 instruction, or false otherwise.

On failure, call cs_errno() for error code.