7. Examining Source Files

GDB can print parts of your program's source, since the debugging information recorded in the program tells GDB what source files were used to build it. When your program stops, GDB spontaneously prints the line where it stopped. Likewise, when you select a stack frame (see section Selecting a Frame), GDB prints the line where execution in that frame has stopped. You can print other portions of source files by explicit command.

If you use GDB through its GNU Emacs interface, you may prefer to use Emacs facilities to view source; see Using GDB under GNU Emacs.

7.1 Printing Source Lines		Printing source lines
7.2 Specifying a Location		How to specify code locations
7.3 Editing Source Files		Editing source files
7.4 Searching Source Files		Searching source files
7.5 Specifying Source Directories		Specifying source directories
7.6 Source and Machine Code		Source and machine code

7.1 Printing Source Lines

To print lines from a source file, use the list command (abbreviated l). By default, ten lines are printed. There are several ways to specify what part of the file you want to print; see 7.2 Specifying a Location, for the full list.

Here are the forms of the list command most commonly used:

list linenum

Print lines centered around line number linenum in the current source file.

list function

Print lines centered around the beginning of function function.

list

Print more lines. If the last lines printed were printed with a list command, this prints lines following the last lines printed; however, if the last line printed was a solitary line printed as part of displaying a stack frame (see section Examining the Stack), this prints lines centered around that line.

list -

Print lines just before the lines last printed.

By default, GDB prints ten source lines with any of these forms of the list command. You can change this using set listsize:

set listsize count

Make the list command display count source lines (unless the list argument explicitly specifies some other number).

show listsize

Display the number of lines that list prints.

Repeating a list command with RET discards the argument, so it is equivalent to typing just list. This is more useful than listing the same lines again. An exception is made for an argument of `-'; that argument is preserved in repetition so that each repetition moves up in the source file.

In general, the list command expects you to supply zero, one or two linespecs. Linespecs specify source lines; there are several ways of writing them (see section 7.2 Specifying a Location), but the effect is always to specify some source line.

Here is a complete description of the possible arguments for list:

list linespec

Print lines centered around the line specified by linespec.

list first,last

Print lines from first to last. Both arguments are linespecs. When a list command has two linespecs, and the source file of the second linespec is omitted, this refers to the same source file as the first linespec.

list ,last

Print lines ending with last.

list first,

Print lines starting with first.

list +

Print lines just after the lines last printed.

list -

Print lines just before the lines last printed.

list

As described in the preceding table.

7.2 Specifying a Location

Several GDB commands accept arguments that specify a location of your program's code. Since GDB is a source-level debugger, a location usually specifies some line in the source code; for that reason, locations are also known as linespecs.

Here are all the different ways of specifying a code location that GDB understands:

linenum

Specifies the line number linenum of the current source file.

-offset

+offset

Specifies the line offset lines before or after the current line. For the list command, the current line is the last one printed; for the breakpoint commands, this is the line at which execution stopped in the currently selected stack frame (see section Frames, for a description of stack frames.) When used as the second of the two linespecs in a list command, this specifies the line offset lines up or down from the first linespec.

filename:linenum

Specifies the line linenum in the source file filename.

function

Specifies the line that begins the body of the function function. For example, in C, this is the line with the open brace.

filename:function

Specifies the line that begins the body of the function function in the file filename. You only need the file name with a function name to avoid ambiguity when there are identically named functions in different source files.

*address

Specifies the program address address. For line-oriented commands, such as list and edit, this specifies a source line that contains address. For break and other breakpoint oriented commands, this can be used to set breakpoints in parts of your program which do not have debugging information or source files.

Here address may be any expression valid in the current working language (see section working language) that specifies a code address. In addition, as a convenience, GDB extends the semantics of expressions used in locations to cover the situations that frequently happen during debugging. Here are the various forms of address:

expression

Any expression valid in the current working language.

funcaddr

An address of a function or procedure derived from its name. In C, C++, Java, Objective-C, Fortran, minimal, and assembly, this is simply the function's name function (and actually a special case of a valid expression). In Pascal and Modula-2, this is &function. In Ada, this is function'Address (although the Pascal form also works).

This form specifies the address of the function's first instruction, before the stack frame and arguments have been set up.

'filename'::funcaddr

Like funcaddr above, but also specifies the name of the source file explicitly. This is useful if the name of the function does not specify the function unambiguously, e.g., if there are several functions with identical names in different source files.

7.3 Editing Source Files

To edit the lines in a source file, use the edit command. The editing program of your choice is invoked with the current line set to the active line in the program. Alternatively, there are several ways to specify what part of the file you want to print if you want to see other parts of the program:

edit location

Edit the source file specified by location. Editing starts at that location, e.g., at the specified source line of the specified file. See section 7.2 Specifying a Location, for all the possible forms of the location argument; here are the forms of the edit command most commonly used:

edit number

Edit the current source file with number as the active line number.

edit function

Edit the file containing function at the beginning of its definition.

7.3.1 Choosing your Editor

EDITOR=/usr/bin/vi
export EDITOR
gdb ...

setenv EDITOR /usr/bin/vi
gdb ...

7.4 Searching Source Files

There are two commands for searching through the current source file for a regular expression.

forward-search regexp

search regexp

The command `forward-search regexp' checks each line, starting with the one following the last line listed, for a match for regexp. It lists the line that is found. You can use the synonym `search regexp' or abbreviate the command name as fo.

