A command file for GDB is a text file made of lines that are GDB commands. Comments (lines starting with #) 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.
You can request the execution of a command file with the source
command. Note that the source command is also used to evaluate
scripts that are not Command Files. The exact behavior can be configured
using the script-extension setting.
See Extending GDB.
source [-s] [-v] filenameExecute the command file filename.
The lines in a command file are generally executed sequentially, unless the order of execution is changed by one of the flow-control commands 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.
GDB first searches for filename in the current directory. If the file is not found there, and filename does not specify a directory, then GDB also looks for the file on the source search path (specified with the ‘directory’ command); except that $cdir is not searched because the compilation directory is not relevant to scripts.
If -s is specified, then GDB searches for filename
on the search path even if filename specifies a directory.
The search is done by appending filename to each element of the
search path. So, for example, if filename is mylib/myscript
and the search path contains /home/user then GDB will
look for the script /home/user/mylib/myscript.
The search is also done if filename is an absolute path.
For example, if filename is /tmp/myscript and
the search path contains /home/user then GDB will
look for the script /home/user/tmp/myscript.
For DOS-like systems, if filename contains a drive specification,
it is stripped before concatenation. For example, if filename is
d:myscript and the search path contains c:/tmp then GDB
will look for the script c:/tmp/myscript.
If -v, for verbose mode, is given then GDB displays
each command as it is executed. The option must be given before
filename, and is interpreted as part of the filename anywhere else.
Commands that would ask for confirmation if used interactively proceed without asking when used in a command file. Many GDB commands that normally print messages to say what they are doing omit the messages when called from command files.
GDB 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—execution continues with the next command.
gdb < cmds > log 2>&1
(The syntax above will vary depending on the shell used.) This example will execute commands from the file cmds. All output and errors would be directed to log.
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. GDB 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.
ifelseThis command allows to include in your script conditionally executed
commands. The if 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 else 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 end.
whileThis command allows to write loops. Its syntax is similar to
if: 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 end. These commands are called the
body of the loop. The commands in the body of while are
executed repeatedly as long as the expression evaluates to true.
loop_breakThis command exits the while loop in whose body it is included.
Execution of the script continues after that whiles end
line.
loop_continueThis command skips the execution of the rest of the body of commands
in the while loop in whose body it is included. Execution
branches to the beginning of the while loop, where it evaluates
the controlling expression.
endTerminate the block of commands that are the body of if,
else, or while flow-control commands.