To set an unconditional breakpoint, you simply specify the point at which you want to stop program execution, using one of the following forms of the stop command:

---

Caution: If your program has multiple source files, be sure to set the breakpoint in the correct file. To do so, you can explicitly set the source file using dbx's file command (see "Changing Source Files") or you can use the func command to go to a source file containing a specified function (see "Moving to a Specified Procedure").

---

An unconditional breakpoint is the simplest type of breakpoint; your program stops every time it reaches a specified place. On the other hand, a conditional breakpoint stops your program only if a condition that you specify is true. The two conditions that you can test are:

By including a variable clause in your stop command, you can cause dbx to stop if the value of a variable or the contents of a memory location has changed.

If you provide only a variable name in your variable clause, the breakpoint stops your program if the value of the variable has changed since the last time dbx checked it. If instead of a variable name, you provide an expression of type pointer, dbx checks the data pointed to. If the data pointed to is a structure, dbx checks that structure. If you provide an expression that's not of type pointer, dbx evaluates the expression and uses the result as an address in memory. The breakpoint stops your program if the contents of the memory location (32 bits) has changed since the last time dbx checked it.

The points at which dbx checks the value of a variable or memory location depend on the command that you use to set the breakpoint:

stop (struct s*) 0x12345678

You can use fast watchpoints, also known as data breakpoints, with the stop command. A fast watchpoint watches a specified variable or memory address without severely impacting the performance of the program being debugged.

InIRIX 4 and earlier versions of dbx, the debugger had to single-step the process being debugged and check if the value of a variable had changed after each instruction. With fast watchpoints, the debugger uses a hardware virtual memory write protect mechanism to allow the program to run freely until the variable being watched changes. The program being debugged stops only when the virtual memory page containing the variable is written to. If the value of the variable being watched does not changed, dbx continues the execution of the process. If a write modifies a watched variable, dbx notifies you of the change.

Consider a small program that contains a global variable called global:

stop global

This command causes the program to stop if the value of the variable global changes. The program runs virtually at full speed until global gets assigned a new value. Similarly, consider the command:

stop 0x100100

This command stops when the 32- bit integer residing at address 0x100100 is modified, and runs at nearly full speed until the value changes. This form of the stop command is useful for watching the contents of anonymous memory, such as the memory returned by malloc().

dbx still needs to use the single-step approach if the stop command contains an expression to watch, such as in stop if global == 1. The performance of the debugged program can be greatly enhanced by including a variable to watch in the stop command.

For example, the previous stop command can be expressed equivalently as stop global if global == 1. This instructs the debugger to check only the expression global == 1 if the value of global changes. For situations where the expression does not depend upon a particular variable getting modified such as stop if global == x * 3, the single-step approach is the only way to achieve the desired behavior.

By including a test clause in your stop command, you can cause dbx to stop if the value of an expression is true. You can use any valid numerical expression as a test. If the result of the expression is nonzero, the expression is true and the test is successful.

The point at which dbx evaluates the test expression depends on the command that you use to set the breakpoint:

You can create conditional breakpoints that combine both variable and test clauses. In these cases, the overall test evaluates to true only if both clauses are true.

The following forms of the stop command combine both the variable and test clauses:

The cont command allows you to continue execution after any type of breakpoint. In its simplest form, program execution continues until the end of the program or until another breakpoint is reached. You can also tell dbx to continue your program until it reaches a given line or procedure; this is similar to setting a temporary, "one-shot" breakpoint and then continuing.

The syntax of the cont command is:

If your program stopped because dbx caught a signal intended for your program, then dbx will send that signal to your program when you continue execution. You can also explicitly send a signal to your program when you continue execution. Sending signals to your program upon continuation is discussed in "Continuing After Catching a Signal".

When you debug multiprocess programs, the resume command can be more helpful than the cont command. Refer to "Resuming a Suspended Process" for more information about the resume command.

The status command lists all of the breakpoints, traces, and conditional commands that you have set and indicates whether they are enabled or disabled.

For example, consider executing the following commands while debugging a program called test:

(dbx) stop in foo
Process     0: [3] stop in foo
(dbx) r
Process 22631 (test) started
[3] Process 22631 (test) stopped at [foo:38 ,0x10001050]
  38  r = foo2(i+1);
(dbx) trace total
Process 22631: [4] trace total in foo
(dbx) when at 60 {print i,j }
Process 22631: [5] when at "/usr/var/tmp/dbx_examples/test.c":60 { print i, j }

If you enter status, you see the following:

(dbx) status
Process 22631: [3] stop in foo
Process 22631: [4] trace total in foo
Process 22631: [5] when at "/usr/var/tmp/dbx_examples/test.c":60 { print i, j }

