Module ida_funcs

IDA Plugin SDK API wrapper: funcs

Classes
	func_item_iterator_t Proxy of C++ func_item_iterator_t class.
	func_parent_iterator_t Proxy of C++ func_parent_iterator_t class.
	func_t Proxy of C++ func_t class.
	func_tail_iterator_t Proxy of C++ func_tail_iterator_t class.
	lock_func Proxy of C++ lock_func class.
	range_array Proxy of C++ dynamic_wrapped_array_t< range_t > class.
	regarg_t Proxy of C++ regarg_t class.
	regvar_array Proxy of C++ dynamic_wrapped_array_t< regvar_t > class.
	stkpnt_array Proxy of C++ dynamic_wrapped_array_t< stkpnt_t > class.

Functions

bool

add_func(ea1, ea2=BADADDR)
Add a new function.

bool

add_func_ex(pfn)
Add a new function.

add_regarg(pfn, reg, tif, name)

bool

append_func_tail(pfn, ea1, ea2)
Append a new tail chunk to the function definition.

int

apply_idasgn_to(signame, ea, is_startup)
Apply a signature file to the specified address.

bool

apply_startup_sig(ea, startup)
Apply a startup signature file to the specified address.

asize_t

calc_func_size(pfn)
Calculate function size.

int

calc_idasgn_state(n)
Get state of a signature in the list of planned signatures

ea_t

calc_thunk_func_target(pfn)
Calculate target of a thunk function.

bool

del_func(ea)
Delete a function.

int

del_idasgn(n)
Remove signature from the list of planned signatures.

bool

f_any(arg1, arg2)
Helper function to accept any address.

int

find_func_bounds(nfn, flags)
Determine the boundaries of a new function.

bool

func_contains(pfn, ea)
Does the given function contain the given address?

bool

func_does_return(callee)
Does the function return?.

bool

func_item_iterator_decode_preceding_insn(fii, visited, p_farref, out)

bool

func_item_iterator_decode_prev_insn(fii, out)

bool

func_item_iterator_next(fii, testf, ud)

bool

func_item_iterator_prev(fii, testf, ud)

bool

func_parent_iterator_set(fpi, pfn)

func_t

func_t__from_ptrval__(ptrval)

bool

func_tail_iterator_set(fti, pfn, ea)

bool

func_tail_iterator_set_ea(fti, ea)

int

get_current_idasgn()
Get number of the the current signature.

func_t

get_fchunk(ea)
Get pointer to function chunk structure by address.

int

get_fchunk_num(ea)
Get ordinal number of a function chunk in the global list of function chunks.

size_t

get_fchunk_qty()
Get total number of function chunks in the program.

ea_t

get_fchunk_referer(ea, idx)

func_t

get_func(ea)
Get pointer to function structure by address.

int

get_func_bitness(pfn)
Get function bitness (which is equal to the function segment bitness).

int

get_func_bits(pfn)
Get number of bits in the function addressing.

int

get_func_bytes(pfn)
Get number of bytes in the function addressing.

int

get_func_chunknum(pfn, ea)
Get the containing tail chunk of 'ea'.

str

get_func_cmt(pfn, repeatable)
Get function comment.

str

get_func_name(ea)
Get function name.

int

get_func_num(ea)
Get ordinal number of a function.

size_t

get_func_qty()
Get total number of functions in the program.

ea_t

get_func_ranges(ranges, pfn)
Get function ranges.

PyObject *

get_idasgn_desc(n)
Get information about a signature in the list.

PyObject *

get_idasgn_desc_with_matches(n)
Get information about a signature in the list.

int

get_idasgn_qty()
Get number of signatures in the list of planned and applied signatures.

str

get_idasgn_title(name)
Get full description of the signature by its short name.

func_t

get_next_fchunk(ea)
Get pointer to the next function chunk in the global list.

func_t

get_next_func(ea)
Get pointer to the next function.

ea_t

get_next_func_addr(pfn, ea)

func_t

get_prev_fchunk(ea)
Get pointer to the previous function chunk in the global list.

func_t

get_prev_func(ea)
Get pointer to the previous function.

ea_t

get_prev_func_addr(pfn, ea)

