Expression Functions¶
You may use functions in an expression. The following functions are defined by the debugger:
Strings¶
ansi(addr[, count])
: Reads a null-terminated ANSI string fromaddr
and returns the string value. When acount
is specified the string will be truncated.utf8(addr[, count])
: Reads a null-terminated UTF-8 string fromaddr
and returns the string value. When acount
is specified the string will be truncated.utf16(addr[, count])
: Reads a null-terminated UTF-16 string fromaddr
and returns the string value. When acount
is specified the string will be truncated.strstr(str1, str2)
: Find a substring. Example:strstr(utf8(addr), "abc")
.streq(str1, str2)
: Compare two strings. Example:streq(utf8(addr), "abc")
.strlen(str)
: Calculates the length of a string.
The functions ansi
/utf8
/utf16
can be used as inputs for other functions that take str
arguments. If the addr
cannot be read an empty string is returned. If you want to fail you can use the .strict
variants (for example utf8.strict(rax)
).
The expression utf8(rax)
does not return a number, so it cannot be used as a trace condition for example.
GUI Interaction¶
disasm.sel()
/dis.sel()
: Get the selected address in the disassembly view.dump.sel()
: Get the selected address in the dump view.stack.sel()
: Get the selected address in the stack view.
Source¶
src.disp(addr)
: Get displacement ofaddr
relative to last source line.src.line(addr)
: Get the source line number ofaddr
.
Modules¶
mod.party(addr)
: Get the party number of the moduleaddr
.0
is user module,1
is system module.mod.base(addr)
: Get the base address of the moduleaddr
.mod.size(addr)
: Get the size of the moduleaddr
.mod.hash(addr)
: Get the hash of the moduleaddr
.mod.entry(addr)
: Get the entry address of the moduleaddr
.mod.system(addr)
: True if the module ataddr
is a system module. False: module is a user module.mod.user(addr)
: True if the module ataddr
is a user module. False: module is NOT a user module.mod.main()
: Returns the base of the main module (debuggee). If this is a DLL it will return0
until loaded.mod.rva(addr)
: Get the RVA ofaddr
. Ifaddr
is not inside a module it will return0
.mod.offset(addr)
: Get the file offset ofaddr
. Ifaddr
is not inside a module it will return0
.mod.isexport(addr)
: True ifaddr
is an exported function from a module.mod.fromname(str)
: Gets the module base forstr
.0
if the module is not found. Example:mod.fromname("ntdll.dll")
.
Process Information¶
peb()
: Get PEB address.teb()
: Get TEB address.tid()
: Get the current thread ID.kusd()
,KUSD()
,KUSER_SHARED_DATA()
: Get the address ofKUSER_SHARED_DATA
(0x7FFE0000
).
General Purpose¶
bswap(value)
: Byte-swapvalue
. For example,bswap(44332211)
= 0x11223344.ternary(condition, val1, val2)
: If condition is nonzero, returnval1
, otherwise returnval2
.GetTickCount()
: The Windows APIGetTickCount()
, a timer that increases every 1ms.rdtsc()
: The result of theRDTSC
instruction, a CPU timer. Only 32-bit result is returned in 32-bit environment.isdebuggerfocused()
: Check if x64dbg is focused. Return1
when x64dbg is focused, otherwise return0
.isdebuggeefocused()
: Check if the debugged program is focused. Return1
when the debugged program is focused, otherwise return0
.
Memory¶
mem.valid(addr)
: True ifaddr
is a valid memory address.mem.base(addr)
: Returns the base of the memory page ofaddr
(can change depending on your memory map mode).mem.size(addr)
: Returns the size of the memory page ofaddr
(can change depending on your memory map mode).mem.iscode(addr)
: True ifaddr
is a page that is executable.mem.decodepointer(ptr)
: Equivalent to calling theDecodePointer
API onptr
, only works on Vista+.
Disassembly¶
dis.len(addr)
: Get the length of the instruction ataddr
.dis.iscond(addr)
: True if the instruction ataddr
is a conditional branch.dis.isbranch(addr)
: True if the instruction ataddr
is a branch (jcc/call).dis.isret(addr)
: True if the instruction ataddr
is aret
.dis.iscall(addr)
: True if the instruction ataddr
is acall
.dis.ismem(addr)
: True if the instruction ataddr
has a memory operand.dis.isnop(addr)
: True if the instruction ataddr
is equivalent to a NOP.dis.isunusual(addr)
: True if the instruction ataddr
is unusual.dis.branchdest(addr)
: Branch destination of the instruction ataddr
(what it follows if you press enter on it).dis.branchexec(addr)
: True if the branch ataddr
is going to execute.dis.imm(addr)
: Immediate value of the instruction ataddr
.dis.brtrue(addr)
: Branch destination of the instruction ataddr
.dis.brfalse(addr)
: Address of the next instruction if the instruction ataddr
is a conditional branch.dis.next(addr)
: Address of the next instruction fromaddr
.dis.prev(addr)
: Address of the previous instruction fromaddr
.dis.iscallsystem(addr)
: True if the instruction ataddr
goes to a system module.dis.mnemonic(addr)
: Returns the mnemonicstr
foraddr
. Example:str.streq(dis.mnemonic(cip), "cpuid")
.dis.text(addr)
: Returns the instruction text as a stringaddr
. Can be used for conditions, for example:strstr(dis.text(rip), "rbx")
. Note: the instruction text might not exactly match the formatting in the GUI.dis.match(addr, str)
: True if the instruction ataddr
matches the regex instr
. Example:dis.match(rip, "test.+, 0x1")
. You can usedis.text
to see what you can match on.
Tracing¶
tr.enabled(addr)
: True if the trace coverage is enabled ataddr
.tr.hitcount(addr)
: Number of hits in the trace coverage ataddr
.tr.isrecording()
,tr.runtraceenabled()
: True if trace recording is enabled.
Byte/Word/Dword/Qword/Ptr¶
ReadByte(addr)
,Byte(addr)
,byte(addr)
: Read a byte fromaddr
and return the value. Example:byte(eax)
reads a byte from memory location[eax]
.ReadWord(addr)
,Word(addr)
,word(addr)
: Read a word (2 bytes) fromaddr
and return the value.ReadDword(addr)
,Dword(addr)
,dword(addr)
: Read a dword (4 bytes) fromaddr
and return the value.ReadQword(addr)
,Qword(addr)
,qword(addr)
: Read a qword (8 bytes) fromaddr
and return the value (only available on x64).ReadPtr(addr)
,ReadPointer(addr)
,ptr(addr)
,Pointer(addr)
,pointer(addr)
: Read a pointer (4/8 bytes) fromaddr
and return the value.
These expression functions return 0
when addr
is not valid.
Functions¶
func.start()
: Return start of the functionaddr
is part of, zero otherwise.func.end()
: Return end of the functionaddr
is part of, zero otherwise.
References¶
ref.count()
: Number of entries in the current reference view.ref.addr(index)
: Get the address of the reference atindex
. Zero on failure.
Arguments¶
This assumes the return address is on the stack (eg you are inside the function).
arg.get(index)
: Gets the argument atindex
(zero-based).arg.set(index, value)
: Sets the argument atindex
(zero-based) tovalue
.
Exceptions¶
This is a set of functions to get information about the last exception. They can be used for exceptions breakpoints to construct more advanced conditions.
ex.firstchance()
: Whether the last exception was a first chance exception.ex.addr()
: Last exception address. For example the address of the instruction that caused the exception.ex.code()
: Last exception code.ex.flags()
: Last exception flags.ex.infocount()
: Last exception information count (number of parameters).ex.info(index)
: Last exception information, zero if index is out of bounds. For access violations or memory breakpointsex.info(1)
contains the address of the accessed memory (see EXCEPTION_RECORD.ExceptionInformation for details).
Plugins¶
Plugins can register their own expression functions. You can find an example in the StackContains plugin. Relevant functions:
_plugin_registerexprfunction
_plugin_registerexprfunctionex
_plugin_unregisterexprfunction