Go to the previous, next section.

Canned Sequences of Commands

Aside from breakpoint commands (see section Breakpoint Command Lists), _GDBN__ provides two ways to store sequences of commands for execution as a unit: user-defined commands and command files.

User-Defined Commands

A user-defined command is a sequence of _GDBN__ commands to which you assign a new name as a command. This is done with the define command.

define commandname

Define a command named commandname. If there is already a command by that name, you are asked to confirm that you want to redefine it.

The definition of the command is made up of other _GDBN__ command lines, which are given following the define command. The end of these commands is marked by a line containing end.

document commandname

Give documentation to the user-defined command commandname. The command commandname must already be defined. This command reads lines of documentation just as define reads the lines of the command definition, ending with end. After the document command is finished, help on command commandname will print the documentation you have specified.

You may use the document command again to change the documentation of a command. Redefining the command with define does not change the documentation.

help user-defined

List all user-defined commands, with the first line of the documentation (if any) for each.

show user

show user commandname

Display the _GDBN__ commands used to define commandname (but not its documentation). If no commandname is given, display the definitions for all user-defined commands.

User-defined commands do not take arguments. When they are executed, the commands of the definition are not printed. An error in any command stops execution of the user-defined command.

Commands that would ask for confirmation if used interactively proceed without asking when used inside a user-defined command. Many _GDBN__ commands that normally print messages to say what they are doing omit the messages when used in a user-defined command.

User-Defined Command Hooks

You may define hooks, which are a special kind of user-defined command. Whenever you run the command `foo', if the user-defined command `hook-foo' exists, it is executed (with no arguments) before that command.

In addition, a pseudo-command, `stop' exists. Hooking this command will cause your hook to be executed every time execution stops in the inferior program, before breakpoint commands are run, displays are printed, or the stack frame is printed.

For example, to cause SIGALRM signals to be ignored while single-stepping, but cause them to be resumed during normal execution, you could do:

define hook-stop
handle SIGALRM nopass
end

define hook-run
handle SIGALRM pass
end

define hook-continue
handle SIGLARM pass
end

Any single-word command in GDB can be hooked. Aliases for other commands cannot be hooked (you should hook the basic command name, e.g. backtrace rather than bt). If an error occurs during the execution of your hook, execution of GDB commands stops and you are returned to the GDB prompt (before the command that you actually typed had a chance to run).

If you try to define a hook which doesn't match any known command, you will get a warning from the define command.

Command Files

A command file for _GDBN__ is a file of lines that are _GDBN__ 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.

When you start _GDBN__, it automatically executes commands from its init files. These are files named `_GDBINIT__'. _GDBN__ reads the init file (if any) in your home directory and then the init file (if any) in the current working directory. (The init files are not executed if you use the `-nx' option; see section Choosing Modes.) You can also request the execution of a command file with the source command:

source filename

Execute the command file filename.

The lines in a command file are executed sequentially. They are not printed as they are executed. An error in any command terminates execution of the command file.

Commands that would ask for confirmation if used interactively proceed without asking when used in a command file. Many _GDBN__ commands that normally print messages to say what they are doing omit the messages when called from command files.

Commands for Controlled Output

During the execution of a command file or a user-defined command, normal _GDBN__ output is suppressed; the only output that appears is what is explicitly printed by the commands in the definition. This section describes three commands useful for generating exactly the output you want.

echo text

Print text. Nonprinting characters can be included in text using C escape sequences, such as `\n' to print a newline. No newline will be printed unless you specify one. In addition to the standard C escape sequences, a backslash followed by a space stands for a space. This is useful for outputting a string with spaces at the beginning or the end, since leading and trailing spaces are otherwise trimmed from all arguments. To print ` and foo = ', use the command `echo \ and foo = \ '.

A backslash at the end of text can be used, as in C, to continue the command onto subsequent lines. For example,

echo This is some text\n\
which is continued\n\
onto several lines.\n

produces the same output as

echo This is some text\n
echo which is continued\n
echo onto several lines.\n

output expression

Print the value of expression and nothing but that value: no newlines, no `$nn = '. The value is not entered in the value history either. See section Expressions, for more information on expressions.

output/fmt expression

Print the value of expression in format fmt. You can use the same formats as for print; see section Output formats, for more information.

printf string, expressions...

Print the values of the expressions under the control of string. The expressions are separated by commas and may be either numbers or pointers. Their values are printed as specified by string, exactly as if your program were to execute

printf (string, expressions...);

For example, you can print two values in hex like this:

printf "foo, bar-foo = 0x%x, 0x%x\n", foo, bar-foo

The only backslash-escape sequences that you can use in the format string are the simple ones that consist of backslash followed by a letter.

_if__(!_DOSHOST__)

Go to the previous, next section.