1 <html devsite> 2 <head> 3 <title>Using GDB</title> 4 <meta name="project_path" value="/_project.yaml" /> 5 <meta name="book_path" value="/_book.yaml" /> 6 </head> 7 <body> 8 <!-- 9 Copyright 2017 The Android Open Source Project 10 11 Licensed under the Apache License, Version 2.0 (the "License"); 12 you may not use this file except in compliance with the License. 13 You may obtain a copy of the License at 14 15 http://www.apache.org/licenses/LICENSE-2.0 16 17 Unless required by applicable law or agreed to in writing, software 18 distributed under the License is distributed on an "AS IS" BASIS, 19 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 20 See the License for the specific language governing permissions and 21 limitations under the License. 22 --> 23 24 25 <p>The GNU Project debugger (GDB) is a commonly used Unix debugger. This page 26 details using <code>gdb</code> to debug Android apps and processes.</p> 27 28 <h2 id=running>Debugging running apps or processes</h2> 29 30 <p>To connect to an already-running app or native daemon, use 31 <code>gdbclient</code> with a PID. For example, to debug the process with PID 32 1234, run:</p> 33 34 <pre class="devsite-terminal devsite-click-to-copy"> 35 gdbclient 1234 36 </pre> 37 38 <p>The script sets up port forwarding, starts the appropriate 39 <code>gdbserver</code> on the device, starts the appropriate <code>gdb</code> on 40 the host, configures <code>gdb</code> to find symbols, and connects 41 <code>gdb</code> to the remote <code>gdbserver</code>.</p> 42 43 <h2 id=starts>Debugging native process startup</h2> 44 45 <p>To debug a process as it starts, use <code>gdbserver</code> or 46 <code>gdbserver64</code> (for 64-bit processes). For example:</p> 47 48 <pre class="devsite-terminal devsite-click-to-copy"> 49 adb shell gdbserver :5039 /system/bin/<var>MY_TEST_APP</var> 50 </pre> 51 52 <p>Example output:</p> 53 <pre class="devsite-click-to-copy"> 54 Process <var>MY_TEST_APP</var> created; pid = 3460 55 Listening on port 5039 56 </pre> 57 58 <p>Next, identify the application PID from the <code>gdbserver</code> output and 59 use it in another terminal window:</p> 60 61 <pre class="devsite-terminal devsite-click-to-copy"> 62 gdbclient <var>APP_PID</var> 63 </pre> 64 65 <p>Finally, enter <strong>continue</strong> at the <code>gdb</code> prompt.</p> 66 67 <p class="note"><strong>Note:</strong> If you specify the wrong 68 <code>gdbserver</code>, you'll get an unhelpful error message (such as 69 "<code>Reply contains invalid hex digit 59</code>").</p> 70 71 <h2 id="app-startup">Debugging app startup</h2> 72 73 <p>Sometimes you want to debug an app as it starts, such as when there's a crash 74 and you want to step through code to see what happens <em>before</em> the crash. 75 <a href="#running">Attaching</a> works in some cases, but in other cases is 76 impossible because the app crashes before you can attach. The 77 <code>logwrapper</code> approach (used for <code>strace</code> and 78 <code>valgrind</code>) does not always work because the app might not have 79 permissions to open a port, and <code>gdbserver</code> inherits that 80 restriction.</p> 81 82 <p>To debug app startup, use the developer options in Settings to instruct 83 the app to wait for a Java debugger to attach:</p> 84 85 <ol> 86 <li>Go to <em>Settings > Developer options > Select debug app</em> and choose 87 your app from the list, then press <strong>Wait for debugger</strong>.</li> 88 89 <li>Start the app, either from the launcher or by using the command line to run: 90 <pre class="devsite-terminal devsite-click-to-copy"> 91 am start -a android.intent.action.MAIN -n <var>APP_NAME</var>/.<var>APP_ACTIVITY</var> 92 </pre></li> 93 94 <li>Wait for the app to load and a dialog to appear telling you the app is 95 waiting for a debugger.</li> 96 97 <li>Attach <code>gdbserver</code>/<code>gdbclient</code> normally, set 98 breakpoints, then continue the process.</li></ol> 99 100 <p>To let the app actually run, attach a Java Debug Wire Protocol (JDWP) 101 debugger such as Java Debugger (jdb):</p> 102 <pre class="devsite-click-to-copy"> 103 <code class="devsite-terminal">adb forward tcp:12345 jdwp:<var>XXX</var> # (Where XXX is the pid of the debugged process.)</code> 104 <code class="devsite-terminal">jdb -attach localhost:12345</code> 105 </pre> 106 107 <h2 id=crash>Debugging apps or processes that crash</h2> 108 109 <p>If you want <code>debuggerd</code> to suspend crashed processes so you can 110 attach <code>gdb</code>, set the appropriate property:</p> 111 112 <pre class="devsite-click-to-copy"> 113 # Android 7.0 Nougat and later. 114 <code class="devsite-terminal">adb shell setprop debug.debuggerd.wait_for_gdb true</code> 115 </pre> 116 117 <pre class="devsite-click-to-copy"> 118 # Android 6.0 Marshmallow and earlier. 119 <code class="devsite-terminal">adb shell setprop debug.db.uid 999999</code> 120 </pre> 121 122 <p>At the end of the usual crash output, <code>debuggerd</code> provides 123 instructions on how to connect <code>gdb</code> using the command: 124 <pre class="devsite-terminal devsite-click-to-copy"> 125 gdbclient <var>PID</var> 126 </pre> 127 128 129 <h2 id=symbols>Debugging without symbols</h2> 130 131 <p>For 32-bit ARM, if you dont have symbols, <code>gdb</code> can get confused 132 about the instruction set it is disassembling (ARM or Thumb). To specify the 133 instruction set chosen as the default when symbol information is missing, set 134 the following property:</p> 135 136 <pre class="devsite-terminal devsite-click-to-copy"> 137 set arm fallback-mode arm # or thumb 138 </pre> 139 140 </body> 141 </html> 142
