Detecting Patterns With Recognizers#

Frame recognizers allow for retrieving information about special frames based on ABI, arguments or other special properties of that frame, even without source code or debug info. Currently, one use case is to extract function arguments that would otherwise be inaccessible, or augment existing arguments.

Adding a custom frame recognizer is done by implementing a Python class and using the frame recognizer add command. The Python class should implement the get_recognized_arguments method and it will receive an argument of type lldb.SBFrame representing the current frame that we are trying to recognize. The method should return a (possibly empty) list of lldb.SBValue objects that represent the recognized arguments.

An example of a recognizer that retrieves the file descriptor values from libc functions ‘read’, ‘write’ and ‘close’ follows:

class LibcFdRecognizer:
 def get_recognized_arguments(self, frame: lldb.SBFrame):
 if frame.name in ["read", "write", "close"]:
 fd = frame.EvaluateExpression("$arg1").unsigned
 target = frame.thread.process.target
 value = target.CreateValueFromExpression("fd", "(int)%d" % fd)
 return [value]
 return []

The file containing this implementation can be imported via command script import and then we can register this recognizer with frame recognizer add.

It’s important to restrict the recognizer to the libc library (which is libsystem_kernel.dylib on macOS) to avoid matching functions with the same name in other modules:

(lldb)commandscriptimport.../fd_recognizer.py
(lldb)framerecognizeradd-lfd_recognizer.LibcFdRecognizer-nread-slibsystem_kernel.dylib

When the program is stopped at the beginning of the ‘read’ function in libc, we can view the recognizer arguments in ‘frame variable’:

(lldb)bread
(lldb)r
Process1234stopped
*thread#1,queue='com.apple.main-thread',stopreason=breakpoint1.3
frame#0:0x00007fff06013ca0libsystem_kernel.dylib`read
(lldb)framevariable
(int)fd=3