func_t

getn_fchunk(n)
Get pointer to function chunk structure by number.

func_t

getn_func(n)
Get pointer to function structure by number.

bool

is_finally_visible_func(pfn)
Is the function visible (event after considering 'SCF_SHHID_FUNC' )?

bool

is_func_entry(pfn)
Does function describe a function entry chunk?

bool

is_func_locked(pfn)
Is the function pointer locked?

bool

is_func_tail(pfn)
Does function describe a function tail chunk?

bool

is_same_func(ea1, ea2)
Do two addresses belong to the same function?

bool

is_visible_func(pfn)
Is the function visible (not hidden)?

lock_func_range(pfn, lock)
Lock function pointer Locked pointers are guaranteed to remain valid until they are unlocked.

int

plan_to_apply_idasgn(fname)
Add a signature file to the list of planned signature files.

read_regargs(pfn)

reanalyze_function(pfn, ea1=0, ea2=BADADDR, analyze_parents=False)
Reanalyze a function.

bool

reanalyze_noret_flag(ea)
Plan to reanalyze noret flag.

bool

remove_func_tail(pfn, tail_ea)
Remove a function tail.

bool

set_func_cmt(pfn, cmt, repeatable)
Set function comment.

bool

set_func_end(ea, newend)
Move function chunk end address.

int

set_func_name_if_jumpfunc(pfn, oldname)
Give a meaningful name to function if it consists of only 'jump' instruction.

int

set_func_start(ea, newstart)
Move function chunk start address.

bool

set_noret_insn(insn_ea, noret)
Signal a non-returning instruction.

bool

set_tail_owner(fnt, func_start)
Set a function as the possessing function of a function tail.

set_visible_func(pfn, visible)
Set visibility of function.

int

try_to_add_libfunc(ea)
Apply the currently loaded signature file to the specified address.

bool

update_func(pfn)
Update information about a function in the database ( 'func_t' ).

Variables
	FIND_FUNC_DEFINE = `1`
	FIND_FUNC_EXIST = `2`
	FIND_FUNC_IGNOREFN = `2`
	FIND_FUNC_KEEPBD = `4`
	FIND_FUNC_NORMAL = `0`
	FIND_FUNC_OK = `1`
	FIND_FUNC_UNDEF = `0`
	FUNC_BOTTOMBP = `256`
	FUNC_FAR = `2`
	FUNC_FRAME = `16`
	FUNC_FUZZY_SP = `2048`
	FUNC_HIDDEN = `64`
	FUNC_LIB = `4`
	FUNC_LUMINA = `65536`
	FUNC_NORET = `1`
	FUNC_NORET_PENDING = `512`
	FUNC_PROLOG_OK = `4096`
	FUNC_PURGED_OK = `16384`
	FUNC_SP_READY = `1024`
	FUNC_STATICDEF = `8`
	FUNC_TAIL = `32768`
	FUNC_THUNK = `128`
	FUNC_USERFAR = `32`
	IDASGN_APPLIED = `2`
	IDASGN_BADARG = `1`
	IDASGN_CURRENT = `3`
	IDASGN_OK = `0`
	IDASGN_PLANNED = `4`
	LIBFUNC_DELAY = `2`
	LIBFUNC_FOUND = `0`
	LIBFUNC_NONE = `1`
	MOVE_FUNC_BADSTART = `2`
	MOVE_FUNC_NOCODE = `1`
	MOVE_FUNC_NOFUNC = `3`
	MOVE_FUNC_OK = `0`
	MOVE_FUNC_REFUSED = `4`
	SWIG_PYTHON_LEGACY_BOOL = `1`
	__package__ = `None`

Function Details

add_func(ea1, ea2=BADADDR)

Add a new function. If the function end address is 'BADADDR' , then IDA will try to determine the function bounds by calling find_func_bounds(..., 'FIND_FUNC_DEFINE' ).

Parameters:

ea1 - start address (C++: ea_t)
ea2 - end address (C++: ea_t)

Returns: bool

success

add_func_ex(pfn)

Add a new function. If the fn->end_ea is 'BADADDR' , then IDA will try to determine the function bounds by calling find_func_bounds(..., 'FIND_FUNC_DEFINE' ).

