doc/gdb/Command-Files.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Copyright (C) 1988-2021 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with the
Invariant Sections being "Free Software" and "Free Software Needs
Free Documentation", with the Front-Cover Texts being "A GNU Manual,"
and with the Back-Cover Texts as in (a) below.

(a) The FSF's Back-Cover Text is: "You are free to copy and modify
this GNU Manual.  Buying copies from GNU Press supports the FSF in
developing GNU and promoting software freedom." -->
<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ -->
<head>
<title>Debugging with GDB: Command Files</title>

<meta name="description" content="Debugging with GDB: Command Files">
<meta name="keywords" content="Debugging with GDB: Command Files">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link href="index.html#Top" rel="start" title="Top">
<link href="Concept-Index.html#Concept-Index" rel="index" title="Concept Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="Sequences.html#Sequences" rel="up" title="Sequences">
<link href="Output.html#Output" rel="next" title="Output">
<link href="Hooks.html#Hooks" rel="previous" title="Hooks">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.indentedblock {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smallindentedblock {margin-left: 3.2em; font-size: smaller}
div.smalllisp {margin-left: 3.2em}
kbd {font-style:oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nocodebreak {white-space:nowrap}
span.nolinebreak {white-space:nowrap}
span.roman {font-family:serif; font-weight:normal}
span.sansserif {font-family:sans-serif; font-weight:normal}
ul.no-bullet {list-style: none}
-->
</style>


</head>

<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
<a name="Command-Files"></a>
<div class="header">
<p>
Next: <a href="Output.html#Output" accesskey="n" rel="next">Output</a>, Previous: <a href="Hooks.html#Hooks" accesskey="p" rel="previous">Hooks</a>, Up: <a href="Sequences.html#Sequences" accesskey="u" rel="up">Sequences</a> &nbsp; [<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>
</div>
<hr>
<a name="Command-Files-1"></a>
<h4 class="subsection">23.1.3 Command Files</h4>

<a name="index-command-files"></a>
<a name="index-scripting-commands"></a>
<p>A command file for <small>GDB</small> is a text file made of lines that are
<small>GDB</small> commands.  Comments (lines starting with <kbd>#</kbd>) may
also be included.  An empty line in a command file does nothing; it
does not mean to repeat the last command, as it would from the
terminal.
</p>
<p>You can request the execution of a command file with the <code>source</code>
command.  Note that the <code>source</code> command is also used to evaluate
scripts that are not Command Files.  The exact behavior can be configured
using the <code>script-extension</code> setting.
See <a href="Extending-GDB.html#Extending-GDB">Extending GDB</a>.
</p>
<dl compact="compact">
<dd><a name="index-source"></a>
<a name="index-execute-commands-from-a-file"></a>
</dd>
<dt><code>source [-s] [-v] <var>filename</var></code></dt>
<dd><p>Execute the command file <var>filename</var>.
</p></dd>
</dl>

<p>The lines in a command file are generally executed sequentially,
unless the order of execution is changed by one of the
<em>flow-control commands</em> described below.  The commands are not
printed as they are executed.  An error in any command terminates
execution of the command file and control is returned to the console.
</p>
<p><small>GDB</small> first searches for <var>filename</var> in the current directory.
If the file is not found there, and <var>filename</var> does not specify a
directory, then <small>GDB</small> also looks for the file on the source search path
(specified with the &lsquo;<samp>directory</samp>&rsquo; command);
except that <samp>$cdir</samp> is not searched because the compilation directory
is not relevant to scripts.
</p>
<p>If <code>-s</code> is specified, then <small>GDB</small> searches for <var>filename</var>
on the search path even if <var>filename</var> specifies a directory.
The search is done by appending <var>filename</var> to each element of the
search path.  So, for example, if <var>filename</var> is <samp>mylib/myscript</samp>
and the search path contains <samp>/home/user</samp> then <small>GDB</small> will
look for the script <samp>/home/user/mylib/myscript</samp>.
The search is also done if <var>filename</var> is an absolute path.
For example, if <var>filename</var> is <samp>/tmp/myscript</samp> and
the search path contains <samp>/home/user</samp> then <small>GDB</small> will
look for the script <samp>/home/user/tmp/myscript</samp>.
For DOS-like systems, if <var>filename</var> contains a drive specification,
it is stripped before concatenation.  For example, if <var>filename</var> is
<samp>d:myscript</samp> and the search path contains <samp>c:/tmp</samp> then <small>GDB</small>
will look for the script <samp>c:/tmp/myscript</samp>.
</p>
<p>If <code>-v</code>, for verbose mode, is given then <small>GDB</small> displays
each command as it is executed.  The option must be given before
<var>filename</var>, and is interpreted as part of the filename anywhere else.
</p>
<p>Commands that would ask for confirmation if used interactively proceed
without asking when used in a command file.  Many <small>GDB</small> commands that
normally print messages to say what they are doing omit the messages
when called from command files.
</p>
<p><small>GDB</small> also accepts command input from standard input.  In this
mode, normal output goes to standard output and error output goes to
standard error.  Errors in a command file supplied on standard input do
not terminate execution of the command file&mdash;execution continues with
the next command.
</p>
<div class="smallexample">
<pre class="smallexample">gdb &lt; cmds &gt; log 2&gt;&amp;1
</pre></div>

<p>(The syntax above will vary depending on the shell used.) This example
will execute commands from the file <samp>cmds</samp>. All output and errors
would be directed to <samp>log</samp>.
</p>
<p>Since commands stored on command files tend to be more general than
commands typed interactively, they frequently need to deal with
complicated situations, such as different or unexpected values of
variables and symbols, changes in how the program being debugged is
built, etc.  <small>GDB</small> provides a set of flow-control commands to
deal with these complexities.  Using these commands, you can write
complex scripts that loop over data structures, execute commands
conditionally, etc.
</p>
<dl compact="compact">
<dd><a name="index-if"></a>
<a name="index-else"></a>
</dd>
<dt><code>if</code></dt>
<dt><code>else</code></dt>
<dd><p>This command allows to include in your script conditionally executed
commands. The <code>if</code> command takes a single argument, which is an
expression to evaluate.  It is followed by a series of commands that
are executed only if the expression is true (its value is nonzero).
There can then optionally be an <code>else</code> line, followed by a series
of commands that are only executed if the expression was false.  The
end of the list is marked by a line containing <code>end</code>.
</p>
<a name="index-while"></a>
</dd>
<dt><code>while</code></dt>
<dd><p>This command allows to write loops.  Its syntax is similar to
<code>if</code>: the command takes a single argument, which is an expression
to evaluate, and must be followed by the commands to execute, one per
line, terminated by an <code>end</code>.  These commands are called the
<em>body</em> of the loop.  The commands in the body of <code>while</code> are
executed repeatedly as long as the expression evaluates to true.
</p>
<a name="index-loop_005fbreak"></a>
</dd>
<dt><code>loop_break</code></dt>
<dd><p>This command exits the <code>while</code> loop in whose body it is included.
Execution of the script continues after that <code>while</code>s <code>end</code>
line.
</p>
<a name="index-loop_005fcontinue"></a>
</dd>
<dt><code>loop_continue</code></dt>
<dd><p>This command skips the execution of the rest of the body of commands
in the <code>while</code> loop in whose body it is included.  Execution
branches to the beginning of the <code>while</code> loop, where it evaluates
the controlling expression.
</p>
<a name="index-end-_0028if_002felse_002fwhile-commands_0029"></a>
</dd>
<dt><code>end</code></dt>
<dd><p>Terminate the block of commands that are the body of <code>if</code>,
<code>else</code>, or <code>while</code> flow-control commands.
</p></dd>
</dl>


<hr>
<div class="header">
<p>
Next: <a href="Output.html#Output" accesskey="n" rel="next">Output</a>, Previous: <a href="Hooks.html#Hooks" accesskey="p" rel="previous">Hooks</a>, Up: <a href="Sequences.html#Sequences" accesskey="u" rel="up">Sequences</a> &nbsp; [<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>
</div>


</body>
</html>