Module ida_funcs
[frames] | no frames]

Module ida_funcs

IDA Plugin SDK API wrapper: funcs

Classes
  stkpnt_array
Proxy of C++ dynamic_wrapped_array_t<(stkpnt_t)> class
  regvar_array
Proxy of C++ dynamic_wrapped_array_t<(regvar_t)> class
  range_array
Proxy of C++ dynamic_wrapped_array_t<(range_t)> class
  regarg_t
Proxy of C++ regarg_t class
  func_t
Proxy of C++ func_t class
  lock_func
Proxy of C++ lock_func class
  func_tail_iterator_t
Proxy of C++ func_tail_iterator_t class
  func_item_iterator_t
Proxy of C++ func_item_iterator_t class
  func_parent_iterator_t
Proxy of C++ func_parent_iterator_t class
Functions
bool
is_func_entry(pfn)
Does function describe a function entry chunk?
bool
is_func_tail(pfn)
Does function describe a function tail chunk?
 
lock_func_range(pfn, lock)
Lock function pointer Locked pointers are guaranteed to remain valid until they are unlocked.
bool
is_func_locked(pfn)
Is the function pointer locked?
func_t
get_func(ea)
Get pointer to function structure by address.
int
get_func_chunknum(pfn, ea)
Get the containing tail chunk of 'ea'.
bool
func_contains(pfn, ea)
Does the given function contain the given address?
bool
is_same_func(ea1, ea2)
Do two addresses belong to the same function?
func_t
getn_func(n)
Get pointer to function structure by number.
size_t
get_func_qty()
Get total number of functions in the program.
int
get_func_num(ea)
Get ordinal number of a function.
func_t
get_prev_func(ea)
Get pointer to the previous function.
func_t
get_next_func(ea)
Get pointer to the next function.
ea_t
get_func_ranges(ranges, pfn)
Get function ranges.
ssize_t
get_func_cmt(pfn, repeatable)
Get function comment.
bool
set_func_cmt(pfn, cmt, repeatable)
Set function comment.
bool
update_func(pfn)
Update information about a function in the database ( 'func_t' ).
bool
add_func_ex(pfn)
Add a new function.
bool
add_func(ea1, ea2=BADADDR)
Add a new function.
bool
del_func(ea)
Delete a function.
int
set_func_start(ea, newstart)
Move function chunk start address.
bool
set_func_end(ea, newend)
Move function chunk end address.
 
reanalyze_function(pfn, ea1=0, ea2=BADADDR, analyze_parents=False)
Reanalyze a function.
int
find_func_bounds(nfn, flags)
Determine the boundaries of a new function.
ssize_t
get_func_name(ea)
Get function name.
asize_t
calc_func_size(pfn)
Calculate function size.
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.
bool
is_visible_func(pfn)
Is the function visible (not hidden)?
bool
is_finally_visible_func(pfn)
Is the function visible (event after considering 'SCF_SHHID_FUNC' )?
 
set_visible_func(pfn, visible)
Set visibility of function.
int
set_func_name_if_jumpfunc(pfn, oldname)
Give a meaningful name to function if it consists of only 'jump' instruction.
bool
func_does_return(callee)
Does the function return?.
bool
reanalyze_noret_flag(ea)
Plan to reanalyze noret flag.
bool
set_noret_insn(insn_ea, noret)
Signal a non-returning instruction.
func_t
get_fchunk(ea)
Get pointer to function chunk structure by address.
func_t
getn_fchunk(n)
Get pointer to function chunk structure by number.
size_t
get_fchunk_qty()
Get total number of function chunks in the program.
int
get_fchunk_num(ea)
Get ordinal number of a function chunk in the global list of function chunks.
func_t
get_prev_fchunk(ea)
Get pointer to the previous function chunk in the global list.
func_t
get_next_fchunk(ea)
Get pointer to the next function chunk in the global list.
bool
append_func_tail(pfn, ea1, ea2)
Append a new tail chunk to the function definition.
bool
remove_func_tail(pfn, tail_ea)
Remove a function tail.
bool
set_tail_owner(fnt, func_start)
Set a function as the possessing function of a function tail.
bool
func_tail_iterator_set(fti, pfn, ea)
bool
func_tail_iterator_set_ea(fti, ea)
bool
func_parent_iterator_set(fpi, pfn)
bool
func_item_iterator_next(fii, testf, ud)
bool
func_item_iterator_prev(fii, testf, ud)
bool
func_item_iterator_decode_prev_insn(fii, out)
bool
func_item_iterator_decode_preceding_insn(fii, visited, p_farref, out)
bool
f_any(arg1, arg2)
Helper function to accept any address.
ea_t
get_prev_func_addr(pfn, ea)
ea_t
get_next_func_addr(pfn, ea)
 
