www/formats.html

   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>&nbsp;&nbsp;frame #0: 0x0000000100000e85 a.out`main + 4 at test.c:19
  35                    <br>&nbsp;&nbsp;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>language</b></td><td>The current compile unit language for the current frame.</td></tr>
  77                     <tr valign=top><td><b>frame.index</b></td><td>The frame index (0, 1, 2, 3...)</td></tr>
  78                     <tr valign=top><td><b>frame.pc</b></td><td>The generic frame register for the program counter.</td></tr>
  79                     <tr valign=top><td><b>frame.sp</b></td><td>The generic frame register for the stack pointer.</td></tr>
  80                     <tr valign=top><td><b>frame.fp</b></td><td>The generic frame register for the frame pointer.</td></tr>
  81                     <tr valign=top><td><b>frame.flags</b></td><td>The generic frame register for the flags register.</td></tr>
  82                     <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>
  83                     <tr valign=top><td><b>function.name</b></td><td>The name of the current function or symbol.</td></tr>
  84                     <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>
  85                     <tr valign=top><td><b>function.name-without-args</b></td><td>The name of the current function without arguments and values (used to include a function name in-line in the <tt>disassembly-format</tt>)</td></tr>
  86                     <tr valign=top><td><b>function.pc-offset</b></td><td>The program counter offset within the current function or symbol</td></tr>
  87                     <tr valign=top><td><b>function.addr-offset</b></td><td>The offset in bytes of the current function, formatted as " + dddd"</td></tr>
  88                     <tr valign=top><td><b>function.concrete-only-addr-offset-no-padding</b></td><td>Similar to <b>function.addr-offset</b> 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</td></tr>
  89                     <tr valign=top><td><b>function.changed</b></td><td>Will evaluate to true when the line being formatted is a different symbol context from the previous line (may be used in <tt>disassembly-format</tt> 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</td></tr>
  90                     <tr valign=top><td><b>function.initial-function</b></td><td>Will evaluate to true if this is the start of the first function, as opposed to a change of functions (may be used in <tt>disassembly-format</tt> to print the function name for the first function being disassembled)</td></tr>
  91                     <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>
  92                     <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>
  93                     <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>
  94                     <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>
  95                     <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>
  96                     <tr valign=top><td><b>module.file.basename</b></td><td>The basename of the current module (shared library or executable)</td></tr>
  97                     <tr valign=top><td><b>module.file.fullpath</b></td><td>The basename of the current module (shared library or executable)</td></tr>
  98                     <tr valign=top><td><b>process.file.basename</b></td><td>The basename of the file for the process</td></tr>
  99                     <tr valign=top><td><b>process.file.fullpath</b></td><td>The fullname of the file for the process</td></tr>
 100                     <tr valign=top><td><b>process.id</b></td><td>The process ID native to the system on which the inferior runs.</td></tr>
 101                     <tr valign=top><td><b>process.name</b></td><td>The name of the process at runtime</td></tr>
 102                     <tr valign=top><td><b>thread.id</b></td><td>The thread identifier for the current thread</td></tr>
 103                     <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>
 104                     <tr valign=top><td><b>thread.name</b></td><td>The name of the thread if the target OS supports naming threads</td></tr>
 105                     <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>
 106                     <tr valign=top><td><b>thread.stop-reason</b></td><td>A textual reason each thread stopped</td></tr>
 107                     <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>
 108                     <tr valign=top><td><b>thread.completed-expression</b></td><td>The expression result for a thread that just finished an interrupted expression evaluation.</td></tr>
 109                     <tr valign=top><td><b>target.arch</b></td><td>The architecture of the current target</td></tr>
 110                     <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>
 111                     <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>
 112                     <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>
 113                     <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>
 114                     <tr valign=top><td><b>current-pc-arrow</b></td><td>Prints either '<tt>-> </tt>' or '<tt>   </tt>' if the current pc value is matched (used in <tt>disassembly-format</tt>)</td></tr>
 115                     <tr valign=top><td><b>addr-file-or-load</b></td><td>Formats an address either as a load address, or if process has not yet been launched, as a load address (used in <tt>disassembly-format</tt>)</td></tr>
 116                     </table>
 117
 118                        </div>
 119                                 <div class="postfooter"></div>
 120                         </div>
 121
 122                         <div class="post">
 123                                 <h1 class ="postheader">Control Characters</h1>
 124                                 <div class="postcontent">
 125
 126                     <p>Control characters include <b><code>'{'</code></b>,
 127                     <b><code>'}'</code></b>, and <b><code>'\'</code></b>.</p>
 128
 129                     <p>The '{' and '}' are used for scoping blocks, and the '\' character
 130                         allows you to desensitize control characters and also emit non-printable
 131                         characters.
 132
 133                            </div>
 134                                 <div class="postfooter"></div>
 135                                 </div>
 136
 137                                 <div class="post">
 138                                         <h1 class ="postheader">Desensitizing Characters in the format string</h1>
 139                                         <div class="postcontent">
 140                     <p>The backslash control character allows your to enter the typical
 141                     <b><code>"\a"</code></b>, <b><code>"\b"</code></b>, <b><code>"\f"</code></b>, <b><code>"\n"</code></b>,
 142                         <b><code>"\r"</code></b>, <b><code>"\t"</code></b>, <b><code>"\v"</code></b>, <b><code>"\\"</code></b>, characters
 143                     and along with the standard octal representation <b><code>"\0123"</code></b>
 144                     and hex <b><code>"\xAB"</code></b> characters. This allows you to enter
 145                     escape characters into your format strings and will
 146                     allow colorized output for terminals that support color.
 147
 148                        </div>
 149                                 <div class="postfooter"></div>
 150                         </div>
 151
 152                         <div class="post">
 153                                 <h1 class ="postheader">Scoping</h1>
 154                                 <div class="postcontent">
 155                    <p>Many times the information that you might have in your prompt might not be
 156                    available and you won't want it to print out if it isn't valid. To take care
 157                    of this you can enclose everything that <b>must</b> resolve into a scope. A scope
 158                    is starts with <code><b>'{'</code></b> and ends with
 159                    <code><b>'}'</code></b>. For example in order to only display
 160                    the current frame line table entry basename and line number when the information
 161                    is available for the current frame:
 162
 163                    <p><b><code>"{ at {$line.file.basename}:${line.number}}"</code></b></p>
 164
 165                    <p>Broken down this is:
 166                        <ul>
 167                         <li>The start the scope <p><b><code>"{"</code></b></p></li>
 168                         <li> format whose content will only be displayed if all information is available:
 169                            <p><b><code>"at {$line.file.basename}:${line.number}"</code></b></p></li>
 170                         <li>end the scope: <p><b><code>"}"</code></b></p></li>
 171                         </ul>
 172
 173                     </div>
 174                     <div class="postfooter"></div>
 175                         </div>
 176
 177                         <div class="post">
 178                                 <h1 class ="postheader">Making the Frame Format</h1>
 179                                 <div class="postcontent">
 180                    <p>The information that we see when stopped in a frame:
 181
 182                    <p><b><code>frame #0: 0x0000000100000e85 a.out`main + 4 at test.c:19</code></b></p>
 183
 184                    <p>can be displayed with the following format:</p>
 185
 186                    <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>
 187
 188                    <p>This breaks down to:
 189
 190                     <ul>
 191                         <li>Always print the frame index and frame PC:
 192
 193                             <p><b><code>"frame #${frame.index}: ${frame.pc}"</code></b></p>
 194
 195                    <li>only print the module followed by a tick if there is a valid
 196                    module for the current frame:
 197
 198                    <p><b><code>"{ ${module.file.basename}`}"</code></b></p>
 199
 200                    <li>print the function name with optional offset:</p>
 201                        <p><b><code>"{${function.name}{${function.pc-offset}}}"</code></b></p>
 202
 203                    <li>print the line info if it is available:</p>
 204
 205                        <p><b><code>"{ at ${line.file.basename}:${line.number}}"</code></b></p>
 206
 207                    <li>then finish off with a newline:</p>
 208
 209                     <p><b><code>"\n"</code></b></p>
 210                     </ul>
 211
 212                     </div>
 213                     <div class="postfooter"></div>
 214                         </div>
 215
 216                         <div class="post">
 217                                 <h1 class ="postheader">Making Your Own Formats</h1>
 218                                 <div class="postcontent">
 219
 220                    <p>When modifying your own format strings, it is useful
 221                        to start with the default values for the frame and
 222                        thread format strings. These can be accessed with the
 223                        <b><code>"settings show"</code></b> command:
 224
 225                    <p><b><code>(lldb)</b> settings show thread-format
 226                    <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'
 227                    <br><b>(lldb)</b> settings show frame-format
 228                    <br>frame-format (string) = 'frame #${frame.index}: ${frame.pc}{ ${module.file.basename}`${function.name}{${function.pc-offset}}}{ at ${line.file.basename}:${line.number}}\n'
 229                    </code></p>
 230
 231
 232                    <p>When making thread formats, you will need surround any
 233                        of the information that comes from a stack frame with scopes (<b>{</b> <i>frame-content</i> <b>}</b>)
 234                        as the thread format doesn't always want to show frame information.
 235                        When displaying the backtrace for a thread, we don't need to duplicate
 236                        the information for frame zero in the thread information:
 237
 238                    <p><code><b>(lldb)</b> thread backtrace
 239                    <br>thread #1: tid = 0x2e03, stop reason = breakpoint 1.1 2.1
 240                    <br>&nbsp;&nbsp;frame #0: 0x0000000100000e85 a.out`main + 4 at test.c:19
 241                    <br>&nbsp;&nbsp;frame #1: 0x0000000100000e40 a.out`start + 52
 242                    </code>
 243                    </p>
 244
 245                    <p>The frame related variables are:
 246                       <ul>
 247                       <li><code><b>${file.*}</b></code></li>
 248                       <li><code><b>${frame.*}</b></code></li>
 249                       <li><code><b>${function.*}</b></code></li>
 250                       <li><code><b>${line.*}</b></code></li>
 251                       <li><code><b>${module.*}</b></code></li>
 252                       </ul>
 253                     </p>
 254
 255                     <p>Looking at the default format for the thread, and underlining
 256                         the frame information:
 257                     <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'
 258                     </code></p>
 259                     <p>We can see that all frame information is contained in scopes so
 260                         that when the thread information is displayed in a context where
 261                         we only want to show thread information, we can do so.
 262
 263                                         <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>}
 264                                                 (and of course ${frame.script:<i>python_func</i>} for frame formats)<br/>
 265                                                 In all cases, the signature of <i>python_func</i> is expected to be:<br/>
 266                                                         <p><code>
 267                                                                 def <i>python_func</i>(<i>object</i>,unused):<br/>
 268                                                                 &nbsp;&nbsp;&nbsp;&nbsp;...<br/>
 269                                                                 &nbsp;&nbsp;&nbsp;&nbsp;return <i>string</i><br/></code>
 270                                                 <p>Where <i>object</i> is an instance of the SB class associated to the keyword you are using.
 271
 272                                                 <p>e.g. Assuming your function looks like<br/><code><p>
 273                                                 def thread_printer_func (thread,unused):<br/>
 274                                                 &nbsp;&nbsp;return "Thread %s has %d frames\n" % (thread.name, thread.num_frames)<br/></code><p>
 275
 276                                                 And you set it up with <code><br/><b>(lldb)</b> settings set thread-format "${thread.script:thread_printer_func}"<br/></code>
 277                                                 you would see output like:
 278                                                 </p>
 279                                                 <code>* Thread main has 21 frames</code>
 280                                 </div>
 281                                 <div class="postfooter"></div>
 282                     </div>
 283
 284                 </div>
 285         </div>
 286 </div>
 287 </body>
 288 </html>