Stack Frame and Thread Format

LLDB has a facility to allow users to define the format of the information that generates the descriptions for threads and stack frames. Typically when your program stops at a breakpoint you will get two lines that describes why your thread stopped and where:

* thread #1, queue = 'com.apple.main-thread', stop reason = breakpoint 1.1 frame #0: test`main at test.c:5



        		   Stack backtraces frames also have a similar information line:

                   (lldb) thread backtrace
                   
* thread #1, queue = 'com.apple.main-thread', stop reason = breakpoint 1.1
                   
  frame #0: 0x0000000100000e85 a.out`main + 4 at test.c:19
                   
  frame #1: 0x0000000100000e40 a.out`start + 52
                   

				   The two format strings that govern the printing in these output forms can currently be set using the settings set command:
				   (lldb) settings set thread-stop-format STRING
				   
(lldb) settings set frame-format STRING
				   

                        The first of these is an abbreviated thread output, that just contains data about
                          the thread, and not the stop frame.  It will always get used in situations where the
                          frame output follows immediately, so that information would be redundant.  The second
                          is the frame printing.
                       
                       
                         There is another thread format used for commands like thread list where
                         the thread information isn't followed by frame info.  In that case, it is convenient to have
                         frame zero information in the thread output.  That format is set by:
                       
				   (lldb) settings set thread-format STRING



   			
   				Format Strings
   				

                   So what is the format of the format strings? Format strings can
                   contain plain text, control characters and variables that have access
                   to the current program state.
                   
                   Normal characters are any text that doesn't contain a '{', '}', '$',
                       or '\' character.
                
                   Variable names are found in between a "${" prefix, and
                   end with a "}" suffix. In other words, a variable looks like
                   "${frame.pc}". 
                   
                
          		
      			

      			
      				Variables
      				

                   A complete list of currently supported format string variables is listed below:

                   
                    Variable Name Description
                    file.basename The current compile unit file basename for the current frame.
                    file.fullpath The current compile unit file fullpath for the current frame.
                    language The current compile unit language for the current frame.
                    frame.index The frame index (0, 1, 2, 3...)
                    frame.no-debug Evaluates to true if the frame has no debug info.
                    frame.pc The generic frame register for the program counter.
                    frame.sp The generic frame register for the stack pointer.
                    frame.fp The generic frame register for the frame pointer.
                    frame.flags The generic frame register for the flags register.
                    frame.reg.NAME Access to any platform specific register by name (replace NAME with the name of the desired register).
                    function.name The name of the current function or symbol.
                    function.name-with-args The name of the current function with arguments and values or the symbol name.
                    function.name-without-args The name of the current function without arguments and values (used to include a function name in-line in the disassembly-format)
                    function.pc-offset The program counter offset within the current function or symbol
                    function.addr-offset The offset in bytes of the current function, formatted as " + dddd"
                    function.concrete-only-addr-offset-no-padding Similar to function.addr-offset except that there are no spaces in the output (e.g. "+dddd") and the offset is computed from the nearest concrete function -- inlined functions are not included
                    function.changed Will evaluate to true when the line being formatted is a different symbol context from the previous line (may be used in disassembly-format to print the new function name on a line by itself at the start of a new function).  Inlined functions are not considered for this variable
                    function.initial-function Will evaluate to true if this is the start of the first function, as opposed to a change of functions (may be used in disassembly-format to print the function name for the first function being disassembled)
                    line.file.basename The line table entry basename to the file for the current line entry in the current frame.
                    line.file.fullpath The line table entry fullpath to the file for the current line entry in the current frame.
                    line.number The line table entry line number for the current line entry in the current frame.
                    line.start-addr The line table entry start address for the current line entry in the current frame.
                    line.end-addr The line table entry end address for the current line entry in the current frame.
                    module.file.basename The basename of the current module (shared library or executable)
                    module.file.fullpath The basename of the current module (shared library or executable)
                    process.file.basename The basename of the file for the process
                    process.file.fullpath The fullname of the file for the process
                    process.id The process ID native to the system on which the inferior runs.
                    process.name The name of the process at runtime
                    thread.id The thread identifier for the current thread
                    thread.index The unique one based thread index ID which is guaranteed to be unique as threads come and go.
                    thread.name The name of the thread if the target OS supports naming threads
                    thread.queue The queue name of the thread if the target OS supports dispatch queues
                    thread.stop-reason A textual reason each thread stopped
                    thread.return-value The return value of the latest step operation (currently only for step-out.)
                    thread.completed-expression The expression result for a thread that just finished an interrupted expression evaluation.
                    target.arch The architecture of the current target
                    script.target:python_func Use a Python function to generate a piece of textual output
                    script.process:python_func Use a Python function to generate a piece of textual output
                    script.thread:python_func Use a Python function to generate a piece of textual output
                    script.frame:python_func Use a Python function to generate a piece of textual output
                    current-pc-arrow Prints either '-> ' or '   ' if the current pc value is matched (used in disassembly-format)
                    addr-file-or-load Formats an address either as a load address, or if process has not yet been launched, as a load address (used in disassembly-format)
                    
                    
                       
           			
       			

       			
       				Control Characters
       				

                    Control characters include '{',
                    '}', and '\'.

                    The '{' and '}' are used for scoping blocks, and the '\' character
                        allows you to desensitize control characters and also emit non-printable
                        characters.
    
                           
               			
           			

           			
           				Desensitizing Characters in the format string
           				
                    The backslash control character allows your to enter the typical
                    "\a", "\b", "\f", "\n", 
                        "\r", "\t", "\v", "\\", characters 
                    and along with the standard octal representation "\0123"
                    and hex "\xAB" characters. This allows you to enter 
                    escape characters into your format strings and will
                    allow colorized output for terminals that support color.

                       
           			
       			

       			
       				Scoping
       				
                   Many times the information that you might have in your prompt might not be
                   available and you won't want it to print out if it isn't valid. To take care
                   of this you can enclose everything that must resolve into a scope. A scope
                   is starts with '{' and ends with 
                   '}'. For example in order to only display
                   the current frame line table entry basename and line number when the information
                   is available for the current frame:

                   