The disable command allows you to temporarily disable a breakpoint, trace, or conditional command so that it is inoperative and has no effect on program execution. dbx remembers all information about a disabled breakpoint, trace, or conditional command, and you may enable it using the enable command described in "Enabling Breakpoints, Traces, and Conditional Commands".

The syntax of the disable command is:

For example, to disable the conditional command set in "Listing Breakpoints, Traces, and Conditional Commands" enter:

(dbx) disable 4

If you enter status, you see the following:

(dbx) status
Process 22631: [3] stop in foo
Process 22631: [4] (disabled) trace total in foo
Process 22631: [5] when at "/usr/var/tmp/dbx_examples/test.c":60 { print i, j

The enable command reverses the effects of a disable command: The breakpoint, trace, or conditional command that you specify is enabled and once again affects the execution of your program. The syntax of the enable command is:

For example, to enable the conditional command disabled in "Disabling Breakpoints, Traces, and Conditional Commands" enter:

(dbx) enable 4

Executing the status command shows that the condition command is now enabled:

(dbx) status
Process 22631: [3] stop in foo
Process 22631: [4] trace total in foo
Process 22631: [5] when at "/usr/var/tmp/dbx_examples/test.c":60 { print i, j

The delete command allows you to delete breakpoints, traces, and conditional commands:

For example, to delete the breakpoint and trace set in "Listing Breakpoints, Traces, and Conditional Commands" enter:

(dbx) delete 3, 4

If you enter status, you see the following:

(dbx) status
Process 22631: [5] when at "/usr/var/tmp/dbx_examples/test.c":60 { print i, j }

To delete all breakpoints, traces, and conditional commands, enter:

(dbx) delete all

With the catch command, you can instruct dbx to stop your program when it receives any specified signal. The ignore command undoes the effects of a catch command.

The catch and ignore commands have the following syntax:

You can use the signal names and numbers as listed in the signal(2) reference page. You can also abbreviate the signal names by omitting the "SIG" portion of the name. You can use uppercase or lowercase for the signal names.

---

Note: Because "int" (in lowercase) is a dbx keyword, you cannot use it as an abbreviation for the SIGINT signal. You must use uppercase ("INT"), the full signal name ("SIGINT" or "sigint"), or the signal number ("2"). SIGINT is the only signal name with such a restriction.

---

If you instruct dbx to catch a signal, whenever that signal is directed to your program, dbx intercepts it and stops your program. Your program does not see this signal until you continue your program with the cont command. If your program has a handler for the signal, the signal is then passed to the program. If there is no handler for the signal, the program does not see the signal. You can suppress passing the signal to the program's signal handler by issuing a step or next command, rather than cont.

If you issue a SIGINT signal at the keyboard (usually by pressing <Ctrl-C>) while you are running an application under dbx, what happens depends on the circumstances:

The cont command allows you to continue execution after catching a signal. You can also use the cont command to specify a different signal to send to your program than the one that dbx caught. Using the same syntax, you can also send a signal to your program when you continue, even if your program did not stop because of a caught signal.

Use the following forms of the cont command when handling signals. In each case, if you do not provide a signal, but your program stopped because dbx caught a signal intended for your program, then dbx sends that signal to your program when you continue execution:

For example, if your program stopped because dbx caught a SIGINT signal, dbx will automatically send that signal to your program, if you enter:

(dbx) cont

Suppose you have a procedure called alarm_handler to handle an alarm signal sent to your program. If you want to test this procedure by single-stepping through it, you can execute the following command:

(dbx) cont SIGALRM in alarm_handler

This sets a temporary breakpoint to stop your program upon entering alarm_handler, continues execution of your program, and sends a SIGALRM signal to your program. Your program then enters the alarm_handler procedure and stops. You can then single-step through the procedure and observe execution.

The format of the step command is:

By default, step steps into only those procedures that are compiled with the debugging options -g, -g2, or -g3 for which line numbers are available in the symbol table. Note that this does not include standard library routines because they are not compiled using debugging options.

You can modify this behavior, even force dbx to step into procedures not compiled with full debugging information, by changing the value of the dbx variable $stepintoall.

Table 6-1 summarizes how the value of $stepintoall affects the step command.

If your program has DSOs, set the environment variable LD_BIND_NOW to 1 before you run your program. This will force complete run-time linking. Otherwise, you can accidentally step into the run-time-linker, rld(1), which becomes part of your program at run time. Useful stack traces are then impossible. To avoid this situation, enter the following before the run command:

(dbx) setenv LD_BIND_NOW 1 

The format of the next command is:

If you step into a procedure and then decide you don't want to step through the rest of it, use return to finish executing the procedure and return to the calling procedure.

The format of the return command is: