Displaying and manipulating the source file with the dbx debug program

This section describes the process of displaying and manipulating the source file with the dbx debug program.

You can use the dbx debug program to search through and display portions of the source files for a program.

You do not need a current source listing for the search. The dbx debug program keeps track of the current file, current procedure, and current line. If a core file exists, the current line and current file are set initially to the line and file containing the source statement where the process ended. This is only true if the process stopped in a location compiled for debugging.

Changing the source directory path

By default, the dbx debug program searches for the source file of the program being debugged in the following directories:

Directory where the source file was located when it was compiled. This directory is searched only if the compiler placed the source path in the object.
Current directory.
Directory where the program is currently located.

You can change the list of directories to be searched by using the -I option on the dbx invocation line or issuing the use subcommand within the dbx program. For example, if you moved the source file to a new location since compilation time, you might want to use one of these commands to specify the old location, the new location, and some temporary location.

Displaying the current file

The list subcommand allows you to list source lines.

The $ (dollar sign) and @ (at sign) symbols represent SourceLineExpression and are useful with the list, stop, and trace subcommands. The $ symbol represents the next line to be run. The @ symbol represents the next line to be listed.

The move subcommand changes the next line number to be listed.

Changing the current file or procedure

Use the func and file subcommands to change the current file, current procedure, and current line within the dbx program without having to run any part of your program.

Search through the current file for text that matches regular expressions. If a match is found, the current line is set to the line containing the matching text. The syntax of the search subcommand is:

/ RegularExpression [/]: Searches forward in the current source file for the given expression.
? RegularExpression [?]: Searches backward in the current source file for the given expression.

If you repeat the search without arguments, the dbx command searches again for the previous regular expression. The search wraps around the end or beginning of the file.

You can also invoke an external text editor for your source file using the edit subcommand. You can override the default editor (vi) by setting the EDITOR environment variable to your desired editor before starting the dbx program.

The dbx program resumes control of the process when the editing session is completed.

Debugging programs involving multiple threads

Programs involving multiple user threads call the subroutine pthread_create. When a process calls this subroutine, the operating system creates a new thread of execution within the process. When debugging a multithreaded program, it is necessary to work with individual threads instead of with processes. The dbx program only works with user threads: in the dbx documentation, the word thread is usually used alone to mean user thread. The dbx program assigns a unique thread number to each thread in the process being debugged, and also supports the concept of a running and current thread:

Running thread: The user thread that was responsible for stopping the program by hitting a breakpoint. Subcommands that single-step the program work with the running thread.
Current thread: The user thread that you are examining. Subcommands that display information work in the context of the current thread.

By default, the running thread and current thread are the same. You can select a different current thread by using the thread subcommand. When the thread subcommand displays threads, the current thread line is preceded by a >. If the running thread is not the same as the current thread, its line is preceded by a *.

Debugging programs involving multiple processes

Programs involving multiple processes call the fork and exec subroutines. When a program forks, the operating system creates another process that has the same image as the original. The original process is called the parent process, the created process is called the child process.

When a process performs an exec subroutine, a new program takes over the original process. Under normal circumstances, the debug program debugs only the parent process. However, the dbx program can follow the execution and debug the new processes when you issue the multproc subcommand. The multproc subcommand enables multiprocess debugging.

When multiprocess debugging is enabled and a fork occurs, the parent and child processes are halted. A separate virtual terminal Xwindow is opened for a new version of the dbx program to control running of the child process:

(dbx) multproc on
(dbx) multproc
multi-process debugging is enabled
(dbx) run

When the fork occurs, execution is stopped in the parent, and the dbx program displays the state of the program:

application forked, child pid = 422, process stopped, awaiting input
stopped due to fork with multiprocessing enabled in fork at 0x1000025a (fork+0xe)
(dbx)

Another virtual terminal Xwindow is then opened to debug the child process:

debugging child, pid=422, process stopped, awaiting input
stopped due to fork with multiprocessing enabled in fork at 0x10000250
10000250 (fork+0x4) )80010010    1       r0,0x10(r1)
(dbx)

At this point, two distinct debugging sessions are running. The debugging session for the child process retains all the breakpoints from the parent process, but only the parent process can be rerun.

When a program performs an exec subroutine in multiprocess debugging mode, the program overwrites itself, and the original symbol information becomes obsolete. All breakpoints are deleted when the exec subroutine runs; the new program is stopped and identified for the debugging to be meaningful. The dbx program attaches itself to the new program image, makes a subroutine to determine the name of the new program, reports the name, and then prompts for input. The prompt is similar to the following:

(dbx) multproc
Multi-process debugging is enabled
(dbx) run
Attaching to program from exec . . . 
Determining program name . . . 
Successfully attached to /home/user/execprog . . . 
Reading symbolic information . . . 
(dbx)

If a multithreaded program forks, the new child process will have only one thread. The process should call the exec subroutine. Otherwise, the original symbol information is retained, and thread-related subcommands (such as thread) display the objects of the parent process, which are obsolete. If an exec subroutine is called, the original symbol information is reinitialized, and the thread-related subcommands display the objects in the new child process.

It is possible to follow the child process of a fork without a new Xwindow being opened by using the child flag of the multproc subcommand. When a forked process is created, dbx follows the child process. The parent flag of the multproc subcommand causes dbx to stop when a program forks, but then follows the parent. Both the child and parent flags follow an execed process. These flags are very useful for debugging programs when Xwindows is not running.