1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 2 <html xmlns="http://www.w3.org/1999/xhtml"> 3 <head> 4 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /> 5 <link href="style.css" rel="stylesheet" type="text/css" /> 6 <title>LLDB Stack and Frame Formats</title> 7 </head> 8 9 <body> 10 <div class="www_title"> 11 The <strong>LLDB</strong> Debugger 12 </div> 13 14 <div id="container"> 15 <div id="content"> 16 <!--#include virtual="sidebar.incl"--> 17 18 <div id="middle"> 19 <div class="post"> 20 <h1 class ="postheader">Stack Frame and Thread Format</h1> 21 <div class="postcontent"> 22 <p>LLDB has a facility to allow users to define the 23 format of the information that generates the descriptions 24 for threads and stack frames. Typically when your program stops 25 at a breakpoint you will get a line that describes why 26 your thread stopped:</p> 27 28 <p><b><code>* thread #1: tid = 0x2e03, 0x0000000100000e85 a.out`main + 4, stop reason = breakpoint 1.1</code></b></p> 29 30 <p>Stack backtraces frames also have a similar information line:</p> 31 32 <p><code><b>(lldb)</b> thread backtrace 33 <br><b>thread #1: tid = 0x2e03, stop reason = breakpoint 1.1 34 <br> frame #0: 0x0000000100000e85 a.out`main + 4 at test.c:19 35 <br> frame #1: 0x0000000100000e40 a.out`start + 52 36 </code></b></p> 37 38 <p>The two format strings can currently be set using the <b>settings set</b> command:</p> 39 <p><code><b>(lldb)</b> settings set frame-format STRING 40 <br><b>(lldb)</b> settings set thread-format STRING 41 </p></code> 42 43 </div> 44 <div class="postfooter"></div> 45 </div> 46 47 <div class="post"> 48 <h1 class ="postheader">Format Strings</h1> 49 <div class="postcontent"> 50 51 <p>So what is the format of the format strings? Format strings can 52 contain plain text, control characters and variables that have access 53 to the current program state.</p> 54 55 <p>Normal characters are any text that doesn't contain a <code><b>'{'</b></code>, <code><b>'}'</b></code>, <code><b>'$'</b></code>, 56 or <code><b>'\'</b></code> character.</p> 57 58 <p>Variable names are found in between a <code><b>"${"</b></code> prefix, and 59 end with a <code><b>"}"</b></code> suffix. In other words, a variable looks like 60 <code>"<b>${frame.pc}</b>"</code>.</p> 61 62 </div> 63 <div class="postfooter"></div> 64 </div> 65 66 <div class="post"> 67 <h1 class ="postheader">Variables</h1> 68 <div class="postcontent"> 69 70 <p>A complete list of currently supported format string variables is listed below:</p> 71 72 <table border="1"> 73 <tr valign=top><td><b>Variable Name</b></td><td><b>Description</b></td></tr> 74 <tr valign=top><td><b>file.basename</b></td><td>The current compile unit file basename for the current frame.</td></tr> 75 <tr valign=top><td><b>file.fullpath</b></td><td>The current compile unit file fullpath for the current frame.</td></tr> 76 <tr valign=top><td><b>frame.index</b></td><td>The frame index (0, 1, 2, 3...)</td></tr> 77 <tr valign=top><td><b>frame.pc</b></td><td>The generic frame register for the program counter.</td></tr> 78 <tr valign=top><td><b>frame.sp</b></td><td>The generic frame register for the stack pointer.</td></tr> 79 <tr valign=top><td><b>frame.fp</b></td><td>The generic frame register for the frame pointer.</td></tr> 80 <tr valign=top><td><b>frame.flags</b></td><td>The generic frame register for the flags register.</td></tr> 81 <tr valign=top><td><b>frame.reg.NAME</b></td><td>Access to any platform specific register by name (replace <b>NAME</b> with the name of the desired register).</td></tr> 82 <tr valign=top><td><b>function.name</b></td><td>The name of the current function or symbol.</td></tr> 83 <tr valign=top><td><b>function.name-with-args</b></td><td>The name of the current function with arguments and values or the symbol name.</td></tr> 84 <tr valign=top><td><b>function.pc-offset</b></td><td>The program counter offset within the current function or symbol</td></tr> 85 <tr valign=top><td><b>line.file.basename</b></td><td>The line table entry basename to the file for the current line entry in the current frame.</td></tr> 86 <tr valign=top><td><b>line.file.fullpath</b></td><td>The line table entry fullpath to the file for the current line entry in the current frame.</td></tr> 87 <tr valign=top><td><b>line.number</b></td><td>The line table entry line number for the current line entry in the current frame.</td></tr> 88 <tr valign=top><td><b>line.start-addr</b></td><td>The line table entry start address for the current line entry in the current frame.</td></tr> 89 <tr valign=top><td><b>line.end-addr</b></td><td>The line table entry end address for the current line entry in the current frame.</td></tr> 90 <tr valign=top><td><b>module.file.basename</b></td><td>The basename of the current module (shared library or executable)</td></tr> 91 <tr valign=top><td><b>module.file.fullpath</b></td><td>The basename of the current module (shared library or executable)</td></tr> 92 <tr valign=top><td><b>process.file.basename</b></td><td>The basename of the file for the process</td></tr> 93 <tr valign=top><td><b>process.file.fullpath</b></td><td>The fullname of the file for the process</td></tr> 94 <tr valign=top><td><b>process.id</b></td><td>The process ID native the the system on which the inferior runs.</td></tr> 95 <tr valign=top><td><b>process.name</b></td><td>The name of the process at runtime</td></tr> 96 <tr valign=top><td><b>thread.id</b></td><td>The thread identifier for the current thread</td></tr> 97 <tr valign=top><td><b>thread.index</b></td><td>The unique one based thread index ID which is guaranteed to be unique as threads come and go.</td></tr> 98 <tr valign=top><td><b>thread.name</b></td><td>The name of the thread if the target OS supports naming threads</td></tr> 99 <tr valign=top><td><b>thread.queue</b></td><td>The queue name of the thread if the target OS supports dispatch queues</td></tr> 100 <tr valign=top><td><b>thread.stop-reason</b></td><td>A textual reason each thread stopped</td></tr> 101 <tr valign=top><td><b>thread.return-value</b></td><td>The return value of the latest step operation (currently only for step-out.)</td></tr> 102 <tr valign=top><td><b>target.arch</b></td><td>The architecture of the current target</td></tr> 103 <tr valign=top><td><b>target.script:<i>python_func</i></b></td><td>Use a Python function to generate a piece of textual output</td></tr> 104 <tr valign=top><td><b>process.script:<i>python_func</i></b></td><td>Use a Python function to generate a piece of textual output</td></tr> 105 <tr valign=top><td><b>thread.script:<i>python_func</i></b></td><td>Use a Python function to generate a piece of textual output</td></tr> 106 <tr valign=top><td><b>frame.script:<i>python_func</i></b></td><td>Use a Python function to generate a piece of textual output</td></tr> 107 </table> 108 109 </div> 110 <div class="postfooter"></div> 111 </div> 112 113 <div class="post"> 114 <h1 class ="postheader">Control Characters</h1> 115 <div class="postcontent"> 116 117 <p>Control characters include <b><code>'{'</code></b>, 118 <b><code>'}'</code></b>, and <b><code>'\'</code></b>.</p> 119 120 <p>The '{' and '}' are used for scoping blocks, and the '\' character 121 allows you to desensitize control characters and also emit non-printable 122 characters. 123 124 </div> 125 <div class="postfooter"></div> 126 </div> 127 128 <div class="post"> 129 <h1 class ="postheader">Desensitizing Characters in the format string</h1> 130 <div class="postcontent"> 131 <p>The backslash control character allows your to enter the typical 132 <b><code>"\a"</code></b>, <b><code>"\b"</code></b>, <b><code>"\f"</code></b>, <b><code>"\n"</code></b>, 133 <b><code>"\r"</code></b>, <b><code>"\t"</code></b>, <b><code>"\v"</code></b>, <b><code>"\\"</code></b>, characters 134 and along with the standard octal representation <b><code>"\0123"</code></b> 135 and hex <b><code>"\xAB"</code></b> characters. This allows you to enter 136 escape characters into your format strings and will 137 allow colorized output for terminals that support color. 138 139 </div> 140 <div class="postfooter"></div> 141 </div> 142 143 <div class="post"> 144 <h1 class ="postheader">Scoping</h1> 145 <div class="postcontent"> 146 <p>Many times the information that you might have in your prompt might not be 147 available and you won't want it to print out if it isn't valid. To take care 148 of this you can enclose everything that <b>must</b> resolve into a scope. A scope 149 is starts with <code><b>'{'</code></b> and ends with 150 <code><b>'}'</code></b>. For example in order to only display 151 the current frame line table entry basename and line number when the information 152 is available for the current frame: 153 154 <p><b><code>"{ at {$line.file.basename}:${line.number}}"</code></b></p> 155 156 <p>Broken down this is: 157 <ul> 158 <li>The start the scope <p><b><code>"{"</code></b></p></li> 159 <li> format whose content will only be displayed if all information is available: 160 <p><b><code>"at {$line.file.basename}:${line.number}"</code></b></p></li> 161 <li>end the scope: <p><b><code>"}"</code></b></p></li> 162 </ul> 163 164 </div> 165 <div class="postfooter"></div> 166 </div> 167 168 <div class="post"> 169 <h1 class ="postheader">Making the Frame Format</h1> 170 <div class="postcontent"> 171 <p>The information that we see when stopped in a frame: 172 173 <p><b><code>frame #0: 0x0000000100000e85 a.out`main + 4 at test.c:19</code></b></p> 174 175 <p>can be displayed with the following format:</p> 176 177 <p><b><code>"frame #${frame.index}: ${frame.pc}{ ${module.file.basename}`${function.name}{${function.pc-offset}}}{ at ${line.file.basename}:${line.number}}\n"</code></b></p> 178 179 <p>This breaks down to: 180 181 <ul> 182 <li>Always print the frame index and frame PC: 183 184 <p><b><code>"frame #${frame.index}: ${frame.pc}"</code></b></p> 185 186 <li>only print the module followed by a tick if there is a valid 187 module for the current frame: 188 189 <p><b><code>"{ ${module.file.basename}`}"</code></b></p> 190 191 <li>print the function name with optional offset:</p> 192 <p><b><code>"{${function.name}{${function.pc-offset}}}"</code></b></p> 193 194 <li>print the line info if it is available:</p> 195 196 <p><b><code>"{ at ${line.file.basename}:${line.number}}"</code></b></p> 197 198 <li>then finish off with a newline:</p> 199 200 <p><b><code>"\n"</code></b></p> 201 </ul> 202 203 </div> 204 <div class="postfooter"></div> 205 </div> 206 207 <div class="post"> 208 <h1 class ="postheader">Making Your Own Formats</h1> 209 <div class="postcontent"> 210 211 <p>When modifying your own format strings, it is useful 212 to start with the default values for the frame and 213 thread format strings. These can be accessed with the 214 <b><code>"settings show"</code></b> command: 215 216 <p><b><code>(lldb)</b> settings show thread-format 217 <br>thread-format (string) = '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' 218 <br><b>(lldb)</b> settings show frame-format 219 <br>frame-format (string) = 'frame #${frame.index}: ${frame.pc}{ ${module.file.basename}`${function.name}{${function.pc-offset}}}{ at ${line.file.basename}:${line.number}}\n' 220 </code></p> 221 222 223 <p>When making thread formats, you will need surround any 224 of the information that comes from a stack frame with scopes (<b>{</b> <i>frame-content</i> <b>}</b>) 225 as the thread format doesn't always want to show frame information. 226 When displaying the backtrace for a thread, we don't need to duplicate 227 the information for frame zero in the thread information: 228 229 <p><code><b>(lldb)</b> thread backtrace 230 <br>thread #1: tid = 0x2e03, stop reason = breakpoint 1.1 2.1 231 <br> frame #0: 0x0000000100000e85 a.out`main + 4 at test.c:19 232 <br> frame #1: 0x0000000100000e40 a.out`start + 52 233 </code> 234 </p> 235 236 <p>The frame related variables are: 237 <ul> 238 <li><code><b>${file.*}</b></code></li> 239 <li><code><b>${frame.*}</b></code></li> 240 <li><code><b>${function.*}</b></code></li> 241 <li><code><b>${line.*}</b></code></li> 242 <li><code><b>${module.*}</b></code></li> 243 </ul> 244 </p> 245 246 <p>Looking at the default format for the thread, and underlining 247 the frame information: 248 <p><code>'thread #${thread.index}: tid = ${thread.id}<u><b>{</b>, ${frame.pc}<b>}{</b> ${module.file.basename}`${function.name}{${function.pc-offset}}<b>}</b></u>{, stop reason = ${thread.stop-reason}}{, name = ${thread.name}}{, queue = ${thread.queue}}\n' 249 </code></p> 250 <p>We can see that all frame information is contained in scopes so 251 that when the thread information is displayed in a context where 252 we only want to show thread information, we can do so. 253 254 <p>For both thread and frame formats, you can use ${target.script:<i>python_func</i>}, ${process.script:<i>python_func</i>} and ${thread.script:<i>python_func</i>} 255 (and of course ${frame.script:<i>python_func</i>} for frame formats)<br/> 256 In all cases, the signature of <i>python_func</i> is expected to be:<br/> 257 <p><code> 258 def <i>python_func</i>(<i>object</i>,unused):<br/> 259 ...<br/> 260 return <i>string</i><br/></code> 261 <p>Where <i>object</i> is an instance of the SB class associated to the keyword you are using. 262 263 <p>e.g. Assuming your function looks like<br/><code><p> 264 def thread_printer_func (thread,unused):<br/> 265 return "Thread %s has %d frames\n" % (thread.name, thread.num_frames)<br/></code><p> 266 267 And you set it up with <code><br/><b>(lldb)</b> settings set thread-format "${thread.script:thread_printer_func}"<br/></code> 268 you would see output like: 269 </p> 270 <code>* Thread main has 21 frames</code> 271 </div> 272 <div class="postfooter"></div> 273 </div> 274 275 </div> 276 </div> 277 </div> 278 </body> 279 </html> 280