reverse-search regexp

The command `reverse-search regexp' checks each line, starting with the one before the last line listed and going backward, for a match for regexp. It lists the line that is found. You can abbreviate this command as rev.

7.5 Specifying Source Directories

Executable programs sometimes do not record the directories of the source files from which they were compiled, just the names. Even when they do, the directories could be moved between the compilation and your debugging session. GDB has a list of directories to search for source files; this is called the source path. Each time GDB wants a source file, it tries all the directories in the list, in the order they are present in the list, until it finds a file with the desired name.

For example, suppose an executable references the file `/usr/src/foo-1.0/lib/foo.c', and our source path is `/mnt/cross'. The file is first looked up literally; if this fails, `/mnt/cross/usr/src/foo-1.0/lib/foo.c' is tried; if this fails, `/mnt/cross/foo.c' is opened; if this fails, an error message is printed. GDB does not look up the parts of the source file name, such as `/mnt/cross/src/foo-1.0/lib/foo.c'. Likewise, the subdirectories of the source path are not searched: if the source path is `/mnt/cross', and the binary refers to `foo.c', GDB would not find it under `/mnt/cross/usr/src/foo-1.0/lib'.

Plain file names, relative file names with leading directories, file names containing dots, etc. are all treated as described above; for instance, if the source path is `/mnt/cross', and the source file is recorded as `../lib/foo.c', GDB would first try `../lib/foo.c', then `/mnt/cross/../lib/foo.c', and after that---`/mnt/cross/foo.c'.

Note that the executable search path is not used to locate the source files.

Whenever you reset or rearrange the source path, GDB clears out any information it has cached about where source files are found and where each line is in the file.

When you start GDB, its source path includes only `cdir' and `cwd', in that order. To add other directories, use the directory command.

The search path is used to find both program source files and GDB script files (read using the `-command' option and `source' command).

In addition to the source path, GDB provides a set of commands that manage a list of source path substitution rules. A substitution rule specifies how to rewrite source directories stored in the program's debug information in case the sources were moved to a different directory between compilation and debugging. A rule is made of two strings, the first specifying what needs to be rewritten in the path, and the second specifying how it should be rewritten. In set substitute-path, we name these two parts from and to respectively. GDB does a simple string replacement of from with to at the start of the directory part of the source file name, and uses that result instead of the original file name to look up the sources.

Using the previous example, suppose the `foo-1.0' tree has been moved from `/usr/src' to `/mnt/cross', then you can tell GDB to replace `/usr/src' in all source path names with `/mnt/cross'. The first lookup will then be `/mnt/cross/foo-1.0/lib/foo.c' in place of the original location of `/usr/src/foo-1.0/lib/foo.c'. To define a source path substitution rule, use the set substitute-path command (see set substitute-path).

To avoid unexpected substitution results, a rule is applied only if the from part of the directory name ends at a directory separator. For instance, a rule substituting `/usr/source' into `/mnt/cross' will be applied to `/usr/source/foo-1.0' but not to `/usr/sourceware/foo-2.0'. And because the substitution is applied only at the beginning of the directory name, this rule will not be applied to `/root/usr/source/baz.c' either.

In many cases, you can achieve the same result using the directory command. However, set substitute-path can be more efficient in the case where the sources are organized in a complex tree with multiple subdirectories. With the directory command, you need to add each subdirectory of your project. If you moved the entire tree while preserving its internal organization, then set substitute-path allows you to direct the debugger to all the sources with one single command.

set substitute-path is also more than just a shortcut command. The source path is only used if the file at the original location no longer exists. On the other hand, set substitute-path modifies the debugger behavior to look at the rewritten location instead. So, if for any reason a source file that is not relevant to your executable is located at the original location, a substitution rule is the only method available to point GDB at the new location.

directory dirname ...

dir dirname ...

Add directory dirname to the front of the source path. Several directory names may be given to this command, separated by `:' (`;' on MS-DOS and MS-Windows, where `:' usually appears as part of absolute file names) or whitespace. You may specify a directory that is already in the source path; this moves it forward, so GDB searches it sooner.

