Setint3breakpoint

int Setint3breakpoint(ulong addr,ulong type,int fnindex,int limit,int count,ulong actions,wchar_t *condition,wchar_t *expression,wchar_t *exprtype);

Adds or modifies INT3 breakpoint of specified basic type(s) (BP_MANUAL, BP_ONESHOT, BP_TEMP or BP_TRACE).
Several types may be set at once or in the separate calls to Setint3breakpoint(). Note that if INT3 breakpoint is set on data or not on the first command byte, debugged application may crash.

Manual breakpoints (BP_MANUAL) are usually set on explicit user request. They have associated limit, condition, expression to protocol and other parameters. If limit is specified, on each break with valid condition OllyDbg increases count . If count is greater or equal to limit, OllyDbg resets count to 0 and pauses process. Note that if count specified in this call is negative, OllyDbg keeps old value.

Temporary breakpoints (BP_TEMP) may specify list of actions. If breakpoint already exists, they are ORed with the available list. If plugins want to get notification via ODBG2_Plugintempbreakpoint(), they must specify action BA_PLUGIN.

Plugins should not set, reset or otherwise modify breakpoints of type BP_TRACE.

Note that when Setint3breakpoint() is called, debugged application must be paused. It is paused when OllyDbg processes debug event or after call to Suspendallthreads(). OllyDbg automatically suspends application when user opens menu. Breakpoint is applied to memory only after the call to Flushmemorycache(), but in all mentioned cases this function is called automatically.


Parameters:

addr
(in) Address of the first byte of the command where INT3 breakpoint should be set
type
(in) Type of the breakpoint, a combination of the following flags:
Basic type of the breakpoint, at least one is required. Breakpoint may have several types at once:
BP_MANUAL - permanent breakpoint set by user
BP_ONESHOT - one-shot breakpoint set by debugging engine. When this breakpoint is hit, OllyDbg removes BP_ONESHOT and pauses the debugged application
BP_TEMP - temporary breakpoint set by debugging engine or plugins. When this breakpoint is hit, OllyDbg removes BP_TEMP (unless action BA_PERMANENT is active), performs actions associated with breakpoint and continues execution
BP_TRACE - used for hit trace, marks unprocessed or unsure branches
All remaining flags are ignored by non-permanent breakpoints:
Features of the permanent breakpoint (BP_MANUAL), a combination of zero or more of the following flags:
BP_DISABLED - breakpoint is disabled
When to pause execution when permanent breakpoint is hit, one of the following flags:
BP_NOBREAK - no pause (default)
BP_CONDBREAK - pause when condition is true
BP_BREAK - pause always
When to protocol the value of expression when permanent breakpoint is hit, one of the following flags:
BP_NOLOG - don't protocol (default)
BP_CONDLOG - protocol if condition is true
BP_LOG - protocol always
When to protocol the arguments of the function that is called or begins at addr when permanent breakpoint is hit, one of the following flags:
BP_NOARG - don't protocol (default)
BP_CONDARG - protocol if condition is true
BP_ARG - protocol always
When to protocol the value returned by a call to function when permanent breakpoint is hit, one of the following flags:
BP_NORET - don't protocol (default)
BP_CONDRET - protocol if condition is true
BP_RET - protocol always
fnindex
(in) Internal index of the prototype that should be used to decode function arguments, or 0 to use arguments of known function or arguments predicted by the Analyser. Applies only to the permanent breakpoints (BP_MANUAL). If fnindex is negative, old index remains active. Currently following prototypes are defined:
  1  WinProcA (hWnd,Msg,wParam,lParam) - ASCII version of window procedure
  2  WinProcW (hWnd,Msg,wParam,lParam) - 
UNICODE version of window procedure
  3  Format1A (format,...) - ASCII printf-like function that specifies format as its first argument
  4  Format1W (format,...) -
UNICODE printf-like function that specifies format as its first argument
  5  Format2A (Arg1,format,...) - ASCII printf-like function that specifies format as its second argument
  6  Format2W (Arg1,format,...) - UNICODE printf-like function that specifies format as its second argument
  7  Format3A (Arg1,Arg2,format,...) - ASCII printf-like function that specifies format as its third argument
  8  Format3W (Arg1,Arg2,format,...) - UNICODE printf-like function that specifies format as its third argument
  9  Format4A (Arg1,Arg2,Arg3,format,...) - ASCII printf-like function that specifies format as its fourth argument
  10 Format4W (Arg1,Arg2,Arg3,format,...) - UNICODE printf-like function that specifies format as its fourth argument
  11 Generic1 (Arg1) - function with 1 argument
  12 Generic2 (Arg1,Arg2)
- function with 2 arguments
  13 Generic3 (Arg1,Arg2,Arg3) - function with 3 arguments
  14 Generic4 (Arg1,Arg2,Arg3,Arg4) - function with 4 arguments
  15 Generic5 (Arg1,Arg2,Arg3,Arg4,Arg5) - function with 5 arguments
  16 Generic6 (Arg1,Arg2,Arg3,Arg4,Arg5,Arg6) - function with 6 arguments
  17 Generic7 (Arg1,Arg2,Arg3,Arg4,Arg5,Arg6,Arg7) - function with 7 arguments
  18 Generic8 (Arg1,Arg2,Arg3,Arg4,Arg5,Arg6,Arg7,Arg8) - function with  arguments
Nothe that this list may change in the new versions of the OllyDbg
limit
(in) Pass count, or 0 if breakpoint should be processed each time it is hit. Applies only to permanent breakpoints
count
(in) Initial value of the pass counter, or negative value if old count should be kept. Applies only to permanent breakpoints
actions
(in) List of actions associated with temporary breakpoint (BP_TEMP). If temporary breakpoint already exists, this list is ORed with the previous. Following actions are defined:
BA_PERMANENT - breakpoint should be kept when hit. If this action is not set, OllyDbg automatically deletes temporary breakpoint
BA_PLUGIN - breakpoint is set by plugin. When hit, OllyDbg calls 
ODBG2_Plugintempbreakpoint()
condition
(in) Null-terminated UNICODE expression at most TEXTLEN wide characters long, or NULL or empty string if conditional processing is not necessary. Applies only to permanent breakpoints. If condition estimates to non-zero value, it activates BP_CONDBREAK, BP_CONDLOG, BP_CONDARG and BP_CONDRET
expression
(in) Null-terminated UNICODE expression at most TEXTLEN wide characters long, or NULL or empty string if protocolling of expressions is not necessary. Applies only to permanent breakpoints. May consist of several subexpressions
exprtype
(in) Null-terminated UNICODE string at most UINCODE characters long, used as an explanation to the protocolled expression. May be NULL or empty string


Return values:

Returns 0 if breakpoint was successfully set and -1 on error


See also:
Breakpoints, expressions, plugins, Confirmint3breakpoint(), Confirmint3breakpointlist(), Enableint3breakpoint(), Removeint3breakpoint()