1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> 2<html> 3<!-- Copyright (C) 1988-2021 Free Software Foundation, Inc. 4 5Permission is granted to copy, distribute and/or modify this document 6under the terms of the GNU Free Documentation License, Version 1.3 or 7any later version published by the Free Software Foundation; with the 8Invariant Sections being "Free Software" and "Free Software Needs 9Free Documentation", with the Front-Cover Texts being "A GNU Manual," 10and with the Back-Cover Texts as in (a) below. 11 12(a) The FSF's Back-Cover Text is: "You are free to copy and modify 13this GNU Manual. Buying copies from GNU Press supports the FSF in 14developing GNU and promoting software freedom." --> 15<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> 16<head> 17<title>Debugging with GDB: Mode Options</title> 18 19<meta name="description" content="Debugging with GDB: Mode Options"> 20<meta name="keywords" content="Debugging with GDB: Mode Options"> 21<meta name="resource-type" content="document"> 22<meta name="distribution" content="global"> 23<meta name="Generator" content="makeinfo"> 24<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> 25<link href="index.html#Top" rel="start" title="Top"> 26<link href="Concept-Index.html#Concept-Index" rel="index" title="Concept Index"> 27<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> 28<link href="Invoking-GDB.html#Invoking-GDB" rel="up" title="Invoking GDB"> 29<link href="Startup.html#Startup" rel="next" title="Startup"> 30<link href="File-Options.html#File-Options" rel="previous" title="File Options"> 31<style type="text/css"> 32<!-- 33a.summary-letter {text-decoration: none} 34blockquote.smallquotation {font-size: smaller} 35div.display {margin-left: 3.2em} 36div.example {margin-left: 3.2em} 37div.indentedblock {margin-left: 3.2em} 38div.lisp {margin-left: 3.2em} 39div.smalldisplay {margin-left: 3.2em} 40div.smallexample {margin-left: 3.2em} 41div.smallindentedblock {margin-left: 3.2em; font-size: smaller} 42div.smalllisp {margin-left: 3.2em} 43kbd {font-style:oblique} 44pre.display {font-family: inherit} 45pre.format {font-family: inherit} 46pre.menu-comment {font-family: serif} 47pre.menu-preformatted {font-family: serif} 48pre.smalldisplay {font-family: inherit; font-size: smaller} 49pre.smallexample {font-size: smaller} 50pre.smallformat {font-family: inherit; font-size: smaller} 51pre.smalllisp {font-size: smaller} 52span.nocodebreak {white-space:nowrap} 53span.nolinebreak {white-space:nowrap} 54span.roman {font-family:serif; font-weight:normal} 55span.sansserif {font-family:sans-serif; font-weight:normal} 56ul.no-bullet {list-style: none} 57--> 58</style> 59 60 61</head> 62 63<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> 64<a name="Mode-Options"></a> 65<div class="header"> 66<p> 67Next: <a href="Startup.html#Startup" accesskey="n" rel="next">Startup</a>, Previous: <a href="File-Options.html#File-Options" accesskey="p" rel="previous">File Options</a>, Up: <a href="Invoking-GDB.html#Invoking-GDB" accesskey="u" rel="up">Invoking GDB</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p> 68</div> 69<hr> 70<a name="Choosing-Modes"></a> 71<h4 class="subsection">2.1.2 Choosing Modes</h4> 72 73<p>You can run <small>GDB</small> in various alternative modes—for example, in 74batch mode or quiet mode. 75</p> 76<dl compact="compact"> 77<dd><a name="g_t_002dnx"></a></dd> 78<dt><code>-nx</code></dt> 79<dt><code>-n</code></dt> 80<dd><a name="index-_002d_002dnx"></a> 81<a name="index-_002dn"></a> 82<p>Do not execute commands found in any initialization file. 83There are three init files, loaded in the following order: 84</p> 85<dl compact="compact"> 86<dt><code><samp>system.gdbinit</samp></code></dt> 87<dd><p>This is the system-wide init file. 88Its location is specified with the <code>--with-system-gdbinit</code> 89configure option (see <a href="System_002dwide-configuration.html#System_002dwide-configuration">System-wide configuration</a>). 90It is loaded first when <small>GDB</small> starts, before command line options 91have been processed. 92</p></dd> 93<dt><code><samp>system.gdbinit.d</samp></code></dt> 94<dd><p>This is the system-wide init directory. 95Its location is specified with the <code>--with-system-gdbinit-dir</code> 96configure option (see <a href="System_002dwide-configuration.html#System_002dwide-configuration">System-wide configuration</a>). 97Files in this directory are loaded in alphabetical order immediately after 98system.gdbinit (if enabled) when <small>GDB</small> starts, before command line 99options have been processed. Files need to have a recognized scripting 100language extension (<samp>.py</samp>/<samp>.scm</samp>) or be named with a <samp>.gdb</samp> 101extension to be interpreted as regular <small>GDB</small> commands. <small>GDB</small> 102will not recurse into any subdirectories of this directory. 103</p></dd> 104<dt><code><samp>~/.gdbinit</samp></code></dt> 105<dd><p>This is the init file in your home directory. 106It is loaded next, after <samp>system.gdbinit</samp>, and before 107command options have been processed. 108</p></dd> 109<dt><code><samp>./.gdbinit</samp></code></dt> 110<dd><p>This is the init file in the current directory. 111It is loaded last, after command line options other than <code>-x</code> and 112<code>-ex</code> have been processed. Command line options <code>-x</code> and 113<code>-ex</code> are processed last, after <samp>./.gdbinit</samp> has been loaded. 114</p></dd> 115</dl> 116 117<p>For further documentation on startup processing, See <a href="Startup.html#Startup">Startup</a>. 118For documentation on how to write command files, 119See <a href="Command-Files.html#Command-Files">Command Files</a>. 120</p> 121<a name="g_t_002dnh"></a></dd> 122<dt><code>-nh</code></dt> 123<dd><a name="index-_002d_002dnh"></a> 124<p>Do not execute commands found in <samp>~/.gdbinit</samp>, the init file 125in your home directory. 126See <a href="Startup.html#Startup">Startup</a>. 127</p> 128</dd> 129<dt><code>-quiet</code></dt> 130<dt><code>-silent</code></dt> 131<dt><code>-q</code></dt> 132<dd><a name="index-_002d_002dquiet"></a> 133<a name="index-_002d_002dsilent"></a> 134<a name="index-_002dq"></a> 135<p>“Quiet”. Do not print the introductory and copyright messages. These 136messages are also suppressed in batch mode. 137</p> 138</dd> 139<dt><code>-batch</code></dt> 140<dd><a name="index-_002d_002dbatch"></a> 141<p>Run in batch mode. Exit with status <code>0</code> after processing all the 142command files specified with ‘<samp>-x</samp>’ (and all commands from 143initialization files, if not inhibited with ‘<samp>-n</samp>’). Exit with 144nonzero status if an error occurs in executing the <small>GDB</small> commands 145in the command files. Batch mode also disables pagination, sets unlimited 146terminal width and height see <a href="Screen-Size.html#Screen-Size">Screen Size</a>, and acts as if <kbd>set confirm 147off</kbd> were in effect (see <a href="Messages_002fWarnings.html#Messages_002fWarnings">Messages/Warnings</a>). 148</p> 149<p>Batch mode may be useful for running <small>GDB</small> as a filter, for 150example to download and run a program on another computer; in order to 151make this more useful, the message 152</p> 153<div class="smallexample"> 154<pre class="smallexample">Program exited normally. 155</pre></div> 156 157<p>(which is ordinarily issued whenever a program running under 158<small>GDB</small> control terminates) is not issued when running in batch 159mode. 160</p> 161</dd> 162<dt><code>-batch-silent</code></dt> 163<dd><a name="index-_002d_002dbatch_002dsilent"></a> 164<p>Run in batch mode exactly like ‘<samp>-batch</samp>’, but totally silently. All 165<small>GDB</small> output to <code>stdout</code> is prevented (<code>stderr</code> is 166unaffected). This is much quieter than ‘<samp>-silent</samp>’ and would be useless 167for an interactive session. 168</p> 169<p>This is particularly useful when using targets that give ‘<samp>Loading section</samp>’ 170messages, for example. 171</p> 172<p>Note that targets that give their output via <small>GDB</small>, as opposed to 173writing directly to <code>stdout</code>, will also be made silent. 174</p> 175</dd> 176<dt><code>-return-child-result</code></dt> 177<dd><a name="index-_002d_002dreturn_002dchild_002dresult"></a> 178<p>The return code from <small>GDB</small> will be the return code from the child 179process (the process being debugged), with the following exceptions: 180</p> 181<ul> 182<li> <small>GDB</small> exits abnormally. E.g., due to an incorrect argument or an 183internal error. In this case the exit code is the same as it would have been 184without ‘<samp>-return-child-result</samp>’. 185</li><li> The user quits with an explicit value. E.g., ‘<samp>quit 1</samp>’. 186</li><li> The child process never runs, or is not allowed to terminate, in which case 187the exit code will be -1. 188</li></ul> 189 190<p>This option is useful in conjunction with ‘<samp>-batch</samp>’ or ‘<samp>-batch-silent</samp>’, 191when <small>GDB</small> is being used as a remote program loader or simulator 192interface. 193</p> 194</dd> 195<dt><code>-nowindows</code></dt> 196<dt><code>-nw</code></dt> 197<dd><a name="index-_002d_002dnowindows"></a> 198<a name="index-_002dnw"></a> 199<p>“No windows”. If <small>GDB</small> comes with a graphical user interface 200(GUI) built in, then this option tells <small>GDB</small> to only use the command-line 201interface. If no GUI is available, this option has no effect. 202</p> 203</dd> 204<dt><code>-windows</code></dt> 205<dt><code>-w</code></dt> 206<dd><a name="index-_002d_002dwindows"></a> 207<a name="index-_002dw"></a> 208<p>If <small>GDB</small> includes a GUI, then this option requires it to be 209used if possible. 210</p> 211</dd> 212<dt><code>-cd <var>directory</var></code></dt> 213<dd><a name="index-_002d_002dcd"></a> 214<p>Run <small>GDB</small> using <var>directory</var> as its working directory, 215instead of the current directory. 216</p> 217</dd> 218<dt><code>-data-directory <var>directory</var></code></dt> 219<dt><code>-D <var>directory</var></code></dt> 220<dd><a name="index-_002d_002ddata_002ddirectory"></a> 221<a name="index-_002dD"></a> 222<p>Run <small>GDB</small> using <var>directory</var> as its data directory. 223The data directory is where <small>GDB</small> searches for its 224auxiliary files. See <a href="Data-Files.html#Data-Files">Data Files</a>. 225</p> 226</dd> 227<dt><code>-fullname</code></dt> 228<dt><code>-f</code></dt> 229<dd><a name="index-_002d_002dfullname"></a> 230<a name="index-_002df"></a> 231<p><small>GNU</small> Emacs sets this option when it runs <small>GDB</small> as a 232subprocess. It tells <small>GDB</small> to output the full file name and line 233number in a standard, recognizable fashion each time a stack frame is 234displayed (which includes each time your program stops). This 235recognizable format looks like two ‘<samp>\032</samp>’ characters, followed by 236the file name, line number and character position separated by colons, 237and a newline. The Emacs-to-<small>GDB</small> interface program uses the two 238‘<samp>\032</samp>’ characters as a signal to display the source code for the 239frame. 240</p> 241</dd> 242<dt><code>-annotate <var>level</var></code></dt> 243<dd><a name="index-_002d_002dannotate"></a> 244<p>This option sets the <em>annotation level</em> inside <small>GDB</small>. Its 245effect is identical to using ‘<samp>set annotate <var>level</var></samp>’ 246(see <a href="Annotations.html#Annotations">Annotations</a>). The annotation <var>level</var> controls how much 247information <small>GDB</small> prints together with its prompt, values of 248expressions, source lines, and other types of output. Level 0 is the 249normal, level 1 is for use when <small>GDB</small> is run as a subprocess of 250<small>GNU</small> Emacs, level 3 is the maximum annotation suitable for programs 251that control <small>GDB</small>, and level 2 has been deprecated. 252</p> 253<p>The annotation mechanism has largely been superseded by <small>GDB/MI</small> 254(see <a href="GDB_002fMI.html#GDB_002fMI">GDB/MI</a>). 255</p> 256</dd> 257<dt><code>--args</code></dt> 258<dd><a name="index-_002d_002dargs"></a> 259<p>Change interpretation of command line so that arguments following the 260executable file are passed as command line arguments to the inferior. 261This option stops option processing. 262</p> 263</dd> 264<dt><code>-baud <var>bps</var></code></dt> 265<dt><code>-b <var>bps</var></code></dt> 266<dd><a name="index-_002d_002dbaud"></a> 267<a name="index-_002db"></a> 268<p>Set the line speed (baud rate or bits per second) of any serial 269interface used by <small>GDB</small> for remote debugging. 270</p> 271</dd> 272<dt><code>-l <var>timeout</var></code></dt> 273<dd><a name="index-_002dl"></a> 274<p>Set the timeout (in seconds) of any communication used by <small>GDB</small> 275for remote debugging. 276</p> 277</dd> 278<dt><code>-tty <var>device</var></code></dt> 279<dt><code>-t <var>device</var></code></dt> 280<dd><a name="index-_002d_002dtty"></a> 281<a name="index-_002dt"></a> 282<p>Run using <var>device</var> for your program’s standard input and output. 283</p> 284</dd> 285<dt><code>-tui</code></dt> 286<dd><a name="index-_002d_002dtui"></a> 287<p>Activate the <em>Text User Interface</em> when starting. The Text User 288Interface manages several text windows on the terminal, showing 289source, assembly, registers and <small>GDB</small> command outputs 290(see <a href="TUI.html#TUI"><small>GDB</small> Text User Interface</a>). Do not use this 291option if you run <small>GDB</small> from Emacs (see <a href="Emacs.html#Emacs">Using <small>GDB</small> under <small>GNU</small> Emacs</a>). 292</p> 293</dd> 294<dt><code>-interpreter <var>interp</var></code></dt> 295<dd><a name="index-_002d_002dinterpreter"></a> 296<p>Use the interpreter <var>interp</var> for interface with the controlling 297program or device. This option is meant to be set by programs which 298communicate with <small>GDB</small> using it as a back end. 299See <a href="Interpreters.html#Interpreters">Command Interpreters</a>. 300</p> 301<p>‘<samp>--interpreter=mi</samp>’ (or ‘<samp>--interpreter=mi3</samp>’) causes 302<small>GDB</small> to use the <em><small>GDB/MI</small> interface</em> version 3 (see <a href="GDB_002fMI.html#GDB_002fMI">The <small>GDB/MI</small> Interface</a>) included since <small>GDB</small> version 9.1. <small>GDB/MI</small> 303version 2 (<code>mi2</code>), included in <small>GDB</small> 6.0 and version 1 (<code>mi1</code>), 304included in <small>GDB</small> 5.3, are also available. Earlier <small>GDB/MI</small> 305interfaces are no longer supported. 306</p> 307</dd> 308<dt><code>-write</code></dt> 309<dd><a name="index-_002d_002dwrite"></a> 310<p>Open the executable and core files for both reading and writing. This 311is equivalent to the ‘<samp>set write on</samp>’ command inside <small>GDB</small> 312(see <a href="Patching.html#Patching">Patching</a>). 313</p> 314</dd> 315<dt><code>-statistics</code></dt> 316<dd><a name="index-_002d_002dstatistics"></a> 317<p>This option causes <small>GDB</small> to print statistics about time and 318memory usage after it completes each command and returns to the prompt. 319</p> 320</dd> 321<dt><code>-version</code></dt> 322<dd><a name="index-_002d_002dversion"></a> 323<p>This option causes <small>GDB</small> to print its version number and 324no-warranty blurb, and exit. 325</p> 326</dd> 327<dt><code>-configuration</code></dt> 328<dd><a name="index-_002d_002dconfiguration"></a> 329<p>This option causes <small>GDB</small> to print details about its build-time 330configuration parameters, and then exit. These details can be 331important when reporting <small>GDB</small> bugs (see <a href="GDB-Bugs.html#GDB-Bugs">GDB Bugs</a>). 332</p> 333</dd> 334</dl> 335 336<hr> 337<div class="header"> 338<p> 339Next: <a href="Startup.html#Startup" accesskey="n" rel="next">Startup</a>, Previous: <a href="File-Options.html#File-Options" accesskey="p" rel="previous">File Options</a>, Up: <a href="Invoking-GDB.html#Invoking-GDB" accesskey="u" rel="up">Invoking GDB</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p> 340</div> 341 342 343 344</body> 345</html> 346