You can use the string `$cdir' to refer to the compilation directory (if one is recorded), and `$cwd' to refer to the current working directory. `$cwd' is not the same as `.'---the former tracks the current working directory as it changes during your GDB session, while the latter is immediately expanded to the current directory at the time you add an entry to the source path.

directory

Reset the source path to its default value (`$cdir:$cwd' on Unix systems). This requires confirmation.

show directories

Print the source path: show which directories it contains.

set substitute-path from to

Define a source path substitution rule, and add it at the end of the current list of existing substitution rules. If a rule with the same from was already defined, then the old rule is also deleted.

For example, if the file `/foo/bar/baz.c' was moved to `/mnt/cross/baz.c', then the command

(gdb) set substitute-path /usr/src /mnt/cross

will tell GDB to replace `/usr/src' with `/mnt/cross', which will allow GDB to find the file `baz.c' even though it was moved.

In the case when more than one substitution rule have been defined, the rules are evaluated one by one in the order where they have been defined. The first one matching, if any, is selected to perform the substitution.

For instance, if we had entered the following commands:

(gdb) set substitute-path /usr/src/include /mnt/include (gdb) set substitute-path /usr/src /mnt/src

GDB would then rewrite `/usr/src/include/defs.h' into `/mnt/include/defs.h' by using the first rule. However, it would use the second rule to rewrite `/usr/src/lib/foo.c' into `/mnt/src/lib/foo.c'.

unset substitute-path [path]

If a path is specified, search the current list of substitution rules for a rule that would rewrite that path. Delete that rule if found. A warning is emitted by the debugger if no rule could be found.

If no path is specified, then all substitution rules are deleted.

show substitute-path [path]

If a path is specified, then print the source path substitution rule which would rewrite that path, if any.

If no path is specified, then print all existing source path substitution rules.

If your source path is cluttered with directories that are no longer of interest, GDB may sometimes cause confusion by finding the wrong versions of source. You can correct the situation as follows:

1. Use directory with no argument to reset the source path to its default value.

2. Use directory with suitable arguments to reinstall the directories you want in the source path. You can add all the directories in one command.

7.6 Source and Machine Code

You can use the command info line to map source lines to program addresses (and vice versa), and the command disassemble to display a range of addresses as machine instructions. When run under GNU Emacs mode, the info line command causes the arrow to point to the line specified. Also, info line prints addresses in symbolic form as well as hex.

info line linespec

Print the starting and ending addresses of the compiled code for source line linespec. You can specify source lines in any of the ways documented in 7.2 Specifying a Location.

For example, we can use info line to discover the location of the object code for the first line of function m4_changequote:

(gdb) info line m4_changequote Line 895 of "builtin.c" starts at pc 0x634c and ends at 0x6350.

We can also inquire (using *addr as the form for linespec) what source line covers a particular address:

(gdb) info line *0x63ff Line 926 of "builtin.c" starts at pc 0x63e4 and ends at 0x6404.

After info line, the default address for the x command is changed to the starting address of the line, so that `x/i' is sufficient to begin examining the machine code (see section Examining Memory). Also, this address is saved as the value of the convenience variable $_ (see section Convenience Variables).

disassemble

This specialized command dumps a range of memory as machine instructions. The default memory range is the function surrounding the program counter of the selected frame. A single argument to this command is a program counter value; GDB dumps the function surrounding this value. Two arguments specify a range of addresses (first inclusive, second exclusive) to dump.

The following example shows the disassembly of a range of addresses of HP PA-RISC 2.0 code:

(gdb) disas 0x32c4 0x32e4 Dump of assembler code from 0x32c4 to 0x32e4: 0x32c4 <main+204>: addil 0,dp 0x32c8 <main+208>: ldw 0x22c(sr0,r1),r26 0x32cc <main+212>: ldil 0x3000,r31 0x32d0 <main+216>: ble 0x3f8(sr4,r31) 0x32d4 <main+220>: ldo 0(r31),rp 0x32d8 <main+224>: addil -0x800,dp 0x32dc <main+228>: ldo 0x588(r1),r26 0x32e0 <main+232>: ldil 0x3000,r31 End of assembler dump.

Some architectures have more than one commonly-used set of instruction mnemonics or other syntax.

For programs that were dynamically linked and use shared libraries, instructions that call functions or branch to locations in the shared libraries might show a seemingly bogus location--it's actually a location of the relocation table. On some architectures, GDB might be able to resolve these to actual function names.

set disassembly-flavor instruction-set

Select the instruction set to use when disassembling the program via the disassemble or x/i commands.

Currently this command is only defined for the Intel x86 family. You can set instruction-set to either intel or att. The default is att, the AT&T flavor used by default by Unix assemblers for x86-based targets.

show disassembly-flavor

Show the current setting of the disassembly flavor.