<HTML> <HEAD> <!-- This HTML file has been created by texi2html 1.51 from /mnt/apple/gdb/source/gdb.apple/source/gdb/gdb/doc/gdb.texinfo on 23 November 1999 --> <TITLE>Debugging with GDB - Stopping and Continuing</TITLE> </HEAD> <BODY> Go to the <A HREF="gdb_1.html">first</A>, <A HREF="gdb_5.html">previous</A>, <A HREF="gdb_7.html">next</A>, <A HREF="gdb_21.html">last</A> section, <A HREF="gdb_toc.html">table of contents</A>. <P><HR><P> <H1><A NAME="SEC27" HREF="gdb_toc.html#TOC27">Stopping and Continuing</A></H1> <P> The principal purposes of using a debugger are so that you can stop your program before it terminates; or so that, if your program runs into trouble, you can investigate and find out why. </P> <P> Inside GDB, your program may stop for any of several reasons, such as a signal, a breakpoint, or reaching a new line after a GDB command such as <CODE>step</CODE>. You may then examine and change variables, set new breakpoints or remove old ones, and then continue execution. Usually, the messages shown by GDB provide ample explanation of the status of your program--but you can also explicitly request this information at any time. </P> <DL COMPACT> <DT><CODE>info program</CODE> <DD> <A NAME="IDX90"></A> Display information about the status of your program: whether it is running or not, what process it is, and why it stopped. </DL> <H2><A NAME="SEC28" HREF="gdb_toc.html#TOC28">Breakpoints, watchpoints, and catchpoints</A></H2> <P> <A NAME="IDX91"></A> A <STRONG>breakpoint</STRONG> makes your program stop whenever a certain point in the program is reached. For each breakpoint, you can add conditions to control in finer detail whether your program stops. You can set breakpoints with the <CODE>break</CODE> command and its variants (see section <A HREF="gdb_6.html#SEC29">Setting breakpoints</A>), to specify the place where your program should stop by line number, function name or exact address in the program. </P> <P> In HP-UX, SunOS 4.x, SVR4, OpenStep, MacOS, and Alpha OSF/1 configurations, you can set breakpoints in shared libraries before the executable is run. There is a minor limitation on HP-UX systems: you must wait until the executable is run in order to set breakpoints in shared library routines that are not called directly by the program (for example, routines that are arguments in a <CODE>pthread_create</CODE> call). </P> <P> <A NAME="IDX92"></A> <A NAME="IDX93"></A> <A NAME="IDX94"></A> <A NAME="IDX95"></A> A <STRONG>watchpoint</STRONG> is a special breakpoint that stops your program when the value of an expression changes. You must use a different command to set watchpoints (see section <A HREF="gdb_6.html#SEC30">Setting watchpoints</A>), but aside from that, you can manage a watchpoint like any other breakpoint: you enable, disable, and delete both breakpoints and watchpoints using the same commands. </P> <P> You can arrange to have values from your program displayed automatically whenever GDB stops at a breakpoint. See section <A HREF="gdb_9.html#SEC57">Automatic display</A>. </P> <P> <A NAME="IDX96"></A> <A NAME="IDX97"></A> A <STRONG>catchpoint</STRONG> is another special breakpoint that stops your program when a certain kind of event occurs, such as the throwing of a C++ exception or the loading of a library. As with watchpoints, you use a different command to set a catchpoint (see section <A HREF="gdb_6.html#SEC31">Setting catchpoints</A>), but aside from that, you can manage a catchpoint like any other breakpoint. (To stop when your program receives a signal, use the <CODE>handle</CODE> command; see section <A HREF="gdb_6.html#SEC38">Signals</A>.) </P> <P> <A NAME="IDX98"></A> <A NAME="IDX99"></A> GDB assigns a number to each breakpoint, watchpoint, or catchpoint when you create it; these numbers are successive integers starting with one. In many of the commands for controlling various features of breakpoints you use the breakpoint number to say which breakpoint you want to change. Each breakpoint may be <STRONG>enabled</STRONG> or <STRONG>disabled</STRONG>; if disabled, it has no effect on your program until you enable it again. </P> <H3><A NAME="SEC29" HREF="gdb_toc.html#TOC29">Setting breakpoints</A></H3> <P> <A NAME="IDX100"></A> <A NAME="IDX101"></A> <A NAME="IDX102"></A> <A NAME="IDX103"></A> Breakpoints are set with the <CODE>break</CODE> command (abbreviated <CODE>b</CODE>). The debugger convenience variable <SAMP>`$bpnum'</SAMP> records the number of the breakpoints you've set most recently; see section <A HREF="gdb_9.html#SEC60">Convenience variables</A>, for a discussion of what you can do with convenience variables. </P> <P> You have several ways to say where the breakpoint should go. </P> <DL COMPACT> <DT><CODE>break <VAR>function</VAR></CODE> <DD> Set a breakpoint at entry to function <VAR>function</VAR>. When using source languages that permit overloading of symbols, such as C++, <VAR>function</VAR> may refer to more than one possible place to break. See section <A HREF="gdb_6.html#SEC36">Breakpoint menus</A>, for a discussion of that situation. <DT><CODE>break +<VAR>offset</VAR></CODE> <DD> <DT><CODE>break -<VAR>offset</VAR></CODE> <DD> Set a breakpoint some number of lines forward or back from the position at which execution stopped in the currently selected frame. <DT><CODE>break <VAR>linenum</VAR></CODE> <DD> Set a breakpoint at line <VAR>linenum</VAR> in the current source file. That file is the last file whose source text was printed. This breakpoint stops your program just before it executes any of the code on that line. <DT><CODE>break <VAR>filename</VAR>:<VAR>linenum</VAR></CODE> <DD> Set a breakpoint at line <VAR>linenum</VAR> in source file <VAR>filename</VAR>. <DT><CODE>break <VAR>filename</VAR>:<VAR>function</VAR></CODE> <DD> Set a breakpoint at entry to function <VAR>function</VAR> found in file <VAR>filename</VAR>. Specifying a file name as well as a function name is superfluous except when multiple files contain similarly named functions. <DT><CODE>break *<VAR>address</VAR></CODE> <DD> Set a breakpoint at address <VAR>address</VAR>. You can use this to set breakpoints in parts of your program which do not have debugging information or source files. <DT><CODE>break</CODE> <DD> When called without any arguments, <CODE>break</CODE> sets a breakpoint at the next instruction to be executed in the selected stack frame (see section <A HREF="gdb_7.html#SEC40">Examining the Stack</A>). In any selected frame but the innermost, this makes your program stop as soon as control returns to that frame. This is similar to the effect of a <CODE>finish</CODE> command in the frame inside the selected frame--except that <CODE>finish</CODE> does not leave an active breakpoint. If you use <CODE>break</CODE> without an argument in the innermost frame, GDB stops the next time it reaches the current location; this may be useful inside loops. GDB normally ignores breakpoints when it resumes execution, until at least one instruction has been executed. If it did not do this, you would be unable to proceed past a breakpoint without first disabling the breakpoint. This rule applies whether or not the breakpoint already existed when your program stopped. <DT><CODE>break ... if <VAR>cond</VAR></CODE> <DD> Set a breakpoint with condition <VAR>cond</VAR>; evaluate the expression <VAR>cond</VAR> each time the breakpoint is reached, and stop only if the value is nonzero--that is, if <VAR>cond</VAR> evaluates as true. <SAMP>`...'</SAMP> stands for one of the possible arguments described above (or no argument) specifying where to break. See section <A HREF="gdb_6.html#SEC34">Break conditions</A>, for more information on breakpoint conditions. <A NAME="IDX104"></A> <DT><CODE>tbreak <VAR>args</VAR></CODE> <DD> Set a breakpoint enabled only for one stop. <VAR>args</VAR> are the same as for the <CODE>break</CODE> command, and the breakpoint is set in the same way, but the breakpoint is automatically deleted after the first time your program stops there. See section <A HREF="gdb_6.html#SEC33">Disabling breakpoints</A>. <A NAME="IDX105"></A> <DT><CODE>hbreak <VAR>args</VAR></CODE> <DD> Set a hardware-assisted breakpoint. <VAR>args</VAR> are the same as for the <CODE>break</CODE> command and the breakpoint is set in the same way, but the breakpoint requires hardware support and some target hardware may not have this support. The main purpose of this is EPROM/ROM code debugging, so you can set a breakpoint at an instruction without changing the instruction. This can be used with the new trap-generation provided by SPARClite DSU. DSU will generate traps when a program accesses some data or instruction address that is assigned to the debug registers. However the hardware breakpoint registers can only take two data breakpoints, and GDB will reject this command if more than two are used. Delete or disable unused hardware breakpoints before setting new ones. See section <A HREF="gdb_6.html#SEC34">Break conditions</A>. <A NAME="IDX106"></A> <DT><CODE>thbreak <VAR>args</VAR></CODE> <DD> Set a hardware-assisted breakpoint enabled only for one stop. <VAR>args</VAR> are the same as for the <CODE>hbreak</CODE> command and the breakpoint is set in the same way. However, like the <CODE>tbreak</CODE> command, the breakpoint is automatically deleted after the first time your program stops there. Also, like the <CODE>hbreak</CODE> command, the breakpoint requires hardware support and some target hardware may not have this support. See section <A HREF="gdb_6.html#SEC33">Disabling breakpoints</A>. Also See section <A HREF="gdb_6.html#SEC34">Break conditions</A>. <A NAME="IDX107"></A> <A NAME="IDX108"></A> <DT><CODE>rbreak <VAR>regex</VAR></CODE> <DD> Set breakpoints on all functions matching the regular expression <VAR>regex</VAR>. This command sets an unconditional breakpoint on all matches, printing a list of all breakpoints it set. Once these breakpoints are set, they are treated just like the breakpoints set with the <CODE>break</CODE> command. You can delete them, disable them, or make them conditional the same way as any other breakpoint. When debugging C++ programs, <CODE>rbreak</CODE> is useful for setting breakpoints on overloaded functions that are not members of any special classes. <A NAME="IDX109"></A> <A NAME="IDX110"></A> <DT><CODE>info breakpoints [<VAR>n</VAR>]</CODE> <DD> <DT><CODE>info break [<VAR>n</VAR>]</CODE> <DD> <DT><CODE>info watchpoints [<VAR>n</VAR>]</CODE> <DD> Print a table of all breakpoints, watchpoints, and catchpoints set and not deleted, with the following columns for each breakpoint: <DL COMPACT> <DT><EM>Breakpoint Numbers</EM> <DD> <DT><EM>Type</EM> <DD> Breakpoint, watchpoint, or catchpoint. <DT><EM>Disposition</EM> <DD> Whether the breakpoint is marked to be disabled or deleted when hit. <DT><EM>Enabled or Disabled</EM> <DD> Enabled breakpoints are marked with <SAMP>`y'</SAMP>. <SAMP>`n'</SAMP> marks breakpoints that are not enabled. <DT><EM>Address</EM> <DD> Where the breakpoint is in your program, as a memory address <DT><EM>What</EM> <DD> Where the breakpoint is in the source for your program, as a file and line number. </DL> If a breakpoint is conditional, <CODE>info break</CODE> shows the condition on the line following the affected breakpoint; breakpoint commands, if any, are listed after that. <CODE>info breakpoints</CODE> with a breakpoint number <VAR>n</VAR> as argument lists only that breakpoint. The convenience variable <CODE>$_</CODE> and the default examining-address for the <CODE>x</CODE> command are set to the address of the last breakpoint listed (see section <A HREF="gdb_9.html#SEC56">Examining memory</A>). <CODE>info breakpoints</CODE> displays a count of the number of times the breakpoint has been hit. This is especially useful in conjunction with the <CODE>ignore</CODE> command. You can ignore a large number of breakpoint hits, look at the breakpoint info to see how many times the breakpoint was hit, and then run again, ignoring one less than that number. This will get you quickly to the last hit of that breakpoint. </DL> <P> GDB allows you to set any number of breakpoints at the same place in your program. There is nothing silly or meaningless about this. When the breakpoints are conditional, this is even useful (see section <A HREF="gdb_6.html#SEC34">Break conditions</A>). </P> <P> <A NAME="IDX111"></A> <A NAME="IDX112"></A> GDB itself sometimes sets breakpoints in your program for special purposes, such as proper handling of <CODE>longjmp</CODE> (in C programs). These internal breakpoints are assigned negative numbers, starting with <CODE>-1</CODE>; <SAMP>`info breakpoints'</SAMP> does not display them. </P> <P> You can see these breakpoints with the GDB maintenance command <SAMP>`maint info breakpoints'</SAMP>. </P> <DL COMPACT> <DT><CODE>maint info breakpoints</CODE> <DD> <A NAME="IDX113"></A> Using the same format as <SAMP>`info breakpoints'</SAMP>, display both the breakpoints you've set explicitly, and those GDB is using for internal purposes. Internal breakpoints are shown with negative breakpoint numbers. The type column identifies what kind of breakpoint is shown: <DL COMPACT> <DT><CODE>breakpoint</CODE> <DD> Normal, explicitly set breakpoint. <DT><CODE>watchpoint</CODE> <DD> Normal, explicitly set watchpoint. <DT><CODE>longjmp</CODE> <DD> Internal breakpoint, used to handle correctly stepping through <CODE>longjmp</CODE> calls. <DT><CODE>longjmp resume</CODE> <DD> Internal breakpoint at the target of a <CODE>longjmp</CODE>. <DT><CODE>until</CODE> <DD> Temporary internal breakpoint used by the GDB <CODE>until</CODE> command. <DT><CODE>finish</CODE> <DD> Temporary internal breakpoint used by the GDB <CODE>finish</CODE> command. </DL> </DL> <H3><A NAME="SEC30" HREF="gdb_toc.html#TOC30">Setting watchpoints</A></H3> <P> <A NAME="IDX114"></A> <A NAME="IDX115"></A> <A NAME="IDX116"></A> You can use a watchpoint to stop execution whenever the value of an expression changes, without having to predict a particular place where this may happen. </P> <P> Depending on your system, watchpoints may be implemented in software or hardware. GDB does software watchpointing by single-stepping your program and testing the variable's value each time, which is hundreds of times slower than normal execution. (But this may still be worth it, to catch errors where you have no clue what part of your program is the culprit.) </P> <P> On some systems, such as HP-UX and Linux, GDB includes support for hardware watchpoints, which do not slow down the running of your program. </P> <DL COMPACT> <DT><CODE>watch <VAR>expr</VAR></CODE> <DD> <A NAME="IDX117"></A> Set a watchpoint for an expression. GDB will break when <VAR>expr</VAR> is written into by the program and its value changes. <A NAME="IDX118"></A> <DT><CODE>rwatch <VAR>expr</VAR></CODE> <DD> Set a watchpoint that will break when watch <VAR>expr</VAR> is read by the program. If you use both watchpoints, both must be set with the <CODE>rwatch</CODE> command. <A NAME="IDX119"></A> <DT><CODE>awatch <VAR>expr</VAR></CODE> <DD> Set a watchpoint that will break when <VAR>args</VAR> is read and written into by the program. If you use both watchpoints, both must be set with the <CODE>awatch</CODE> command. <A NAME="IDX120"></A> <DT><CODE>info watchpoints</CODE> <DD> This command prints a list of watchpoints, breakpoints, and catchpoints; it is the same as <CODE>info break</CODE>. </DL> <P> GDB sets a <STRONG>hardware watchpoint</STRONG> if possible. Hardware watchpoints execute very quickly, and the debugger reports a change in value at the exact instruction where the change occurs. If GDB cannot set a hardware watchpoint, it sets a software watchpoint, which executes more slowly and reports the change in value at the next statement, not the instruction, after the change occurs. </P> <P> When you issue the <CODE>watch</CODE> command, GDB reports </P> <PRE> Hardware watchpoint <VAR>num</VAR>: <VAR>expr</VAR> </PRE> <P> if it was able to set a hardware watchpoint. </P> <P> The SPARClite DSU will generate traps when a program accesses some data or instruction address that is assigned to the debug registers. For the data addresses, DSU facilitates the <CODE>watch</CODE> command. However the hardware breakpoint registers can only take two data watchpoints, and both watchpoints must be the same kind. For example, you can set two watchpoints with <CODE>watch</CODE> commands, two with <CODE>rwatch</CODE> commands, <STRONG>or</STRONG> two with <CODE>awatch</CODE> commands, but you cannot set one watchpoint with one command and the other with a different command. GDB will reject the command if you try to mix watchpoints. Delete or disable unused watchpoint commands before setting new ones. </P> <P> If you call a function interactively using <CODE>print</CODE> or <CODE>call</CODE>, any watchpoints you have set will be inactive until GDB reaches another kind of breakpoint or the call completes. </P> <BLOCKQUOTE> <A NAME="IDX121"></A> <A NAME="IDX122"></A> <P> <EM>Warning:</EM> In multi-thread programs, watchpoints have only limited usefulness. With the current watchpoint implementation, GDB can only watch the value of an expression <EM>in a single thread</EM>. If you are confident that the expression can only change due to the current thread's activity (and if you are also confident that no other thread can become current), then you can use watchpoints as usual. However, GDB may not notice when a non-current thread's activity changes the expression. </BLOCKQUOTE> <H3><A NAME="SEC31" HREF="gdb_toc.html#TOC31">Setting catchpoints</A></H3> <P> <A NAME="IDX123"></A> <A NAME="IDX124"></A> <A NAME="IDX125"></A> </P> <P> You can use <STRONG>catchpoints</STRONG> to cause the debugger to stop for certain kinds of program events, such as C++ exceptions or the loading of a shared library. Use the <CODE>catch</CODE> command to set a catchpoint. </P> <DL COMPACT> <DT><CODE>catch <VAR>event</VAR></CODE> <DD> <A NAME="IDX126"></A> Stop when <VAR>event</VAR> occurs. <VAR>event</VAR> can be any of the following: <DL COMPACT> <DT><CODE>throw</CODE> <DD> <A NAME="IDX127"></A> The throwing of a C++ exception. <DT><CODE>catch</CODE> <DD> <A NAME="IDX128"></A> The catching of a C++ exception. <DT><CODE>exec</CODE> <DD> <A NAME="IDX129"></A> A call to <CODE>exec</CODE>. This is currently only available for HP-UX. <DT><CODE>fork</CODE> <DD> <A NAME="IDX130"></A> A call to <CODE>fork</CODE>. This is currently only available for HP-UX. <DT><CODE>vfork</CODE> <DD> <A NAME="IDX131"></A> A call to <CODE>vfork</CODE>. This is currently only available for HP-UX. <DT><CODE>load</CODE> <DD> <DT><CODE>load <VAR>libname</VAR></CODE> <DD> <A NAME="IDX132"></A> The dynamic loading of any shared library, or the loading of the library <VAR>libname</VAR>. This is currently only available for HP-UX. <DT><CODE>unload</CODE> <DD> <DT><CODE>unload <VAR>libname</VAR></CODE> <DD> <A NAME="IDX133"></A> The unloading of any dynamically loaded shared library, or the unloading of the library <VAR>libname</VAR>. This is currently only available for HP-UX. </DL> <DT><CODE>tcatch <VAR>event</VAR></CODE> <DD> Set a catchpoint that is enabled only for one stop. The catchpoint is automatically deleted after the first time the event is caught. </DL> <P> Use the <CODE>info break</CODE> command to list the current catchpoints. </P> <P> There are currently some limitations to C++ exception handling (<CODE>catch throw</CODE> and <CODE>catch catch</CODE>) in GDB: </P> <UL> <LI> If you call a function interactively, GDB normally returns control to you when the function has finished executing. If the call raises an exception, however, the call may bypass the mechanism that returns control to you and cause your program either to abort or to simply continue running until it hits a breakpoint, catches a signal that GDB is listening for, or exits. This is the case even if you set a catchpoint for the exception; catchpoints on exceptions are disabled within interactive calls. <LI> You cannot raise an exception interactively. <LI> You cannot install an exception handler interactively. </UL> <P> <A NAME="IDX134"></A> Sometimes <CODE>catch</CODE> is not the best way to debug exception handling: if you need to know exactly where an exception is raised, it is better to stop <EM>before</EM> the exception handler is called, since that way you can see the stack before any unwinding takes place. If you set a breakpoint in an exception handler instead, it may not be easy to find out where the exception was raised. </P> <P> To stop just before an exception handler is called, you need some knowledge of the implementation. In the case of GNU C++, exceptions are raised by calling a library function named <CODE>__raise_exception</CODE> which has the following ANSI C interface: </P> <PRE> /* <VAR>addr</VAR> is where the exception identifier is stored. ID is the exception identifier. */ void __raise_exception (void **<VAR>addr</VAR>, void *<VAR>id</VAR>); </PRE> <P> To make the debugger catch all exceptions before any stack unwinding takes place, set a breakpoint on <CODE>__raise_exception</CODE> (see section <A HREF="gdb_6.html#SEC28">Breakpoints, watchpoints, and catchpoints</A>). </P> <P> With a conditional breakpoint (see section <A HREF="gdb_6.html#SEC34">Break conditions</A>) that depends on the value of <VAR>id</VAR>, you can stop your program when a specific exception is raised. You can use multiple conditional breakpoints to stop your program when any of a number of exceptions are raised. </P> <H3><A NAME="SEC32" HREF="gdb_toc.html#TOC32">Deleting breakpoints</A></H3> <P> <A NAME="IDX135"></A> <A NAME="IDX136"></A> It is often necessary to eliminate a breakpoint, watchpoint, or catchpoint once it has done its job and you no longer want your program to stop there. This is called <STRONG>deleting</STRONG> the breakpoint. A breakpoint that has been deleted no longer exists; it is forgotten. </P> <P> With the <CODE>clear</CODE> command you can delete breakpoints according to where they are in your program. With the <CODE>delete</CODE> command you can delete individual breakpoints, watchpoints, or catchpoints by specifying their breakpoint numbers. </P> <P> It is not necessary to delete a breakpoint to proceed past it. GDB automatically ignores breakpoints on the first instruction to be executed when you continue execution without changing the execution address. </P> <DL COMPACT> <DT><CODE>clear</CODE> <DD> <A NAME="IDX137"></A> Delete any breakpoints at the next instruction to be executed in the selected stack frame (see section <A HREF="gdb_7.html#SEC43">Selecting a frame</A>). When the innermost frame is selected, this is a good way to delete a breakpoint where your program just stopped. <DT><CODE>clear <VAR>function</VAR></CODE> <DD> <DT><CODE>clear <VAR>filename</VAR>:<VAR>function</VAR></CODE> <DD> Delete any breakpoints set at entry to the function <VAR>function</VAR>. <DT><CODE>clear <VAR>linenum</VAR></CODE> <DD> <DT><CODE>clear <VAR>filename</VAR>:<VAR>linenum</VAR></CODE> <DD> Delete any breakpoints set at or within the code of the specified line. <A NAME="IDX138"></A> <A NAME="IDX139"></A> <A NAME="IDX140"></A> <DT><CODE>delete [breakpoints] [<VAR>bnums</VAR>...]</CODE> <DD> Delete the breakpoints, watchpoints, or catchpoints of the numbers specified as arguments. If no argument is specified, delete all breakpoints (GDB asks confirmation, unless you have <CODE>set confirm off</CODE>). You can abbreviate this command as <CODE>d</CODE>. </DL> <H3><A NAME="SEC33" HREF="gdb_toc.html#TOC33">Disabling breakpoints</A></H3> <P> <A NAME="IDX141"></A> <A NAME="IDX142"></A> Rather than deleting a breakpoint, watchpoint, or catchpoint, you might prefer to <STRONG>disable</STRONG> it. This makes the breakpoint inoperative as if it had been deleted, but remembers the information on the breakpoint so that you can <STRONG>enable</STRONG> it again later. </P> <P> You disable and enable breakpoints, watchpoints, and catchpoints with the <CODE>enable</CODE> and <CODE>disable</CODE> commands, optionally specifying one or more breakpoint numbers as arguments. Use <CODE>info break</CODE> or <CODE>info watch</CODE> to print a list of breakpoints, watchpoints, and catchpoints if you do not know which numbers to use. </P> <P> A breakpoint, watchpoint, or catchpoint can have any of four different states of enablement: </P> <UL> <LI> Enabled. The breakpoint stops your program. A breakpoint set with the <CODE>break</CODE> command starts out in this state. <LI> Disabled. The breakpoint has no effect on your program. <LI> Enabled once. The breakpoint stops your program, but then becomes disabled. A breakpoint set with the <CODE>tbreak</CODE> command starts out in this state. <LI> Enabled for deletion. The breakpoint stops your program, but immediately after it does so it is deleted permanently. </UL> <P> You can use the following commands to enable or disable breakpoints, watchpoints, and catchpoints: </P> <DL COMPACT> <DT><CODE>disable [breakpoints] [<VAR>bnums</VAR>...]</CODE> <DD> <A NAME="IDX143"></A> <A NAME="IDX144"></A> <A NAME="IDX145"></A> Disable the specified breakpoints--or all breakpoints, if none are listed. A disabled breakpoint has no effect but is not forgotten. All options such as ignore-counts, conditions and commands are remembered in case the breakpoint is enabled again later. You may abbreviate <CODE>disable</CODE> as <CODE>dis</CODE>. <A NAME="IDX146"></A> <A NAME="IDX147"></A> <DT><CODE>enable [breakpoints] [<VAR>bnums</VAR>...]</CODE> <DD> Enable the specified breakpoints (or all defined breakpoints). They become effective once again in stopping your program. <DT><CODE>enable [breakpoints] once <VAR>bnums</VAR>...</CODE> <DD> Enable the specified breakpoints temporarily. GDB disables any of these breakpoints immediately after stopping your program. <DT><CODE>enable [breakpoints] delete <VAR>bnums</VAR>...</CODE> <DD> Enable the specified breakpoints to work once, then die. GDB deletes any of these breakpoints as soon as your program stops there. </DL> <P> Except for a breakpoint set with <CODE>tbreak</CODE> (see section <A HREF="gdb_6.html#SEC29">Setting breakpoints</A>), breakpoints that you set are initially enabled; subsequently, they become disabled or enabled only when you use one of the commands above. (The command <CODE>until</CODE> can set and delete a breakpoint of its own, but it does not change the state of your other breakpoints; see section <A HREF="gdb_6.html#SEC37">Continuing and stepping</A>.) </P> <H3><A NAME="SEC34" HREF="gdb_toc.html#TOC34">Break conditions</A></H3> <P> <A NAME="IDX148"></A> <A NAME="IDX149"></A> </P> <P> The simplest sort of breakpoint breaks every time your program reaches a specified place. You can also specify a <STRONG>condition</STRONG> for a breakpoint. A condition is just a Boolean expression in your programming language (see section <A HREF="gdb_9.html#SEC52">Expressions</A>). A breakpoint with a condition evaluates the expression each time your program reaches it, and your program stops only if the condition is <EM>true</EM>. </P> <P> This is the converse of using assertions for program validation; in that situation, you want to stop when the assertion is violated--that is, when the condition is false. In C, if you want to test an assertion expressed by the condition <VAR>assert</VAR>, you should set the condition <SAMP>`! <VAR>assert</VAR>'</SAMP> on the appropriate breakpoint. </P> <P> Conditions are also accepted for watchpoints; you may not need them, since a watchpoint is inspecting the value of an expression anyhow--but it might be simpler, say, to just set a watchpoint on a variable name, and specify a condition that tests whether the new value is an interesting one. </P> <P> Break conditions can have side effects, and may even call functions in your program. This can be useful, for example, to activate functions that log program progress, or to use your own print functions to format special data structures. The effects are completely predictable unless there is another enabled breakpoint at the same address. (In that case, GDB might see the other breakpoint first and stop your program without checking the condition of this one.) Note that breakpoint commands are usually more convenient and flexible for the purpose of performing side effects when a breakpoint is reached (see section <A HREF="gdb_6.html#SEC35">Breakpoint command lists</A>). </P> <P> Break conditions can be specified when a breakpoint is set, by using <SAMP>`if'</SAMP> in the arguments to the <CODE>break</CODE> command. See section <A HREF="gdb_6.html#SEC29">Setting breakpoints</A>. They can also be changed at any time with the <CODE>condition</CODE> command. The <CODE>watch</CODE> command does not recognize the <CODE>if</CODE> keyword; <CODE>condition</CODE> is the only way to impose a further condition on a watchpoint. </P> <DL COMPACT> <DT><CODE>condition <VAR>bnum</VAR> <VAR>expression</VAR></CODE> <DD> <A NAME="IDX150"></A> Specify <VAR>expression</VAR> as the break condition for breakpoint, watchpoint, or catchpoint number <VAR>bnum</VAR>. After you set a condition, breakpoint <VAR>bnum</VAR> stops your program only if the value of <VAR>expression</VAR> is true (nonzero, in C). When you use <CODE>condition</CODE>, GDB checks <VAR>expression</VAR> immediately for syntactic correctness, and to determine whether symbols in it have referents in the context of your breakpoint. GDB does not actually evaluate <VAR>expression</VAR> at the time the <CODE>condition</CODE> command is given, however. See section <A HREF="gdb_9.html#SEC52">Expressions</A>. <DT><CODE>condition <VAR>bnum</VAR></CODE> <DD> Remove the condition from breakpoint number <VAR>bnum</VAR>. It becomes an ordinary unconditional breakpoint. </DL> <P> <A NAME="IDX151"></A> A special case of a breakpoint condition is to stop only when the breakpoint has been reached a certain number of times. This is so useful that there is a special way to do it, using the <STRONG>ignore count</STRONG> of the breakpoint. Every breakpoint has an ignore count, which is an integer. Most of the time, the ignore count is zero, and therefore has no effect. But if your program reaches a breakpoint whose ignore count is positive, then instead of stopping, it just decrements the ignore count by one and continues. As a result, if the ignore count value is <VAR>n</VAR>, the breakpoint does not stop the next <VAR>n</VAR> times your program reaches it. </P> <DL COMPACT> <DT><CODE>ignore <VAR>bnum</VAR> <VAR>count</VAR></CODE> <DD> <A NAME="IDX152"></A> Set the ignore count of breakpoint number <VAR>bnum</VAR> to <VAR>count</VAR>. The next <VAR>count</VAR> times the breakpoint is reached, your program's execution does not stop; other than to decrement the ignore count, GDB takes no action. To make the breakpoint stop the next time it is reached, specify a count of zero. When you use <CODE>continue</CODE> to resume execution of your program from a breakpoint, you can specify an ignore count directly as an argument to <CODE>continue</CODE>, rather than using <CODE>ignore</CODE>. See section <A HREF="gdb_6.html#SEC37">Continuing and stepping</A>. If a breakpoint has a positive ignore count and a condition, the condition is not checked. Once the ignore count reaches zero, GDB resumes checking the condition. You could achieve the effect of the ignore count with a condition such as <SAMP>`$foo-- <= 0'</SAMP> using a debugger convenience variable that is decremented each time. See section <A HREF="gdb_9.html#SEC60">Convenience variables</A>. </DL> <P> Ignore counts apply to breakpoints, watchpoints, and catchpoints. </P> <H3><A NAME="SEC35" HREF="gdb_toc.html#TOC35">Breakpoint command lists</A></H3> <P> <A NAME="IDX153"></A> You can give any breakpoint (or watchpoint or catchpoint) a series of commands to execute when your program stops due to that breakpoint. For example, you might want to print the values of certain expressions, or enable other breakpoints. </P> <DL COMPACT> <DT><CODE>commands [<VAR>bnum</VAR>]</CODE> <DD> <A NAME="IDX154"></A> <A NAME="IDX155"></A> <DT><CODE>... <VAR>command-list</VAR> ...</CODE> <DD> <DT><CODE>end</CODE> <DD> Specify a list of commands for breakpoint number <VAR>bnum</VAR>. The commands themselves appear on the following lines. Type a line containing just <CODE>end</CODE> to terminate the commands. To remove all commands from a breakpoint, type <CODE>commands</CODE> and follow it immediately with <CODE>end</CODE>; that is, give no commands. With no <VAR>bnum</VAR> argument, <CODE>commands</CODE> refers to the last breakpoint, watchpoint, or catchpoint set (not to the breakpoint most recently encountered). </DL> <P> Pressing <KBD>RET</KBD> as a means of repeating the last GDB command is disabled within a <VAR>command-list</VAR>. </P> <P> You can use breakpoint commands to start your program up again. Simply use the <CODE>continue</CODE> command, or <CODE>step</CODE>, or any other command that resumes execution. </P> <P> Any other commands in the command list, after a command that resumes execution, are ignored. This is because any time you resume execution (even with a simple <CODE>next</CODE> or <CODE>step</CODE>), you may encounter another breakpoint--which could have its own command list, leading to ambiguities about which list to execute. </P> <P> <A NAME="IDX156"></A> If the first command you specify in a command list is <CODE>silent</CODE>, the usual message about stopping at a breakpoint is not printed. This may be desirable for breakpoints that are to print a specific message and then continue. If none of the remaining commands print anything, you see no sign that the breakpoint was reached. <CODE>silent</CODE> is meaningful only at the beginning of a breakpoint command list. </P> <P> The commands <CODE>echo</CODE>, <CODE>output</CODE>, and <CODE>printf</CODE> allow you to print precisely controlled output, and are often useful in silent breakpoints. See section <A HREF="gdb_16.html#SEC160">Commands for controlled output</A>. </P> <P> For example, here is how you could use breakpoint commands to print the value of <CODE>x</CODE> at entry to <CODE>foo</CODE> whenever <CODE>x</CODE> is positive. </P> <PRE> break foo if x>0 commands silent printf "x is %d\n",x cont end </PRE> <P> One application for breakpoint commands is to compensate for one bug so you can test for another. Put a breakpoint just after the erroneous line of code, give it a condition to detect the case in which something erroneous has been done, and give it commands to assign correct values to any variables that need them. End with the <CODE>continue</CODE> command so that your program does not stop, and start with the <CODE>silent</CODE> command so that no output is produced. Here is an example: </P> <PRE> break 403 commands silent set x = y + 4 cont end </PRE> <H3><A NAME="SEC36" HREF="gdb_toc.html#TOC36">Breakpoint menus</A></H3> <P> <A NAME="IDX157"></A> <A NAME="IDX158"></A> </P> <P> Some programming languages (such as C++ or Objective-C) permit a single function name to be defined several times, for application in different contexts. This is called <STRONG>overloading</STRONG>. When a function name is overloaded, <SAMP>`break <VAR>function</VAR>'</SAMP> is not enough to tell GDB where you want a breakpoint. If you realize this is a problem, you can use something like <SAMP>`break <VAR>function</VAR>(<VAR>types</VAR>)'</SAMP> to specify which particular version of the function you want. Otherwise, GDB offers you a menu of numbered choices for different possible breakpoints, and waits for your selection with the prompt <SAMP>`>'</SAMP>. The first two options are always <SAMP>`[0] cancel'</SAMP> and <SAMP>`[1] all'</SAMP>. Typing <KBD>1</KBD> sets a breakpoint at each definition of <VAR>function</VAR>, and typing <KBD>0</KBD> aborts the <CODE>break</CODE> command without setting any new breakpoints. </P> <P> For example, the following session excerpt shows an attempt to set a breakpoint at the overloaded symbol <CODE>String::after</CODE>. We choose three particular definitions of that function name: </P> <PRE> (gdb) b String::after [0] cancel [1] all [2] file:String.cc; line number:867 [3] file:String.cc; line number:860 [4] file:String.cc; line number:875 [5] file:String.cc; line number:853 [6] file:String.cc; line number:846 [7] file:String.cc; line number:735 > 2 4 6 Breakpoint 1 at 0xb26c: file String.cc, line 867. Breakpoint 2 at 0xb344: file String.cc, line 875. Breakpoint 3 at 0xafcc: file String.cc, line 846. Multiple breakpoints were set. Use the "delete" command to delete unwanted breakpoints. (gdb) </PRE> <H2><A NAME="SEC37" HREF="gdb_toc.html#TOC37">Continuing and stepping</A></H2> <P> <A NAME="IDX159"></A> <A NAME="IDX160"></A> <A NAME="IDX161"></A> <STRONG>Continuing</STRONG> means resuming program execution until your program completes normally. In contrast, <STRONG>stepping</STRONG> means executing just one more "step" of your program, where "step" may mean either one line of source code, or one machine instruction (depending on what particular command you use). Either when continuing or when stepping, your program may stop even sooner, due to a breakpoint or a signal. (If due to a signal, you may want to use <CODE>handle</CODE>, or use <SAMP>`signal 0'</SAMP> to resume execution. See section <A HREF="gdb_6.html#SEC38">Signals</A>.) </P> <DL COMPACT> <DT><CODE>continue [<VAR>ignore-count</VAR>]</CODE> <DD> <A NAME="IDX162"></A> <A NAME="IDX163"></A> <A NAME="IDX164"></A> <DT><CODE>c [<VAR>ignore-count</VAR>]</CODE> <DD> <DT><CODE>fg [<VAR>ignore-count</VAR>]</CODE> <DD> Resume program execution, at the address where your program last stopped; any breakpoints set at that address are bypassed. The optional argument <VAR>ignore-count</VAR> allows you to specify a further number of times to ignore a breakpoint at this location; its effect is like that of <CODE>ignore</CODE> (see section <A HREF="gdb_6.html#SEC34">Break conditions</A>). The argument <VAR>ignore-count</VAR> is meaningful only when your program stopped due to a breakpoint. At other times, the argument to <CODE>continue</CODE> is ignored. The synonyms <CODE>c</CODE> and <CODE>fg</CODE> are provided purely for convenience, and have exactly the same behavior as <CODE>continue</CODE>. </DL> <P> To resume execution at a different place, you can use <CODE>return</CODE> (see section <A HREF="gdb_12.html#SEC106">Returning from a function</A>) to go back to the calling function; or <CODE>jump</CODE> (see section <A HREF="gdb_12.html#SEC104">Continuing at a different address</A>) to go to an arbitrary location in your program. </P> <P> A typical technique for using stepping is to set a breakpoint (see section <A HREF="gdb_6.html#SEC28">Breakpoints, watchpoints, and catchpoints</A>) at the beginning of the function or the section of your program where a problem is believed to lie, run your program until it stops at that breakpoint, and then step through the suspect area, examining the variables that are interesting, until you see the problem happen. </P> <DL COMPACT> <DT><CODE>step</CODE> <DD> <A NAME="IDX165"></A> <A NAME="IDX166"></A> Continue running your program until control reaches a different source line, then stop it and return control to GDB. This command is abbreviated <CODE>s</CODE>. <BLOCKQUOTE> <P> <EM>Warning:</EM> If you use the <CODE>step</CODE> command while control is within a function that was compiled without debugging information, execution proceeds until control reaches a function that does have debugging information. Likewise, it will not step into a function which is compiled without debugging information. To step through functions without debugging information, use the <CODE>stepi</CODE> command, described below. </BLOCKQUOTE> The <CODE>step</CODE> command now only stops at the first instruction of a source line. This prevents the multiple stops that used to occur in switch statements, for loops, etc. <CODE>step</CODE> continues to stop if a function that has debugging information is called within the line. Also, the <CODE>step</CODE> command now only enters a subroutine if there is line number information for the subroutine. Otherwise it acts like the <CODE>next</CODE> command. This avoids problems when using <CODE>cc -gl</CODE> on MIPS machines. Previously, <CODE>step</CODE> entered subroutines if there was any debugging information about the routine. <DT><CODE>step <VAR>count</VAR></CODE> <DD> Continue running as in <CODE>step</CODE>, but do so <VAR>count</VAR> times. If a breakpoint is reached, or a signal not related to stepping occurs before <VAR>count</VAR> steps, stepping stops right away. <A NAME="IDX167"></A> <A NAME="IDX168"></A> <DT><CODE>next [<VAR>count</VAR>]</CODE> <DD> Continue to the next source line in the current (innermost) stack frame. This is similar to <CODE>step</CODE>, but function calls that appear within the line of code are executed without stopping. Execution stops when control reaches a different line of code at the original stack level that was executing when you gave the <CODE>next</CODE> command. This command is abbreviated <CODE>n</CODE>. An argument <VAR>count</VAR> is a repeat count, as for <CODE>step</CODE>. The <CODE>next</CODE> command now only stops at the first instruction of a source line. This prevents the multiple stops that used to occur in switch statements, for loops, etc. <A NAME="IDX169"></A> <DT><CODE>finish</CODE> <DD> Continue running until just after function in the selected stack frame returns. Print the returned value (if any). Contrast this with the <CODE>return</CODE> command (see section <A HREF="gdb_12.html#SEC106">Returning from a function</A>). <A NAME="IDX170"></A> <A NAME="IDX171"></A> <DT><CODE>until</CODE> <DD> <DT><CODE>u</CODE> <DD> Continue running until a source line past the current line, in the current stack frame, is reached. This command is used to avoid single stepping through a loop more than once. It is like the <CODE>next</CODE> command, except that when <CODE>until</CODE> encounters a jump, it automatically continues execution until the program counter is greater than the address of the jump. This means that when you reach the end of a loop after single stepping though it, <CODE>until</CODE> makes your program continue execution until it exits the loop. In contrast, a <CODE>next</CODE> command at the end of a loop simply steps back to the beginning of the loop, which forces you to step through the next iteration. <CODE>until</CODE> always stops your program if it attempts to exit the current stack frame. <CODE>until</CODE> may produce somewhat counterintuitive results if the order of machine code does not match the order of the source lines. For example, in the following excerpt from a debugging session, the <CODE>f</CODE> (<CODE>frame</CODE>) command shows that execution is stopped at line <CODE>206</CODE>; yet when we use <CODE>until</CODE>, we get to line <CODE>195</CODE>: <PRE> (gdb) f #0 main (argc=4, argv=0xf7fffae8) at m4.c:206 206 expand_input(); (gdb) until 195 for ( ; argc > 0; NEXTARG) { </PRE> This happened because, for execution efficiency, the compiler had generated code for the loop closure test at the end, rather than the start, of the loop--even though the test in a C <CODE>for</CODE>-loop is written before the body of the loop. The <CODE>until</CODE> command appeared to step back to the beginning of the loop when it advanced to this expression; however, it has not really gone to an earlier statement--not in terms of the actual machine code. <CODE>until</CODE> with no argument works by means of single instruction stepping, and hence is slower than <CODE>until</CODE> with an argument. <DT><CODE>until <VAR>location</VAR></CODE> <DD> <DT><CODE>u <VAR>location</VAR></CODE> <DD> Continue running your program until either the specified location is reached, or the current stack frame returns. <VAR>location</VAR> is any of the forms of argument acceptable to <CODE>break</CODE> (see section <A HREF="gdb_6.html#SEC29">Setting breakpoints</A>). This form of the command uses breakpoints, and hence is quicker than <CODE>until</CODE> without an argument. <A NAME="IDX172"></A> <A NAME="IDX173"></A> <DT><CODE>stepi</CODE> <DD> <DT><CODE>si</CODE> <DD> Execute one machine instruction, then stop and return to the debugger. It is often useful to do <SAMP>`display/i $pc'</SAMP> when stepping by machine instructions. This makes GDB automatically display the next instruction to be executed, each time your program stops. See section <A HREF="gdb_9.html#SEC57">Automatic display</A>. An argument is a repeat count, as in <CODE>step</CODE>. <A NAME="IDX174"></A> <A NAME="IDX175"></A> <DT><CODE>nexti</CODE> <DD> <DT><CODE>ni</CODE> <DD> Execute one machine instruction, but if it is a function call, proceed until the function returns. An argument is a repeat count, as in <CODE>next</CODE>. </DL> <H2><A NAME="SEC38" HREF="gdb_toc.html#TOC38">Signals</A></H2> <P> <A NAME="IDX176"></A> </P> <P> A signal is an asynchronous event that can happen in a program. The operating system defines the possible kinds of signals, and gives each kind a name and a number. For example, in Unix <CODE>SIGINT</CODE> is the signal a program gets when you type an interrupt (often <KBD>C-c</KBD>); <CODE>SIGSEGV</CODE> is the signal a program gets from referencing a place in memory far away from all the areas in use; <CODE>SIGALRM</CODE> occurs when the alarm clock timer goes off (which happens only if your program has requested an alarm). </P> <P> <A NAME="IDX177"></A> Some signals, including <CODE>SIGALRM</CODE>, are a normal part of the functioning of your program. Others, such as <CODE>SIGSEGV</CODE>, indicate errors; these signals are <STRONG>fatal</STRONG> (kill your program immediately) if the program has not specified in advance some other way to handle the signal. <CODE>SIGINT</CODE> does not indicate an error in your program, but it is normally fatal so it can carry out the purpose of the interrupt: to kill the program. </P> <P> GDB has the ability to detect any occurrence of a signal in your program. You can tell GDB in advance what to do for each kind of signal. </P> <P> <A NAME="IDX178"></A> Normally, GDB is set up to ignore non-erroneous signals like <CODE>SIGALRM</CODE> (so as not to interfere with their role in the functioning of your program) but to stop your program immediately whenever an error signal happens. You can change these settings with the <CODE>handle</CODE> command. </P> <DL COMPACT> <DT><CODE>info signals</CODE> <DD> <A NAME="IDX179"></A> Print a table of all the kinds of signals and how GDB has been told to handle each one. You can use this to see the signal numbers of all the defined types of signals. <CODE>info handle</CODE> is the new alias for <CODE>info signals</CODE>. <A NAME="IDX180"></A> <DT><CODE>handle <VAR>signal</VAR> <VAR>keywords</VAR>...</CODE> <DD> Change the way GDB handles signal <VAR>signal</VAR>. <VAR>signal</VAR> can be the number of a signal or its name (with or without the <SAMP>`SIG'</SAMP> at the beginning). The <VAR>keywords</VAR> say what change to make. </DL> <P> The keywords allowed by the <CODE>handle</CODE> command can be abbreviated. Their full names are: </P> <DL COMPACT> <DT><CODE>nostop</CODE> <DD> GDB should not stop your program when this signal happens. It may still print a message telling you that the signal has come in. <DT><CODE>stop</CODE> <DD> GDB should stop your program when this signal happens. This implies the <CODE>print</CODE> keyword as well. <DT><CODE>print</CODE> <DD> GDB should print a message when this signal happens. <DT><CODE>noprint</CODE> <DD> GDB should not mention the occurrence of the signal at all. This implies the <CODE>nostop</CODE> keyword as well. <DT><CODE>pass</CODE> <DD> GDB should allow your program to see this signal; your program can handle the signal, or else it may terminate if the signal is fatal and not handled. <DT><CODE>nopass</CODE> <DD> GDB should not allow your program to see this signal. </DL> <P> When a signal stops your program, the signal is not visible until you continue. Your program sees the signal then, if <CODE>pass</CODE> is in effect for the signal in question <EM>at that time</EM>. In other words, after GDB reports a signal, you can use the <CODE>handle</CODE> command with <CODE>pass</CODE> or <CODE>nopass</CODE> to control whether your program sees that signal when you continue. </P> <P> You can also use the <CODE>signal</CODE> command to prevent your program from seeing a signal, or cause it to see a signal it normally would not see, or to give it any signal at any time. For example, if your program stopped due to some sort of memory reference error, you might store correct values into the erroneous variables and continue, hoping to see more execution; but your program would probably terminate immediately as a result of the fatal signal once it saw the signal. To prevent this, you can continue with <SAMP>`signal 0'</SAMP>. See section <A HREF="gdb_12.html#SEC105">Giving your program a signal</A>. </P> <H2><A NAME="SEC39" HREF="gdb_toc.html#TOC39">Stopping and starting multi-thread programs</A></H2> <P> When your program has multiple threads (see section <A HREF="gdb_5.html#SEC25">Debugging programs with multiple threads</A>), you can choose whether to set breakpoints on all threads, or on a particular thread. </P> <DL COMPACT> <DT><CODE>break <VAR>linespec</VAR> thread <VAR>threadno</VAR></CODE> <DD> <A NAME="IDX181"></A> <A NAME="IDX182"></A> <A NAME="IDX183"></A> <DT><CODE>break <VAR>linespec</VAR> thread <VAR>threadno</VAR> if ...</CODE> <DD> <VAR>linespec</VAR> specifies source lines; there are several ways of writing them, but the effect is always to specify some source line. Use the qualifier <SAMP>`thread <VAR>threadno</VAR>'</SAMP> with a breakpoint command to specify that you only want GDB to stop the program when a particular thread reaches this breakpoint. <VAR>threadno</VAR> is one of the numeric thread identifiers assigned by GDB, shown in the first column of the <SAMP>`info threads'</SAMP> display. If you do not specify <SAMP>`thread <VAR>threadno</VAR>'</SAMP> when you set a breakpoint, the breakpoint applies to <EM>all</EM> threads of your program. You can use the <CODE>thread</CODE> qualifier on conditional breakpoints as well; in this case, place <SAMP>`thread <VAR>threadno</VAR>'</SAMP> before the breakpoint condition, like this: <PRE> (gdb) break frik.c:13 thread 28 if bartab > lim </PRE> </DL> <P> <A NAME="IDX184"></A> <A NAME="IDX185"></A> Whenever your program stops under GDB for any reason, <EM>all</EM> threads of execution stop, not just the current thread. This allows you to examine the overall state of the program, including switching between threads, without worrying that things may change underfoot. </P> <P> <A NAME="IDX186"></A> <A NAME="IDX187"></A> Conversely, whenever you restart the program, <EM>all</EM> threads start executing. <EM>This is true even when single-stepping</EM> with commands like <CODE>step</CODE> or <CODE>next</CODE>. </P> <P> In particular, GDB cannot single-step all threads in lockstep. Since thread scheduling is up to your debugging target's operating system (not controlled by GDB), other threads may execute more than one statement while the current thread completes a single step. Moreover, in general other threads stop in the middle of a statement, rather than at a clean statement boundary, when the program stops. </P> <P> You might even find your program stopped in another thread after continuing or even single-stepping. This happens whenever some other thread runs into a breakpoint, a signal, or an exception before the first thread completes whatever you requested. </P> <P> On some OSes, you can lock the OS scheduler and thus allow only a single thread to run. </P> <DL COMPACT> <DT><CODE>set scheduler-locking <VAR>mode</VAR></CODE> <DD> Set the scheduler locking mode. If it is <CODE>off</CODE>, then there is no locking and any thread may run at any time. If <CODE>on</CODE>, then only the current thread may run when the inferior is resumed. The <CODE>step</CODE> mode optimizes for single-stepping. It stops other threads from "seizing the prompt" by preempting the current thread while you are stepping. Other threads will only rarely (or never) get a chance to run when you step. They are more likely to run when you "next" over a function call, and they are completely free to run when you use commands like "continue", "until", or "finish". However, unless another thread hits a breakpoint during its timeslice, they will never steal the GDB prompt away from the thread that you are debugging. <DT><CODE>show scheduler-locking</CODE> <DD> Display the current scheduler locking mode. </DL> <P><HR><P> Go to the <A HREF="gdb_1.html">first</A>, <A HREF="gdb_5.html">previous</A>, <A HREF="gdb_7.html">next</A>, <A HREF="gdb_21.html">last</A> section, <A HREF="gdb_toc.html">table of contents</A>. </BODY> </HTML>