Parameters:

pfn - ptr to filled function structure (C++: func_t *)

Returns: bool

success

append_func_tail(pfn, ea1, ea2)

Append a new tail chunk to the function definition. If the tail already exists, then it will simply be added to the function tail list Otherwise a new tail will be created and its owner will be set to be our function If a new tail cannot be created, then this function will fail.

Parameters:

pfn, (C++ - func_t *)
ea1 - start of the tail. If a tail already exists at the specified address it must start at 'ea1' (C++: ea_t)
ea2 - end of the tail. If a tail already exists at the specified address it must end at 'ea2'. If specified as BADADDR, IDA will determine the end address itself. (C++: ea_t)

Returns: bool

apply_idasgn_to(signame, ea, is_startup)

Apply a signature file to the specified address.

Parameters:

signame - short name of signature file (the file name without path) (C++: const char *)
ea - address to apply the signature (C++: ea_t)
is_startup - if set, then the signature is treated as a startup one for startup signature ida doesn't rename the first function of the applied module. (C++: bool)

Returns: int

Library function codes

apply_startup_sig(ea, startup)

Apply a startup signature file to the specified address.

Parameters:

ea - address to apply the signature to; usually \inf{start_ea} (C++: ea_t)
startup - the name of the signature file without path and extension (C++: const char *)

Returns: bool

true if successfully applied the signature

calc_func_size(pfn)

Calculate function size. This function takes into account all fragments of the function.

Parameters:

pfn - ptr to function structure (C++: func_t *)

Returns: asize_t

calc_idasgn_state(n)

Get state of a signature in the list of planned signatures

Parameters:

n - number of signature in the list (0.. get_idasgn_qty() -1) (C++: int)

Returns: int

state of signature or IDASGN_BADARG

calc_thunk_func_target(pfn)

Calculate target of a thunk function.

Parameters:

pfn - pointer to function (may not be NULL) (C++: func_t *)

Returns: ea_t

the target function or BADADDR

del_func(ea)

Delete a function.

Parameters:

ea - any address in the function entry chunk (C++: ea_t)

Returns: bool

success

del_idasgn(n)

Remove signature from the list of planned signatures.

Parameters:

n - number of signature in the list (0.. get_idasgn_qty() -1) (C++: int)

Returns: int

IDASGN_OK , IDASGN_BADARG , IDASGN_APPLIED

find_func_bounds(nfn, flags)

Determine the boundaries of a new function. This function tries to find the start and end addresses of a new function. It calls the module with \ph{func_bounds} in order to fine tune the function boundaries.

Parameters:

nfn - structure to fill with information \ nfn->start_ea points to the start address of the new function. (C++: func_t *)
flags - Find function bounds flags (C++: int)

Returns: int

Find function bounds result codes

func_contains(pfn, ea)

Does the given function contain the given address?

Parameters:

pfn, (C++ - func_t *)
ea, (C++ - ea_t)

Returns: bool

func_does_return(callee)

Does the function return?. To calculate the answer, 'FUNC_NORET' flag and is_noret() are consulted The latter is required for imported functions in the .idata section. Since in .idata we have only function pointers but not functions, we have to introduce a special flag for them.

Parameters:

callee, (C++ - ea_t)

Returns: bool

get_current_idasgn()

Get number of the the current signature.

Returns: int: 0..n-1

get_fchunk(ea)

Get pointer to function chunk structure by address.

Parameters:

ea - any address in a function chunk (C++: ea_t)

Returns: func_t

ptr to a function chunk or NULL. This function may return a function entry as well as a function tail.

get_fchunk_num(ea)

Get ordinal number of a function chunk in the global list of function chunks.

Parameters:

ea - any address in the function chunk (C++: ea_t)

Returns: int

number of function chunk (0.. get_fchunk_qty() -1). -1 means 'no function chunk at the specified address'.

get_func(ea)

Get pointer to function structure by address.

Parameters:

ea - any address in a function (C++: ea_t)

Returns: func_t

ptr to a function or NULL. This function returns a function entry chunk.

get_func_bitness(pfn)

Get function bitness (which is equal to the function segment bitness). pfn==NULL => returns 0