"{ at {$line.file.basename}:${line.number}}"

                   Broken down this is:
                       

                        The start the scope "{"
                         format whose content will only be displayed if all information is available:
                           "at {$line.file.basename}:${line.number}"
                        end the scope: "}"
                        

                    
               	    
           		

           		
           			Making the Frame Format
           			
                   The information that we see when stopped in a frame:

                   
frame #0: 0x0000000100000e85 a.out`main + 4 at test.c:19

                   can be displayed with the following format:

                   "frame #${frame.index}: ${frame.pc}{ ${module.file.basename}`${function.name}{${function.pc-offset}}}{ at ${line.file.basename}:${line.number}}\n"

                   This breaks down to:
                       
                    

                        Always print the frame index and frame PC:

                            "frame #${frame.index}: ${frame.pc}"

                   
only print the module followed by a tick if there is a valid
                   module for the current frame:

                   "{ ${module.file.basename}`}"

                   
print the function name with optional offset:
                       "{${function.name}{${function.pc-offset}}}"

                   
print the line info if it is available:

                       "{ at ${line.file.basename}:${line.number}}"

                   
then finish off with a newline:

                    "\n"
                    

                    
               	    
           		

           		
           			Making Your Own Formats
           			

                   When modifying your own format strings, it is useful
                       to start with the default values for the frame and
                       thread format strings. These can be accessed with the
                       "settings show" command:
                       
                   
(lldb) settings show thread-format 
                   
thread-format (format-string) = "thread #${thread.index}: tid = ${thread.id%tid}{, ${frame.pc}}{ ${module.file.basename}{`${function.name-with-args}{${frame.no-debug}${function.pc-offset}}}}{ at ${line.file.basename}:${line.number}}{, name = '${thread.name}'}{, queue = '${thread.queue}'}{, activity = '${thread.info.activity.name}'}{, ${thread.info.trace_messages} messages}{, stop reason = ${thread.stop-reason}}{\nReturn value: ${thread.return-value}}{\nCompleted expression: ${thread.completed-expression}}\n"
                   
(lldb) settings show frame-format 
                   
frame-format (format-string) = "frame #${frame.index}:{ ${frame.no-debug}${frame.pc}}{ ${module.file.basename}{`${function.name-with-args}{${frame.no-debug}${function.pc-offset}}}}{ at ${line.file.basename}:${line.number}}{${function.is-optimized} [opt]}\n"
                   


                   When making thread formats, you will need surround any
                       of the information that comes from a stack frame with scopes ({ frame-content })
                       as the thread format doesn't always want to show frame information.
                       When displaying the backtrace for a thread, we don't need to duplicate
                       the information for frame zero in the thread information:

                   
(lldb) thread backtrace 
                   