read_regargs(pfn)
 
add_regarg(pfn, reg, tif, name)
int
plan_to_apply_idasgn(fname)
Add a signature file to the list of planned signature files.
int
apply_idasgn_to(signame, ea, is_startup)
Apply a signature file to the specified address.
int
get_idasgn_qty()
Get number of signatures in the list of planned and applied signatures.
int
get_current_idasgn()
Get number of the the current signature.
int
calc_idasgn_state(n)
Get state of a signature in the list of planned signatures
int
del_idasgn(n)
Remove signature from the list of planned signatures.
ssize_t
get_idasgn_title(name)
Get full description of the signature by its short name.
bool
apply_startup_sig(ea, startup)
Apply a startup signature file to the specified address.
int
try_to_add_libfunc(ea)
Apply the currently loaded signature file to the specified address.
ea_t
get_fchunk_referer(ea, idx)
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.
func_t
func_t__from_ptrval__(ptrval)
ea_t
calc_thunk_func_target(pfn)
Calculate target of a thunk function.
Variables
  FUNC_NORET = 1
Function doesn't return.
  FUNC_FAR = 2
Far function.
  FUNC_LIB = 4
Library function.
  FUNC_STATICDEF = 8
Static function.
  FUNC_FRAME = 16
Function uses frame pointer (BP)
  FUNC_USERFAR = 32
of the function
  FUNC_HIDDEN = 64
A hidden function chunk.
  FUNC_THUNK = 128
Thunk (jump) function.
  FUNC_BOTTOMBP = 256
BP points to the bottom of the stack frame.
  FUNC_NORET_PENDING = 512
This flag is verified upon 'func_does_return()'
  FUNC_SP_READY = 1024
SP-analysis has been performed.
  FUNC_FUZZY_SP = 2048
for example: and esp, 0FFFFFFF0h
  FUNC_PROLOG_OK = 4096
by last SP-analysis
  FUNC_PURGED_OK = 16384
'argsize' field has been validated.
  FUNC_TAIL = 32768
This is a function tail.
  FUNC_LUMINA = 65536
Function info is provided by Lumina.
  MOVE_FUNC_OK = 0
ok
  MOVE_FUNC_NOCODE = 1
no instruction at 'newstart'
  MOVE_FUNC_BADSTART = 2
bad new start address
  MOVE_FUNC_NOFUNC = 3
no function at 'ea'
  MOVE_FUNC_REFUSED = 4
a plugin refused the action
  FIND_FUNC_NORMAL = 0
stop processing if undefined byte is encountered
  FIND_FUNC_DEFINE = 1
create instruction if undefined byte is encountered
  FIND_FUNC_IGNOREFN = 2
ignore existing function boundaries.
  FIND_FUNC_KEEPBD = 4
just create instructions inside the boundaries.
  FIND_FUNC_UNDEF = 0
nfn->end_ea will have the address of the unexplored byte.
  FIND_FUNC_OK = 1
ok, 'nfn' is ready for 'add_func()'
  FIND_FUNC_EXIST = 2
its bounds are returned in 'nfn'.
  IDASGN_OK = 0
ok
  IDASGN_BADARG = 1
bad number of signature
  IDASGN_APPLIED = 2
signature is already applied
  IDASGN_CURRENT = 3
signature is currently being applied
  IDASGN_PLANNED = 4
