Magic-Mirror/capstone
1
0
Fork 0
mirror of https://github.com/capstone-engine/capstone.git synced 2025-03-05 04:47:21 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

capstone.h: add notes on cs_disasm() vs cs_disasm_iter()

Browse Source
This commit is contained in:
Nguyen Anh Quynh 2014-10-20 23:32:06 +08:00
parent 257ea59241
commit 024e55ebeb
1 changed files with 18 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
include/capstone.h
View File

@ -382,8 +382,17 @@ const char *cs_strerror(cs_err code);
NOTE 1: this API will automatically determine memory needed to contain
output disassembled instructions in @insn.
NOTE 2: caller must free the allocated memory itself to avoid memory leaking.
NOTE 3: for system with scarce memory to be dynamically allocated such as
OS kernel or firmware, the API cs_disasm_iter() might be a better choice than
cs_disasm(). 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 uncontrolly (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 the above code buffer.
@ -454,6 +463,15 @@ cs_insn *cs_malloc(csh handle);
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 uncontrolly (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