This chapter explains the basics of how to run dbx. It contains the following topics:
Before using dbx to debug a program, compile the program with the compiler's -g option (for example, cc -g). The -g option includes additional debugging information in your program object so that dbx can list local variables and find source lines.
If you use dbx to debug code that was not compiled using the -g option, local variables are invisible to dbx, and source lines may appear to jump around oddly as a result of various optimizations. It is more difficult to debug code without reliable references to lines of source code.
This section summarizes some hings you need to know if you compile and link your program with Dynamic Shared Objects (DSOs). A DSO is a relocatable shared library. By linking with a DSO, you keep your program size small and also use memory efficiently.
If you compile and link with DSOs, dbx automatically notices their use in the program and picks up the relevant debugging information. The dbx listobj command shows any DSOs in a process. The dbx whichobj command lists all DSOs in which a specified variable is present. The dbx listregions command identifies DSO addresses at run time.
The dbx help section on hint_dso has more information on dbx and DSOs. For more information on DSOs, refer to the MIPSpro N32/64 Compiling and Performance Tuning Guide.
This section describes how to invoke dbx and includes the following topics:
To invoke dbx from the shell command line, use the following dbx syntax:
dbx [options] [object_file [corefile]] |
After dbx starts, it displays the following prompt:
(dbx) |
To change this prompt, change the value of the dbx $prompt variable. “Setting dbx Variables” in Chapter 4, describes how to set dbx variables.
The following list describes options that you can give to the dbx command. These options are described in detail later in this chapter.
-c file: selects a command file other than .dbxinit to execute on starting dbx. For information about .dbxinit, see “Automatically Executing Commands on Startup”.
-d: provides startup information to the shell when a program is started with the run command.
-e num: chooses as large an evaluation stack size as you want. The default stack size is 20,000 bytes, where num is equal to the number of bytes. If you see the message too large to evaluate, rerun dbx while suppling a value greater than 20,000.
-i: uses interactive mode. This option prompts for source even when it reads from a file and treats data in a file as if it comes from a terminal (stdin). This option does not treat # characters as comments in a file.
-I dir: tells dbx to look in the specified directory (in addition to the current directory and the object file's directory) for source files. To specify multiple directories, use a separate -I option for each directory. If no directory is specified when you invoke dbx, it looks for source files in the current directory and in the object file's directory. From dbx, changes the directories searched for source files with the use and dir commands.
-k: turns on kernel debugging. When debugging a running system, specify /dev/kmem as the core file.
-N: sets the dbx $nonstop variable to 1 on startup. Attaching to a process does not stop the process. This affects only the dbx -p and dbx -P options and the addproc command.
-P name: debugs the running process with the specified name ( name as described in the ps(1) man page).
-p pid: debugs the process specified by the pid number.
-R: allows breakpoints in the runtime linker (rld).
-r program [ args]: runs the named program upon entering dbx by using the arguments specified by args. The .dbxinit file (if any) is read and executed after executing the object file. You cannot specify a core file with -r option.
The object_file is the name of the executable object file that you want to debug. It provides both the code that dbx executes and the symbol table that provides variable and procedure names and maps executable code to its corresponding source code in source files.
A corefile is produced when a program exits abnormally and produces a core dump. dbx allows you to provide the name of a core file that it uses as “the contents of memory” for the program that you specify. If you provide a core file, dbx lists the point of program failure. You can then perform stack traces and examine variable values to determine why a program crashed. However, you cannot force the program to execute past the line that caused it to crash.
If you do not specify a corefile, dbx examines the current directory for a file named core . If it finds core, and if core seems (based on data in the core file) to be a core dump of the program you specified, dbx acts as if you had specified core as the core file.
You can specify object and core files either as arguments when you invoke dbx or as commands that you enter at the dbx prompt.
The dbx givenfile and corefile commands allow you to set the object file and the core file, respectively, while dbx is running.
givenfile file: if you provide a filename, dbx kills the processes that currently are running and loads the executable code and debugging information found in file.
If you do not provide a filename, dbx displays the name of the program that it is currently debugging without changing it.
corefile file: if you provide a filename, dbx uses the program data stored in the core dump file.
If you do not provide a filename, dbx displays the name of the current core file without changing it.
You can start your program under dbx by using the run or the rerun command.
To verify exactly how your application is being started by the run or the rerun command, start dbx with the -d option.
run run-arguments: the run command starts your program and passes any arguments to it that you provide. The command uses your shell (the program named in the SHELL environment variable or in /bin/sh if an environment variable does not exist) to process a run command. The same syntax allowed in your shell is allowed on the run command line. All shell processing is accepted, such as expansion and substitution of * and ? in filenames. Redirection of the program's standard input and standard output, and/or standard error is also done by the shell.
Therefore, the dbx run command does exactly the same thing as typing target run-arguments at the shell prompt. You can specify target either on dbx invocation or in a prior givenfile command. dbx passes ./target as argv[0] to target when you specify it as a relative pathname.
The run command must appear on a line by itself and cannot be followed by another dbx command separated by a semicolon (;). Terminate the command line with a return. Note that you cannot include a run command in the command list of a when command.
The run command does not invoke the initialization files of the Bourne, C, and Korn shells before it starts a program. If you use a non-standard shell, before you run a program you should set the dbx variable called $shellparameters to a string that will instruct the shell to not load the initialization file. For example, for the C shell you would enter the following command:
% set $shellparameters = "-f"
If the SHELL environment variable is set to a C shell and your program has file-descriptors other than the default values (0,1,2), switch to the Bourne shell before you invoke the run command. This means you can use only sh-style redirections, because csh closes the extra file-descriptors. To switch shells for the purpose of running your program, use the following dbx command:
% setenv SHELL /bin/sh
rerun: the rerun command, without any arguments, repeats the last run command. rerun is equivalent to the run command without any arguments.
sort: the sort command takes an input file and produces a sorted output file; you can specify input and output files either through command-line arguments or file redirection. For example, from the command line you can enter:
% sort -i input -o output % sort < input2 > output2
If you are debugging the sort program, the equivalent dbx commands are:
(dbx) run -i input -o output (dbx) run < input2 > output2 |
If you execute these run commands in the order presented, you can repeat the last run command by using the rerun command:
(dbx) rerun |
You can use an editor to create a .dbxinit command file. This file contains various dbx commands that automatically execute when you invoke dbx. You can put any dbx command in the .dbxinit file. If a command requires input, the system prompts you for it when you invoke dbx .
On invocation, dbx looks for a .dbxinit file in the current directory. If the current directory does not contain a .dbxinit file, dbx looks for one in your home directory. (This assumes that you have set the IRIX system HOME environment variable.)
The dbx command help has several options:
help: shows the supported dbx commands.
help keyword: shows information pertaining to a given keyword, such as alias, help, most_used , quit, playback, record, and so on.
help all: shows the entire dbx help file.
When you type help all, dbx displays the help file by using the command name specified in the dbx $pager variable. The dbx help file is large and can be difficult to read even if you use a simple paging program like more(1). You can set the $pager variable to a text editor like vi (1) or to your favorite editor.
For example, just add the following command in your .dbxinit file:
% set $pager = "vi" |
When the above entry is in your .dbxinit file, dbx displays the help file in vi. You can then use the editor's search commands to look through the help file quickly. Quit the editor to return to dbx.
You can use a semicolon (;) as a separator to include multiple commands on the same command line. This is useful with commands such as when (described in “Writing Conditional Commands” in Chapter 6) because it allows you to include multiple commands in the command block.
For example:
(dbx)when at "myfile.c":37 {print a ; where ; print b} |
You can use a backslash (\) at the end of a line of input to indicate that the command is continued on the next line. This can be convenient when entering complex commands such as an alias definition (aliases are discussed in “Creating and Removing dbx Aliases” in Chapter 4).
For example:
(dbx) alias foll "print *(struct list *)$p ; \ set $p = (int)((struct list *)($p))->next" |
 | Note: You can also use the hed command for creating and modifying commands. “The History Editor” in Chapter 4, has details on this command. |
To invoke a subshell, enter the sh command at the dbx prompt, or enter the sh command and a shell command at the dbx prompt. After invoking a subshell, type the exit or Ctrl-d to return to dbx.
The syntax for the sh command is:
sh command |
The sh command alone invokes a subshell. The sh command syntax executes the specified command. dbx interprets the rest of the line as a command to pass to the spawned shell process, unless you enclose the command in double quotes or you terminate your shell command with a semicolon (;).
For example, to spawn a subshell, enter:
(dbx) sh % |
To display the end of the file datafile, enter:
(dbx) sh tail datafile |