Parameters:

pfn, (C++ - const func_t *)

Returns: int

get_func_bits(pfn)

Get number of bits in the function addressing.

Parameters:

pfn, (C++ - const func_t *)

Returns: int

get_func_bytes(pfn)

Get number of bytes in the function addressing.

Parameters:

pfn, (C++ - const func_t *)

Returns: int

get_func_chunknum(pfn, ea)

Get the containing tail chunk of 'ea'.

Parameters:

pfn, (C++ - func_t *)
ea, (C++ - ea_t)

Returns: int

get_func_cmt(pfn, repeatable)

Get function comment.

Parameters:

pfn - ptr to function structure (C++: const func_t *)
repeatable - get repeatable comment? (C++: bool)

Returns: str

size of comment or -1 In fact this function works with function chunks too.

get_func_name(ea)

Get function name.

Parameters:

ea - any address in the function (C++: ea_t)

Returns: str

length of the function name

get_func_num(ea)

Get ordinal number of a function.

Parameters:

ea - any address in the function (C++: ea_t)

Returns: int

number of function (0.. get_func_qty() -1). -1 means 'no function at the specified address'.

get_func_ranges(ranges, pfn)

Get function ranges.

Parameters:

ranges - buffer to receive the range info (C++: rangeset_t *)
pfn - ptr to function structure (C++: func_t *)

Returns: ea_t

end address of the last function range (BADADDR-error)

get_idasgn_desc(n)

Get information about a signature in the list. It returns: (name of signature, names of optional libraries)

get_idasgn_desc_with_matches(n)

Get information about a signature in the list. It returns: (name of signature, names of optional libraries, number of matches)

Parameters:

n - number of signature in the list (0..get_idasgn_qty()-1)

Returns: PyObject *

None on failure or tuple(signame, optlibs, nmatches)

get_idasgn_qty()

Get number of signatures in the list of planned and applied signatures.

Returns: int: 0..n

get_idasgn_title(name)

Get full description of the signature by its short name.

Parameters:

name - short name of a signature (C++: const char *)

Returns: str

size of signature description or -1

get_next_fchunk(ea)

Get pointer to the next function chunk in the global list.

Parameters:

ea - any address in the program (C++: ea_t)

Returns: func_t

ptr to function chunk or NULL if next function chunk doesn't exist

get_next_func(ea)

Get pointer to the next function.

Parameters:

ea - any address in the program (C++: ea_t)

Returns: func_t

ptr to function or NULL if next function doesn't exist

get_prev_fchunk(ea)

Get pointer to the previous function chunk in the global list.

Parameters:

ea - any address in the program (C++: ea_t)

Returns: func_t

ptr to function chunk or NULL if previous function chunk doesn't exist

get_prev_func(ea)

Get pointer to the previous function.

Parameters:

ea - any address in the program (C++: ea_t)

Returns: func_t

ptr to function or NULL if previous function doesn't exist

getn_fchunk(n)

Get pointer to function chunk structure by number.

Parameters:

n - number of function chunk, is in range 0.. get_fchunk_qty() -1 (C++: int)

Returns: func_t

ptr to a function chunk or NULL. This function may return a function entry as well as a function tail.

getn_func(n)

Get pointer to function structure by number.

Parameters:

n - number of function, is in range 0.. get_func_qty() -1 (C++: size_t)

Returns: func_t

ptr to a function or NULL. This function returns a function entry chunk.

is_finally_visible_func(pfn)

Is the function visible (event after considering 'SCF_SHHID_FUNC' )?

Parameters:

pfn, (C++ - func_t *)

Returns: bool

is_func_entry(pfn)

Does function describe a function entry chunk?

Parameters:

pfn, (C++ - const func_t *)

Returns: bool

is_func_locked(pfn)

Is the function pointer locked?

Parameters:

pfn, (C++ - const func_t *)

Returns: bool

is_func_tail(pfn)

Does function describe a function tail chunk?

Parameters:

pfn, (C++ - const func_t *)

Returns: bool

is_same_func(ea1, ea2)

Do two addresses belong to the same function?

Parameters:

ea1, (C++ - ea_t)
ea2, (C++ - ea_t)

