Using the command line interface of debug

Code in header files

None of the programs in this tutorial have code that comes from an included file, but having code in header files is a common situation, particularly in C++ programs, which frequently have numerous inline functions defined in header files or make use of templates, whose source may be included automatically by the compiler. Any statement that comes from a header file is displayed by the debugger in terms of both the compilation unit (or primary source file name) and the included file name, using the syntax compilation_unit@included_file. For example, given the following program:

   process.c:
     #include <stdlib.h>
     #include "chdr.h"
     
     void
     process(char *str)
     {
   	f(str);
      	...
     }
      
   chdr.h:
   
     static void
     f(char *str)
     {
   	if (str == 0)
   		return;
      	...
     }

The location of the function f called by the function process is given by process.c@chdr.h@f. When you stop in that function, the location is displayed in the event notification and in the stack trace.

   debug> stop process.c@chdr.h@f
   EVENT [1] assigned
   debug> run
   STOP EVENT TRIGGERED: f  in p1 [f in process.c@chdr.h]
   4:		if (file == 0)
   debug> stack
   Stack Trace for p1, Program a.out
   *[0] f(str="testing")	[process.c@chdr.h@4]
    [1] process(str="testing")	[process.c@6]
           ...

Also, although the source file displayed by list is from chdr.h, the debugger can only find chdr.h by looking through the debugging information generated for process.c. The debugger variables %file and %list_file reflect that condition:

   debug> print %list_file
   "process.c@chdr.h"

This has several implications for you in setting breakpoints or in examining the source for code in included files:

Any command that takes a location (dis, run, list, etc.) will accept a compilation_unit@included_file pair:
```
      debug> list process.c@chdr@1
      1:	static void
      2:	f(char *str)
      3:   ...
```
You may also refer to an entity in an included file without naming the compilation unit. If you give only one file name, the debugger will first assume it is the name of a primay source file, and will try to find a compilation unit with that name. If that fails, the debugger will then try to find an included file with that name in the current compilation unit. If that also fails, debug will ask you if it should search through all the compilation units until it finds an included file with that name. Note that if you are debugging a large program with many files, this search can take a while and may consume a lot of memory.
```
      debug> dis chdr.h@4
      File chdr.h was not found.
      Search program for an included file?
      debug> yes
      Disassembly for p1, Program a.out
       . . .
```
If you attempt to set a breakpoint on a function or line number from an included file without specifying the compilation unit, the debugger will ask if you want to set a breakpoint on all instances. If you reply affirmatively, debug will search through all the compilation units in your program to find all that include that file.
```
      debug> stop chdr.h@4
      Set a breakpoint on all occurrences of chdr.h@4?
      debug> yes
      EVENT [3] assigned
```
If you are stopped in code from an included file, command line_num will apply command to line_num in the included file. To refer to a line number in the primary source file when stopped in the included file, or vice versa, the file name must be specified.