1<html lang="en"> 2<head> 3<title>Bug Reporting - Debugging with GDB</title> 4<meta http-equiv="Content-Type" content="text/html"> 5<meta name="description" content="Debugging with GDB"> 6<meta name="generator" content="makeinfo 4.13"> 7<link title="Top" rel="start" href="index.html#Top"> 8<link rel="up" href="GDB-Bugs.html#GDB-Bugs" title="GDB Bugs"> 9<link rel="prev" href="Bug-Criteria.html#Bug-Criteria" title="Bug Criteria"> 10<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> 11<!-- 12Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 131998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 14Free Software Foundation, Inc. 15 16Permission is granted to copy, distribute and/or modify this document 17under the terms of the GNU Free Documentation License, Version 1.3 or 18any later version published by the Free Software Foundation; with the 19Invariant Sections being ``Free Software'' and ``Free Software Needs 20Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,'' 21and with the Back-Cover Texts as in (a) below. 22 23(a) The FSF's Back-Cover Text is: ``You are free to copy and modify 24this GNU Manual. Buying copies from GNU Press supports the FSF in 25developing GNU and promoting software freedom.''--> 26<meta http-equiv="Content-Style-Type" content="text/css"> 27<style type="text/css"><!-- 28 pre.display { font-family:inherit } 29 pre.format { font-family:inherit } 30 pre.smalldisplay { font-family:inherit; font-size:smaller } 31 pre.smallformat { font-family:inherit; font-size:smaller } 32 pre.smallexample { font-size:smaller } 33 pre.smalllisp { font-size:smaller } 34 span.sc { font-variant:small-caps } 35 span.roman { font-family:serif; font-weight:normal; } 36 span.sansserif { font-family:sans-serif; font-weight:normal; } 37--></style> 38<link rel="stylesheet" type="text/css" href="../cs.css"> 39</head> 40<body> 41<div class="node"> 42<a name="Bug-Reporting"></a> 43<p> 44Previous: <a rel="previous" accesskey="p" href="Bug-Criteria.html#Bug-Criteria">Bug Criteria</a>, 45Up: <a rel="up" accesskey="u" href="GDB-Bugs.html#GDB-Bugs">GDB Bugs</a> 46<hr> 47</div> 48 49<h3 class="section">30.2 How to Report Bugs</h3> 50 51<p><a name="index-bug-reports-2182"></a><a name="index-g_t_0040value_007bGDBN_007d-bugs_002c-reporting-2183"></a> 52A number of companies and individuals offer support for <span class="sc">gnu</span> products. 53If you obtained <span class="sc">gdb</span> from a support organization, we recommend you 54contact that organization first. 55 56 <p>You can find contact information for many support companies and 57individuals in the file <samp><span class="file">etc/SERVICE</span></samp> in the <span class="sc">gnu</span> Emacs 58distribution. 59<!-- should add a web page ref... --> 60 61 <p>In any event, we also recommend that you submit bug reports for 62<span class="sc">gdb</span> to <a href="https://support.codesourcery.com/GNUToolchain/">https://support.codesourcery.com/GNUToolchain/</a>. 63 64 <p>The fundamental principle of reporting bugs usefully is this: 65<strong>report all the facts</strong>. If you are not sure whether to state a 66fact or leave it out, state it! 67 68 <p>Often people omit facts because they think they know what causes the 69problem and assume that some details do not matter. Thus, you might 70assume that the name of the variable you use in an example does not matter. 71Well, probably it does not, but one cannot be sure. Perhaps the bug is a 72stray memory reference which happens to fetch from the location where that 73name is stored in memory; perhaps, if the name were different, the contents 74of that location would fool the debugger into doing the right thing despite 75the bug. Play it safe and give a specific, complete example. That is the 76easiest thing for you to do, and the most helpful. 77 78 <p>Keep in mind that the purpose of a bug report is to enable us to fix the 79bug. It may be that the bug has been reported previously, but neither 80you nor we can know that unless your bug report is complete and 81self-contained. 82 83 <p>Sometimes people give a few sketchy facts and ask, “Does this ring a 84bell?” Those bug reports are useless, and we urge everyone to 85<em>refuse to respond to them</em> except to chide the sender to report 86bugs properly. 87 88 <p>To enable us to fix the bug, you should include all these things: 89 90 <ul> 91<li>The version of <span class="sc">gdb</span>. <span class="sc">gdb</span> announces it if you start 92with no arguments; you can also print it at any time using <code>show 93version</code>. 94 95 <p>Without this, we will not know whether there is any point in looking for 96the bug in the current version of <span class="sc">gdb</span>. 97 98 <li>The type of machine you are using, and the operating system name and 99version number. 100 101 <li>What compiler (and its version) was used to compile <span class="sc">gdb</span>—e.g. 102“gcc–2.8.1”. 103 104 <li>What compiler (and its version) was used to compile the program you are 105debugging—e.g. “gcc–2.8.1”, or “HP92453-01 A.10.32.03 HP 106C Compiler”. For <span class="sc">gcc</span>, you can say <kbd>gcc --version</kbd> 107to get this information; for other compilers, see the documentation for 108those compilers. 109 110 <li>The command arguments you gave the compiler to compile your example and 111observe the bug. For example, did you use ‘<samp><span class="samp">-O</span></samp>’? To guarantee 112you will not omit something important, list them all. A copy of the 113Makefile (or the output from make) is sufficient. 114 115 <p>If we were to try to guess the arguments, we would probably guess wrong 116and then we might not encounter the bug. 117 118 <li>A complete input script, and all necessary source files, that will 119reproduce the bug. 120 121 <li>A description of what behavior you observe that you believe is 122incorrect. For example, “It gets a fatal signal.” 123 124 <p>Of course, if the bug is that <span class="sc">gdb</span> gets a fatal signal, then we 125will certainly notice it. But if the bug is incorrect output, we might 126not notice unless it is glaringly wrong. You might as well not give us 127a chance to make a mistake. 128 129 <p>Even if the problem you experience is a fatal signal, you should still 130say so explicitly. Suppose something strange is going on, such as, your 131copy of <span class="sc">gdb</span> is out of synch, or you have encountered a bug in 132the C library on your system. (This has happened!) Your copy might 133crash and ours would not. If you told us to expect a crash, then when 134ours fails to crash, we would know that the bug was not happening for 135us. If you had not told us to expect a crash, then we would not be able 136to draw any conclusion from our observations. 137 138 <p><a name="index-script-2184"></a><a name="index-recording-a-session-script-2185"></a>To collect all this information, you can use a session recording program 139such as <samp><span class="command">script</span></samp>, which is available on many Unix systems. 140Just run your <span class="sc">gdb</span> session inside <samp><span class="command">script</span></samp> and then 141include the <samp><span class="file">typescript</span></samp> file with your bug report. 142 143 <p>Another way to record a <span class="sc">gdb</span> session is to run <span class="sc">gdb</span> 144inside Emacs and then save the entire buffer to a file. 145 146 <li>If you wish to suggest changes to the <span class="sc">gdb</span> source, send us context 147diffs. If you even discuss something in the <span class="sc">gdb</span> source, refer to 148it by context, not by line number. 149 150 <p>The line numbers in our development sources will not match those in your 151sources. Your line numbers would convey no useful information to us. 152 153 </ul> 154 155 <p>Here are some things that are not necessary: 156 157 <ul> 158<li>A description of the envelope of the bug. 159 160 <p>Often people who encounter a bug spend a lot of time investigating 161which changes to the input file will make the bug go away and which 162changes will not affect it. 163 164 <p>This is often time consuming and not very useful, because the way we 165will find the bug is by running a single example under the debugger 166with breakpoints, not by pure deduction from a series of examples. 167We recommend that you save your time for something else. 168 169 <p>Of course, if you can find a simpler example to report <em>instead</em> 170of the original one, that is a convenience for us. Errors in the 171output will be easier to spot, running under the debugger will take 172less time, and so on. 173 174 <p>However, simplification is not vital; if you do not want to do this, 175report the bug anyway and send us the entire test case you used. 176 177 <li>A patch for the bug. 178 179 <p>A patch for the bug does help us if it is a good one. But do not omit 180the necessary information, such as the test case, on the assumption that 181a patch is all we need. We might see problems with your patch and decide 182to fix the problem another way, or we might not understand it at all. 183 184 <p>Sometimes with a program as complicated as <span class="sc">gdb</span> it is very hard to 185construct an example that will make the program follow a certain path 186through the code. If you do not send us the example, we will not be able 187to construct one, so we will not be able to verify that the bug is fixed. 188 189 <p>And if we cannot understand what bug you are trying to fix, or why your 190patch should be an improvement, we will not install it. A test case will 191help us to understand. 192 193 <li>A guess about what the bug is or what it depends on. 194 195 <p>Such guesses are usually wrong. Even we cannot guess right about such 196things without first using the debugger to find the facts. 197</ul> 198 199<!-- The readline documentation is distributed with the readline code --> 200<!-- and consists of the two following files: --> 201<!-- rluser.texinfo --> 202<!-- inc-hist.texinfo --> 203<!-- Use -I with makeinfo to point to the appropriate directory, --> 204<!-- environment var TEXINPUTS with TeX. --> 205<!-- %**start of header (This is for running Texinfo on a region.) --> 206<!-- %**end of header (This is for running Texinfo on a region.) --> 207<!-- If you are including this manual as an appendix, then set the --> 208<!-- variable readline-appendix. --> 209 </body></html> 210 211