Returns: bool

is_visible_func(pfn)

Is the function visible (not hidden)?

Parameters:

pfn, (C++ - func_t *)

Returns: bool

lock_func_range(pfn, lock)

Lock function pointer Locked pointers are guaranteed to remain valid until they are unlocked. Ranges with locked pointers cannot be deleted or moved.

Parameters:

pfn, (C++ - const func_t *)
lock, (C++ - bool)

plan_to_apply_idasgn(fname)

Add a signature file to the list of planned signature files.

Parameters:

fname - file name. should not contain directory part. (C++: const char *)

Returns: int

0 if failed, otherwise number of planned (and applied) signatures

reanalyze_function(pfn, ea1=0, ea2=BADADDR, analyze_parents=False)

Reanalyze a function. This function plans to analyzes all chunks of the given function. Optional parameters (ea1, ea2) may be used to narrow the analyzed range.

Parameters:

pfn - pointer to a function (C++: func_t *)
ea1 - start of the range to analyze (C++: ea_t)
ea2 - end of range to analyze (C++: ea_t)
analyze_parents - meaningful only if pfn points to a function tail. if true, all tail parents will be reanalyzed. if false, only the given tail will be reanalyzed. (C++: bool)

reanalyze_noret_flag(ea)

Plan to reanalyze noret flag. This function does not remove FUNC_NORET if it is already present. It just plans to reanalysis.

Parameters:

ea, (C++ - ea_t)

Returns: bool

remove_func_tail(pfn, tail_ea)

Remove a function tail. If the tail belongs only to one function, it will be completely removed. Otherwise if the function was the tail owner, the first function using this tail becomes the owner of the tail.

Parameters:

pfn, (C++ - func_t *)
tail_ea, (C++ - ea_t)

Returns: bool

set_func_cmt(pfn, cmt, repeatable)

Set function comment. This function works with function chunks too.

Parameters:

pfn - ptr to function structure (C++: const func_t *)
cmt - comment string, may be multiline (with ' '). Use empty str ("") to delete comment (C++: const char *)
repeatable - set repeatable comment? (C++: bool)

Returns: bool

set_func_end(ea, newend)

Move function chunk end address.

Parameters:

ea - any address in the function (C++: ea_t)
newend - new end address of the function (C++: ea_t)

Returns: bool

success

set_func_name_if_jumpfunc(pfn, oldname)

Give a meaningful name to function if it consists of only 'jump' instruction.

Parameters:

pfn - pointer to function (may be NULL) (C++: func_t *)
oldname - old name of function. if old name was in "j_..." form, then we may discard it and set a new name. if oldname is not known, you may pass NULL. (C++: const char *)

Returns: int

success

set_func_start(ea, newstart)

Move function chunk start address.

Parameters:

ea - any address in the function (C++: ea_t)
newstart - new end address of the function (C++: ea_t)

Returns: int

Function move result codes

set_noret_insn(insn_ea, noret)

Signal a non-returning instruction. This function can be used by the processor module to tell the kernel about non-returning instructions (like call exit). The kernel will perform the global function analysis and find out if the function returns at all. This analysis will be done at the first call to 'func_does_return()'

Parameters:

insn_ea, (C++ - ea_t)
noret, (C++ - bool)

Returns: bool

true if the instruction 'noret' flag has been changed

set_tail_owner(fnt, func_start)

Set a function as the possessing function of a function tail. The function should already refer to the tail (after append_func_tail).

Parameters:

fnt, (C++ - func_t *)
func_start, (C++ - ea_t)

Returns: bool

set_visible_func(pfn, visible)

Set visibility of function.

Parameters:

pfn, (C++ - func_t *)
visible, (C++ - bool)

try_to_add_libfunc(ea)

Apply the currently loaded signature file to the specified address. If a library function is found, then create a function and name it accordingly.

Parameters:

ea - any address in the program (C++: ea_t)

Returns: int

Library function codes

update_func(pfn)

Update information about a function in the database ( 'func_t' ). You must not change the function start and end addresses using this function. Use 'set_func_start()' and 'set_func_end()' for it.

Parameters:

pfn - ptr to function structure (C++: func_t *)

Returns: bool

success