signature is planned to be applied
  LIBFUNC_FOUND = 0
ok, library function is found
  LIBFUNC_NONE = 1
no, this is not a library function
  LIBFUNC_DELAY = 2
no decision because of lack of information
  __package__ = None
Function Details

is_func_entry(pfn)

 

Does function describe a function entry chunk?

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

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)

is_func_locked(pfn)

 

Is the function pointer locked?

Parameters:
  • pfn, (C++ - const func_t *)
Returns: bool

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_chunknum(pfn, ea)

 

Get the containing tail chunk of 'ea'.

Parameters:
  • pfn, (C++ - func_t *)
  • ea, (C++ - ea_t)
Returns: int

func_contains(pfn, ea)

 

Does the given function contain the given address?

Parameters:
  • pfn, (C++ - func_t *)
  • ea, (C++ - ea_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

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.

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_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

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_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_func_cmt(pfn, repeatable)

 

Get function comment.

Parameters:
  • pfn - ptr to function structure (C++: const func_t *)
  • repeatable - get repeatable comment? (C++: bool)
Returns: ssize_t
size of comment or -1 In fact this function works with function chunks too.

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

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

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

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

del_func(ea)

 

Delete a function.

Parameters:
  • ea - any address in the function entry chunk (C++: ea_t)
Returns: bool
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_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

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)

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

get_func_name(ea)

 

Get function name.

Parameters:
  • ea - any address in the function (C++: ea_t)
Returns: ssize_t
length of the function name

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

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

is_visible_func(pfn)

 

Is the function visible (not hidden)?

Parameters:
  • pfn, (C++ - func_t *)
Returns: bool

is_finally_visible_func(pfn)

 

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

Parameters:
  • pfn, (C++ - func_t *)
Returns: bool

set_visible_func(pfn, visible)

 

Set visibility of function.

Parameters:
  • pfn, (C++ - func_t *)
  • visible, (C++ - bool)

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

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

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

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

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.

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.

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_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_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

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

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_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

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

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

get_idasgn_qty()

 

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

Returns: int
0..n

get_current_idasgn()

 

Get number of the the current signature.

Returns: int
0..n-1

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

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

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: ssize_t
size of signature description or -1

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

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

get_idasgn_desc(n)

 

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

See also: get_idasgn_desc_with_matches

Parameters:
  • n - number of signature in the list (0..get_idasgn_qty()-1)
Returns: PyObject *
None on failure or tuple(signame, optlibs)

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)

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
Decorators:
  • @ida_idaapi.replfun

Variables Details

FUNC_USERFAR

of the function

User has specified far-ness

Value:
32

FUNC_NORET_PENDING

This flag is verified upon 'func_does_return()'

Function 'non-return' analysis must be performed.

Value:
512

FUNC_SP_READY

SP-analysis has been performed. If this flag is on, the stack change points should not be not modified anymore. Currently this analysis is performed only for PC

Value:
1024

FUNC_FUZZY_SP

for example: and esp, 0FFFFFFF0h

Function changes SP in untraceable way,

Value:
2048

FUNC_PROLOG_OK

by last SP-analysis

Prolog analysis has be performed

Value:
4096

FUNC_PURGED_OK

'argsize' field has been validated. If this bit is clear and 'argsize' is 0, then we do not known the real number of bytes removed from the stack. This bit is handled by the processor module.

Value:
16384

FUNC_TAIL

This is a function tail. Other bits must be clear (except 'FUNC_HIDDEN' ).

Value:
32768

FIND_FUNC_IGNOREFN

ignore existing function boundaries. by default the function returns function boundaries if ea belongs to a function.

Value:
2

FIND_FUNC_KEEPBD

just create instructions inside the boundaries.

do not modify incoming function boundaries,

Value:
4

FIND_FUNC_UNDEF

nfn->end_ea will have the address of the unexplored byte.

function has instructions that pass execution flow to unexplored bytes.

Value:
0

FIND_FUNC_EXIST

its bounds are returned in 'nfn'.

function exists already.

Value:
2