thread #1: tid = 0x2e03, stop reason = breakpoint 1.1 2.1
                   
  frame #0: 0x0000000100000e85 a.out`main + 4 at test.c:19
                   
  frame #1: 0x0000000100000e40 a.out`start + 52
                   
                   
                       
                   The frame related variables are:
                      

                      ${file.*}
                      ${frame.*}
                      ${function.*}
                      ${line.*}
                      ${module.*}
                      
                    
                     
                    Looking at the default format for the thread, and underlining
                        the frame information:
                    
'thread #${thread.index}: tid = ${thread.id}{, ${frame.pc}}{ ${module.file.basename}`${function.name}{${function.pc-offset}}}{, stop reason = ${thread.stop-reason}}{, name = ${thread.name}}{, queue = ${thread.queue}}\n'
                    
                    We can see that all frame information is contained in scopes so 
                        that when the thread information is displayed in a context where
                        we only want to show thread information, we can do so.
                        
					
For both thread and frame formats, you can use ${script.target:python_func}, ${script.process:python_func} and ${script.thread:python_func}
						(and of course ${script.frame:python_func} for frame formats)

						In all cases, the signature of python_func is expected to be:

							

								def python_func(object,unused):

								    ...

								    return string

						
Where object is an instance of the SB class associated to the keyword you are using.
							
						
e.g. Assuming your function looks like

						def thread_printer_func (thread,unused):

						  return "Thread %s has %d frames\n" % (thread.name, thread.num_frames)

							
						And you set it up with 
(lldb) settings set thread-format "${script.thread:thread_printer_func}"

						you would see output like:
						
						* Thread main has 21 frames

Variable Name	Description
file.basename	The current compile unit file basename for the current frame.
file.fullpath	The current compile unit file fullpath for the current frame.
language	The current compile unit language for the current frame.
frame.index	The frame index (0, 1, 2, 3...)
frame.no-debug	Evaluates to true if the frame has no debug info.
frame.pc	The generic frame register for the program counter.
frame.sp	The generic frame register for the stack pointer.
frame.fp	The generic frame register for the frame pointer.
frame.flags	The generic frame register for the flags register.
frame.reg.NAME	Access to any platform specific register by name (replace NAME with the name of the desired register).
function.name	The name of the current function or symbol.
function.name-with-args	The name of the current function with arguments and values or the symbol name.
function.name-without-args	The name of the current function without arguments and values (used to include a function name in-line in the `disassembly-format`)
function.pc-offset	The program counter offset within the current function or symbol
function.addr-offset	The offset in bytes of the current function, formatted as " + dddd"
function.concrete-only-addr-offset-no-padding	Similar to function.addr-offset except that there are no spaces in the output (e.g. "+dddd") and the offset is computed from the nearest concrete function -- inlined functions are not included
function.changed	Will evaluate to true when the line being formatted is a different symbol context from the previous line (may be used in `disassembly-format` to print the new function name on a line by itself at the start of a new function). Inlined functions are not considered for this variable
function.initial-function	Will evaluate to true if this is the start of the first function, as opposed to a change of functions (may be used in `disassembly-format` to print the function name for the first function being disassembled)
line.file.basename	The line table entry basename to the file for the current line entry in the current frame.
line.file.fullpath	The line table entry fullpath to the file for the current line entry in the current frame.
line.number	The line table entry line number for the current line entry in the current frame.
line.start-addr	The line table entry start address for the current line entry in the current frame.
line.end-addr	The line table entry end address for the current line entry in the current frame.
module.file.basename	The basename of the current module (shared library or executable)
module.file.fullpath	The basename of the current module (shared library or executable)
process.file.basename	The basename of the file for the process
process.file.fullpath	The fullname of the file for the process
process.id	The process ID native to the system on which the inferior runs.
process.name	The name of the process at runtime
thread.id	The thread identifier for the current thread
thread.index	The unique one based thread index ID which is guaranteed to be unique as threads come and go.
thread.name	The name of the thread if the target OS supports naming threads
thread.queue	The queue name of the thread if the target OS supports dispatch queues
thread.stop-reason	A textual reason each thread stopped
thread.return-value	The return value of the latest step operation (currently only for step-out.)
thread.completed-expression	The expression result for a thread that just finished an interrupted expression evaluation.
target.arch	The architecture of the current target
script.target:python_func	Use a Python function to generate a piece of textual output
script.process:python_func	Use a Python function to generate a piece of textual output
script.thread:python_func	Use a Python function to generate a piece of textual output
script.frame:python_func	Use a Python function to generate a piece of textual output
current-pc-arrow	Prints either '`->` ' or ' ' if the current pc value is matched (used in `disassembly-format`)
addr-file-or-load	Formats an address either as a load address, or if process has not yet been launched, as a load address (used in `disassembly-format`)