diff options
Diffstat (limited to 'gdb/doc/gdb.info-2')
| -rw-r--r-- | gdb/doc/gdb.info-2 | 1161 |
1 files changed, 0 insertions, 1161 deletions
diff --git a/gdb/doc/gdb.info-2 b/gdb/doc/gdb.info-2 deleted file mode 100644 index ab5549f..0000000 --- a/gdb/doc/gdb.info-2 +++ /dev/null @@ -1,1161 +0,0 @@ -This is Info file ./gdb.info, produced by Makeinfo version 1.68 from -the input file gdb.texinfo. - -START-INFO-DIR-ENTRY -* Gdb: (gdb). The GNU debugger. -END-INFO-DIR-ENTRY - This file documents the GNU debugger GDB. - - This is the Seventh Edition, February 1999, of `Debugging with GDB: -the GNU Source-Level Debugger' for GDB Version 4.18. - - Copyright (C) 1988-1999 Free Software Foundation, Inc. - - Permission is granted to make and distribute verbatim copies of this -manual provided the copyright notice and this permission notice are -preserved on all copies. - - Permission is granted to copy and distribute modified versions of -this manual under the conditions for verbatim copying, provided also -that the entire resulting derived work is distributed under the terms -of a permission notice identical to this one. - - Permission is granted to copy and distribute translations of this -manual into another language, under the above conditions for modified -versions. - - -File: gdb.info, Node: Starting, Next: Arguments, Prev: Compilation, Up: Running - -Starting your program -===================== - -`run' -`r' - Use the `run' command to start your program under GDB. You must - first specify the program name (except on VxWorks) with an - argument to GDB (*note Getting In and Out of GDB: Invocation.), or - by using the `file' or `exec-file' command (*note Commands to - specify files: Files.). - - If you are running your program in an execution environment that -supports processes, `run' creates an inferior process and makes that -process run your program. (In environments without processes, `run' -jumps to the start of your program.) - - The execution of a program is affected by certain information it -receives from its superior. GDB provides ways to specify this -information, which you must do *before* starting your program. (You -can change it after starting your program, but such changes only affect -your program the next time you start it.) This information may be -divided into four categories: - -The *arguments.* - Specify the arguments to give your program as the arguments of the - `run' command. If a shell is available on your target, the shell - is used to pass the arguments, so that you may use normal - conventions (such as wildcard expansion or variable substitution) - in describing the arguments. In Unix systems, you can control - which shell is used with the `SHELL' environment variable. *Note - Your program's arguments: Arguments. - -The *environment.* - Your program normally inherits its environment from GDB, but you - can use the GDB commands `set environment' and `unset environment' - to change parts of the environment that affect your program. - *Note Your program's environment: Environment. - -The *working directory.* - Your program inherits its working directory from GDB. You can set - the GDB working directory with the `cd' command in GDB. *Note - Your program's working directory: Working Directory. - -The *standard input and output.* - Your program normally uses the same device for standard input and - standard output as GDB is using. You can redirect input and output - in the `run' command line, or you can use the `tty' command to set - a different device for your program. *Note Your program's input - and output: Input/Output. - - *Warning:* While input and output redirection work, you cannot use - pipes to pass the output of the program you are debugging to - another program; if you attempt this, GDB is likely to wind up - debugging the wrong program. - - When you issue the `run' command, your program begins to execute -immediately. *Note Stopping and continuing: Stopping, for discussion -of how to arrange for your program to stop. Once your program has -stopped, you may call functions in your program, using the `print' or -`call' commands. *Note Examining Data: Data. - - If the modification time of your symbol file has changed since the -last time GDB read its symbols, GDB discards its symbol table, and -reads it again. When it does this, GDB tries to retain your current -breakpoints. - - -File: gdb.info, Node: Arguments, Next: Environment, Prev: Starting, Up: Running - -Your program's arguments -======================== - - The arguments to your program can be specified by the arguments of -the `run' command. They are passed to a shell, which expands wildcard -characters and performs redirection of I/O, and thence to your program. -Your `SHELL' environment variable (if it exists) specifies what shell -GDB uses. If you do not define `SHELL', GDB uses `/bin/sh'. - - `run' with no arguments uses the same arguments used by the previous -`run', or those set by the `set args' command. - -`set args' - Specify the arguments to be used the next time your program is - run. If `set args' has no arguments, `run' executes your program - with no arguments. Once you have run your program with arguments, - using `set args' before the next `run' is the only way to run it - again without arguments. - -`show args' - Show the arguments to give your program when it is started. - - -File: gdb.info, Node: Environment, Next: Working Directory, Prev: Arguments, Up: Running - -Your program's environment -========================== - - The "environment" consists of a set of environment variables and -their values. Environment variables conventionally record such things -as your user name, your home directory, your terminal type, and your -search path for programs to run. Usually you set up environment -variables with the shell and they are inherited by all the other -programs you run. When debugging, it can be useful to try running your -program with a modified environment without having to start GDB over -again. - -`path DIRECTORY' - Add DIRECTORY to the front of the `PATH' environment variable (the - search path for executables), for both GDB and your program. You - may specify several directory names, separated by `:' or - whitespace. If DIRECTORY is already in the path, it is moved to - the front, so it is searched sooner. - - You can use the string `$cwd' to refer to whatever is the current - working directory at the time GDB searches the path. If you use - `.' instead, it refers to the directory where you executed the - `path' command. GDB replaces `.' in the DIRECTORY argument (with - the current path) before adding DIRECTORY to the search path. - -`show paths' - Display the list of search paths for executables (the `PATH' - environment variable). - -`show environment [VARNAME]' - Print the value of environment variable VARNAME to be given to - your program when it starts. If you do not supply VARNAME, print - the names and values of all environment variables to be given to - your program. You can abbreviate `environment' as `env'. - -`set environment VARNAME [=] VALUE' - Set environment variable VARNAME to VALUE. The value changes for - your program only, not for GDB itself. VALUE may be any string; - the values of environment variables are just strings, and any - interpretation is supplied by your program itself. The VALUE - parameter is optional; if it is eliminated, the variable is set to - a null value. - - For example, this command: - - set env USER = foo - - tells a Unix program, when subsequently run, that its user is named - `foo'. (The spaces around `=' are used for clarity here; they are - not actually required.) - -`unset environment VARNAME' - Remove variable VARNAME from the environment to be passed to your - program. This is different from `set env VARNAME ='; `unset - environment' removes the variable from the environment, rather - than assigning it an empty value. - - *Warning:* GDB runs your program using the shell indicated by your -`SHELL' environment variable if it exists (or `/bin/sh' if not). If -your `SHELL' variable names a shell that runs an initialization -file--such as `.cshrc' for C-shell, or `.bashrc' for BASH--any -variables you set in that file affect your program. You may wish to -move setting of environment variables to files that are only run when -you sign on, such as `.login' or `.profile'. - - -File: gdb.info, Node: Working Directory, Next: Input/Output, Prev: Environment, Up: Running - -Your program's working directory -================================ - - Each time you start your program with `run', it inherits its working -directory from the current working directory of GDB. The GDB working -directory is initially whatever it inherited from its parent process -(typically the shell), but you can specify a new working directory in -GDB with the `cd' command. - - The GDB working directory also serves as a default for the commands -that specify files for GDB to operate on. *Note Commands to specify -files: Files. - -`cd DIRECTORY' - Set the GDB working directory to DIRECTORY. - -`pwd' - Print the GDB working directory. - - -File: gdb.info, Node: Input/Output, Next: Attach, Prev: Working Directory, Up: Running - -Your program's input and output -=============================== - - By default, the program you run under GDB does input and output to -the same terminal that GDB uses. GDB switches the terminal to its own -terminal modes to interact with you, but it records the terminal modes -your program was using and switches back to them when you continue -running your program. - -`info terminal' - Displays information recorded by GDB about the terminal modes your - program is using. - - You can redirect your program's input and/or output using shell -redirection with the `run' command. For example, - - run > outfile - -starts your program, diverting its output to the file `outfile'. - - Another way to specify where your program should do input and output -is with the `tty' command. This command accepts a file name as -argument, and causes this file to be the default for future `run' -commands. It also resets the controlling terminal for the child -process, for future `run' commands. For example, - - tty /dev/ttyb - -directs that processes started with subsequent `run' commands default -to do input and output on the terminal `/dev/ttyb' and have that as -their controlling terminal. - - An explicit redirection in `run' overrides the `tty' command's -effect on the input/output device, but not its effect on the controlling -terminal. - - When you use the `tty' command or redirect input in the `run' -command, only the input *for your program* is affected. The input for -GDB still comes from your terminal. - - -File: gdb.info, Node: Attach, Next: Kill Process, Prev: Input/Output, Up: Running - -Debugging an already-running process -==================================== - -`attach PROCESS-ID' - This command attaches to a running process--one that was started - outside GDB. (`info files' shows your active targets.) The - command takes as argument a process ID. The usual way to find out - the process-id of a Unix process is with the `ps' utility, or with - the `jobs -l' shell command. - - `attach' does not repeat if you press <RET> a second time after - executing the command. - - To use `attach', your program must be running in an environment -which supports processes; for example, `attach' does not work for -programs on bare-board targets that lack an operating system. You must -also have permission to send the process a signal. - - When you use `attach', the debugger finds the program running in the -process first by looking in the current working directory, then (if the -program is not found) by using the source file search path (*note -Specifying source directories: Source Path.). You can also use the -`file' command to load the program. *Note Commands to Specify Files: -Files. - - The first thing GDB does after arranging to debug the specified -process is to stop it. You can examine and modify an attached process -with all the GDB commands that are ordinarily available when you start -processes with `run'. You can insert breakpoints; you can step and -continue; you can modify storage. If you would rather the process -continue running, you may use the `continue' command after attaching -GDB to the process. - -`detach' - When you have finished debugging the attached process, you can use - the `detach' command to release it from GDB control. Detaching - the process continues its execution. After the `detach' command, - that process and GDB become completely independent once more, and - you are ready to `attach' another process or start one with `run'. - `detach' does not repeat if you press <RET> again after executing - the command. - - If you exit GDB or use the `run' command while you have an attached -process, you kill that process. By default, GDB asks for confirmation -if you try to do either of these things; you can control whether or not -you need to confirm by using the `set confirm' command (*note Optional -warnings and messages: Messages/Warnings.). - - -File: gdb.info, Node: Kill Process, Next: Process Information, Prev: Attach, Up: Running - -Killing the child process -========================= - -`kill' - Kill the child process in which your program is running under GDB. - - This command is useful if you wish to debug a core dump instead of a -running process. GDB ignores any core dump file while your program is -running. - - On some operating systems, a program cannot be executed outside GDB -while you have breakpoints set on it inside GDB. You can use the -`kill' command in this situation to permit running your program outside -the debugger. - - The `kill' command is also useful if you wish to recompile and -relink your program, since on many systems it is impossible to modify an -executable file while it is running in a process. In this case, when -you next type `run', GDB notices that the file has changed, and reads -the symbol table again (while trying to preserve your current -breakpoint settings). - - -File: gdb.info, Node: Process Information, Next: Threads, Prev: Kill Process, Up: Running - -Additional process information -============================== - - Some operating systems provide a facility called `/proc' that can be -used to examine the image of a running process using file-system -subroutines. If GDB is configured for an operating system with this -facility, the command `info proc' is available to report on several -kinds of information about the process running your program. `info -proc' works only on SVR4 systems that support `procfs'. - -`info proc' - Summarize available information about the process. - -`info proc mappings' - Report on the address ranges accessible in the program, with - information on whether your program may read, write, or execute - each range. - -`info proc times' - Starting time, user CPU time, and system CPU time for your program - and its children. - -`info proc id' - Report on the process IDs related to your program: its own process - ID, the ID of its parent, the process group ID, and the session ID. - -`info proc status' - General information on the state of the process. If the process is - stopped, this report includes the reason for stopping, and any - signal received. - -`info proc all' - Show all the above information about the process. - - -File: gdb.info, Node: Threads, Next: Processes, Prev: Process Information, Up: Running - -Debugging programs with multiple threads -======================================== - - In some operating systems, such as HP-UX and Solaris, a single -program may have more than one "thread" of execution. The precise -semantics of threads differ from one operating system to another, but -in general the threads of a single program are akin to multiple -processes--except that they share one address space (that is, they can -all examine and modify the same variables). On the other hand, each -thread has its own registers and execution stack, and perhaps private -memory. - - GDB provides these facilities for debugging multi-thread programs: - - * automatic notification of new threads - - * `thread THREADNO', a command to switch among threads - - * `info threads', a command to inquire about existing threads - - * `thread apply [THREADNO] [ALL] ARGS', a command to apply a command - to a list of threads - - * thread-specific breakpoints - - *Warning:* These facilities are not yet available on every GDB - configuration where the operating system supports threads. If - your GDB does not support threads, these commands have no effect. - For example, a system without thread support shows no output from - `info threads', and always rejects the `thread' command, like this: - - (gdb) info threads - (gdb) thread 1 - Thread ID 1 not known. Use the "info threads" command to - see the IDs of currently known threads. - - The GDB thread debugging facility allows you to observe all threads -while your program runs--but whenever GDB takes control, one thread in -particular is always the focus of debugging. This thread is called the -"current thread". Debugging commands show program information from the -perspective of the current thread. - - Whenever GDB detects a new thread in your program, it displays the -target system's identification for the thread with a message in the -form `[New SYSTAG]'. SYSTAG is a thread identifier whose form varies -depending on the particular system. For example, on LynxOS, you might -see - - [New process 35 thread 27] - -when GDB notices a new thread. In contrast, on an SGI system, the -SYSTAG is simply something like `process 368', with no further -qualifier. - - For debugging purposes, GDB associates its own thread number--always -a single integer--with each thread in your program. - -`info threads' - Display a summary of all threads currently in your program. GDB - displays for each thread (in this order): - - 1. the thread number assigned by GDB - - 2. the target system's thread identifier (SYSTAG) - - 3. the current stack frame summary for that thread - - An asterisk `*' to the left of the GDB thread number indicates the - current thread. - - For example, - - (gdb) info threads - 3 process 35 thread 27 0x34e5 in sigpause () - 2 process 35 thread 23 0x34e5 in sigpause () - * 1 process 35 thread 13 main (argc=1, argv=0x7ffffff8) - at threadtest.c:68 - -`thread THREADNO' - Make thread number THREADNO the current thread. The command - argument THREADNO is the internal GDB thread number, as shown in - the first field of the `info threads' display. GDB responds by - displaying the system identifier of the thread you selected, and - its current stack frame summary: - - (gdb) thread 2 - [Switching to process 35 thread 23] - 0x34e5 in sigpause () - - As with the `[New ...]' message, the form of the text after - `Switching to' depends on your system's conventions for identifying - threads. - -`thread apply [THREADNO] [ALL] ARGS' - The `thread apply' command allows you to apply a command to one or - more threads. Specify the numbers of the threads that you want - affected with the command argument THREADNO. THREADNO is the - internal GDB thread number, as shown in the first field of the - `info threads' display. To apply a command to all threads, use - `thread apply all' ARGS. - - Whenever GDB stops your program, due to a breakpoint or a signal, it -automatically selects the thread where that breakpoint or signal -happened. GDB alerts you to the context switch with a message of the -form `[Switching to SYSTAG]' to identify the thread. - - *Note Stopping and starting multi-thread programs: Thread Stops, for -more information about how GDB behaves when you stop and start programs -with multiple threads. - - *Note Setting watchpoints: Set Watchpoints, for information about -watchpoints in programs with multiple threads. - - -File: gdb.info, Node: Processes, Prev: Threads, Up: Running - -Debugging programs with multiple processes -========================================== - - GDB has no special support for debugging programs which create -additional processes using the `fork' function. When a program forks, -GDB will continue to debug the parent process and the child process -will run unimpeded. If you have set a breakpoint in any code which the -child then executes, the child will get a `SIGTRAP' signal which -(unless it catches the signal) will cause it to terminate. - - However, if you want to debug the child process there is a workaround -which isn't too painful. Put a call to `sleep' in the code which the -child process executes after the fork. It may be useful to sleep only -if a certain environment variable is set, or a certain file exists, so -that the delay need not occur when you don't want to run GDB on the -child. While the child is sleeping, use the `ps' program to get its -process ID. Then tell GDB (a new invocation of GDB if you are also -debugging the parent process) to attach to the child process (see *Note -Attach::). From that point on you can debug the child process just -like any other process which you attached to. - - -File: gdb.info, Node: Stopping, Next: Stack, Prev: Running, Up: Top - -Stopping and Continuing -*********************** - - 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. - - 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 `step'. 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. - -`info program' - Display information about the status of your program: whether it is - running or not, what process it is, and why it stopped. - -* Menu: - -* Breakpoints:: Breakpoints, watchpoints, and catchpoints -* Continuing and Stepping:: Resuming execution - -* Signals:: Signals - - -* Thread Stops:: Stopping and starting multi-thread programs - - -File: gdb.info, Node: Breakpoints, Next: Continuing and Stepping, Prev: Stopping, Up: Stopping - -Breakpoints, watchpoints, and catchpoints -========================================= - - A "breakpoint" 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 `break' command and its variants (*note Setting -breakpoints: Set Breaks.), to specify the place where your program -should stop by line number, function name or exact address in the -program. - - In HP-UX, SunOS 4.x, SVR4, 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 `pthread_create' call). - - A "watchpoint" is a special breakpoint that stops your program when -the value of an expression changes. You must use a different command -to set watchpoints (*note Setting watchpoints: Set Watchpoints.), 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. - - You can arrange to have values from your program displayed -automatically whenever GDB stops at a breakpoint. *Note Automatic -display: Auto Display. - - A "catchpoint" 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 (*note Setting catchpoints: Set -Catchpoints.), but aside from that, you can manage a catchpoint like any -other breakpoint. (To stop when your program receives a signal, use the -`handle' command; *note Signals: Signals..) - - 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 "enabled" or "disabled"; if -disabled, it has no effect on your program until you enable it again. - -* Menu: - -* Set Breaks:: Setting breakpoints -* Set Watchpoints:: Setting watchpoints -* Set Catchpoints:: Setting catchpoints -* Delete Breaks:: Deleting breakpoints -* Disabling:: Disabling breakpoints -* Conditions:: Break conditions -* Break Commands:: Breakpoint command lists - -* Breakpoint Menus:: Breakpoint menus - - -File: gdb.info, Node: Set Breaks, Next: Set Watchpoints, Prev: Breakpoints, Up: Breakpoints - -Setting breakpoints -------------------- - - Breakpoints are set with the `break' command (abbreviated `b'). The -debugger convenience variable `$bpnum' records the number of the -breakpoints you've set most recently; see *Note Convenience variables: -Convenience Vars, for a discussion of what you can do with convenience -variables. - - You have several ways to say where the breakpoint should go. - -`break FUNCTION' - Set a breakpoint at entry to function FUNCTION. When using source - languages that permit overloading of symbols, such as C++, - FUNCTION may refer to more than one possible place to break. - *Note Breakpoint menus: Breakpoint Menus, for a discussion of that - situation. - -`break +OFFSET' -`break -OFFSET' - Set a breakpoint some number of lines forward or back from the - position at which execution stopped in the currently selected - frame. - -`break LINENUM' - Set a breakpoint at line LINENUM 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. - -`break FILENAME:LINENUM' - Set a breakpoint at line LINENUM in source file FILENAME. - -`break FILENAME:FUNCTION' - Set a breakpoint at entry to function FUNCTION found in file - FILENAME. Specifying a file name as well as a function name is - superfluous except when multiple files contain similarly named - functions. - -`break *ADDRESS' - Set a breakpoint at address ADDRESS. You can use this to set - breakpoints in parts of your program which do not have debugging - information or source files. - -`break' - When called without any arguments, `break' sets a breakpoint at - the next instruction to be executed in the selected stack frame - (*note Examining the Stack: Stack.). 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 `finish' - command in the frame inside the selected frame--except that - `finish' does not leave an active breakpoint. If you use `break' - 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. - -`break ... if COND' - Set a breakpoint with condition COND; evaluate the expression COND - each time the breakpoint is reached, and stop only if the value is - nonzero--that is, if COND evaluates as true. `...' stands for one - of the possible arguments described above (or no argument) - specifying where to break. *Note Break conditions: Conditions, - for more information on breakpoint conditions. - -`tbreak ARGS' - Set a breakpoint enabled only for one stop. ARGS are the same as - for the `break' command, and the breakpoint is set in the same - way, but the breakpoint is automatically deleted after the first - time your program stops there. *Note Disabling breakpoints: - Disabling. - -`hbreak ARGS' - Set a hardware-assisted breakpoint. ARGS are the same as for the - `break' 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. - *Note Break conditions: Conditions. - -`thbreak ARGS' - Set a hardware-assisted breakpoint enabled only for one stop. ARGS - are the same as for the `hbreak' command and the breakpoint is set - in the same way. However, like the `tbreak' command, the - breakpoint is automatically deleted after the first time your - program stops there. Also, like the `hbreak' command, the - breakpoint requires hardware support and some target hardware may - not have this support. *Note Disabling breakpoints: Disabling. - Also *Note Break conditions: Conditions. - -`rbreak REGEX' - Set breakpoints on all functions matching the regular expression - REGEX. 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 `break' command. You can delete them, disable them, - or make them conditional the same way as any other breakpoint. - - When debugging C++ programs, `rbreak' is useful for setting - breakpoints on overloaded functions that are not members of any - special classes. - -`info breakpoints [N]' -`info break [N]' -`info watchpoints [N]' - Print a table of all breakpoints, watchpoints, and catchpoints set - and not deleted, with the following columns for each breakpoint: - - *Breakpoint Numbers* - - *Type* - Breakpoint, watchpoint, or catchpoint. - - *Disposition* - Whether the breakpoint is marked to be disabled or deleted - when hit. - - *Enabled or Disabled* - Enabled breakpoints are marked with `y'. `n' marks - breakpoints that are not enabled. - - *Address* - Where the breakpoint is in your program, as a memory address - - *What* - Where the breakpoint is in the source for your program, as a - file and line number. - - If a breakpoint is conditional, `info break' shows the condition on - the line following the affected breakpoint; breakpoint commands, - if any, are listed after that. - - `info break' with a breakpoint number N as argument lists only - that breakpoint. The convenience variable `$_' and the default - examining-address for the `x' command are set to the address of - the last breakpoint listed (*note Examining memory: Memory.). - - `info break' displays a count of the number of times the breakpoint - has been hit. This is especially useful in conjunction with the - `ignore' 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. - - 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 (*note Break -conditions: Conditions.). - - GDB itself sometimes sets breakpoints in your program for special -purposes, such as proper handling of `longjmp' (in C programs). These -internal breakpoints are assigned negative numbers, starting with `-1'; -`info breakpoints' does not display them. - - You can see these breakpoints with the GDB maintenance command -`maint info breakpoints'. - -`maint info breakpoints' - Using the same format as `info breakpoints', 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: - - `breakpoint' - Normal, explicitly set breakpoint. - - `watchpoint' - Normal, explicitly set watchpoint. - - `longjmp' - Internal breakpoint, used to handle correctly stepping through - `longjmp' calls. - - `longjmp resume' - Internal breakpoint at the target of a `longjmp'. - - `until' - Temporary internal breakpoint used by the GDB `until' command. - - `finish' - Temporary internal breakpoint used by the GDB `finish' - command. - - -File: gdb.info, Node: Set Watchpoints, Next: Set Catchpoints, Prev: Set Breaks, Up: Breakpoints - -Setting watchpoints -------------------- - - 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. - - 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.) - - 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. - -`watch EXPR' - Set a watchpoint for an expression. GDB will break when EXPR is - written into by the program and its value changes. - -`rwatch EXPR' - Set a watchpoint that will break when watch EXPR is read by the - program. If you use both watchpoints, both must be set with the - `rwatch' command. - -`awatch EXPR' - Set a watchpoint that will break when ARGS is read and written into - by the program. If you use both watchpoints, both must be set - with the `awatch' command. - -`info watchpoints' - This command prints a list of watchpoints, breakpoints, and - catchpoints; it is the same as `info break'. - - GDB sets a "hardware watchpoint" 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. - - When you issue the `watch' command, GDB reports - - Hardware watchpoint NUM: EXPR - -if it was able to set a hardware watchpoint. - - 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 `watch' 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 `watch' commands, two with `rwatch' commands, *or* -two with `awatch' 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. - - If you call a function interactively using `print' or `call', any -watchpoints you have set will be inactive until GDB reaches another -kind of breakpoint or the call completes. - - *Warning:* In multi-thread programs, watchpoints have only limited - usefulness. With the current watchpoint implementation, GDB can - only watch the value of an expression *in a single thread*. 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. - - -File: gdb.info, Node: Set Catchpoints, Next: Delete Breaks, Prev: Set Watchpoints, Up: Breakpoints - -Setting catchpoints -------------------- - - You can use "catchpoints" 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 `catch' command to set a catchpoint. - -`catch EVENT' - Stop when EVENT occurs. EVENT can be any of the following: - `throw' - The throwing of a C++ exception. - - `catch' - The catching of a C++ exception. - - `exec' - A call to `exec'. This is currently only available for HP-UX. - - `fork' - A call to `fork'. This is currently only available for HP-UX. - - `vfork' - A call to `vfork'. This is currently only available for - HP-UX. - - `load' - `load LIBNAME' - The dynamic loading of any shared library, or the loading of - the library LIBNAME. This is currently only available for - HP-UX. - - `unload' - `unload LIBNAME' - The unloading of any dynamically loaded shared library, or - the unloading of the library LIBNAME. This is currently only - available for HP-UX. - -`tcatch EVENT' - Set a catchpoint that is enabled only for one stop. The - catchpoint is automatically deleted after the first time the event - is caught. - - Use the `info break' command to list the current catchpoints. - - There are currently some limitations to C++ exception handling -(`catch throw' and `catch catch') in GDB: - - * 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. - - * You cannot raise an exception interactively. - - * You cannot install an exception handler interactively. - - Sometimes `catch' 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 *before* 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. - - 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 `__raise_exception' which -has the following ANSI C interface: - - /* ADDR is where the exception identifier is stored. - ID is the exception identifier. */ - void __raise_exception (void **ADDR, void *ID); - -To make the debugger catch all exceptions before any stack unwinding -takes place, set a breakpoint on `__raise_exception' (*note -Breakpoints; watchpoints; and exceptions: Breakpoints.). - - With a conditional breakpoint (*note Break conditions: Conditions.) -that depends on the value of ID, 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. - - -File: gdb.info, Node: Delete Breaks, Next: Disabling, Prev: Set Catchpoints, Up: Breakpoints - -Deleting breakpoints --------------------- - - 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 "deleting" the breakpoint. A breakpoint -that has been deleted no longer exists; it is forgotten. - - With the `clear' command you can delete breakpoints according to -where they are in your program. With the `delete' command you can -delete individual breakpoints, watchpoints, or catchpoints by specifying -their breakpoint numbers. - - 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. - -`clear' - Delete any breakpoints at the next instruction to be executed in - the selected stack frame (*note Selecting a frame: Selection.). - When the innermost frame is selected, this is a good way to delete - a breakpoint where your program just stopped. - -`clear FUNCTION' -`clear FILENAME:FUNCTION' - Delete any breakpoints set at entry to the function FUNCTION. - -`clear LINENUM' -`clear FILENAME:LINENUM' - Delete any breakpoints set at or within the code of the specified - line. - -`delete [breakpoints] [BNUMS...]' - 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 `set confirm - off'). You can abbreviate this command as `d'. - - -File: gdb.info, Node: Disabling, Next: Conditions, Prev: Delete Breaks, Up: Breakpoints - -Disabling breakpoints ---------------------- - - Rather than deleting a breakpoint, watchpoint, or catchpoint, you -might prefer to "disable" it. This makes the breakpoint inoperative as -if it had been deleted, but remembers the information on the breakpoint -so that you can "enable" it again later. - - You disable and enable breakpoints, watchpoints, and catchpoints with -the `enable' and `disable' commands, optionally specifying one or more -breakpoint numbers as arguments. Use `info break' or `info watch' to -print a list of breakpoints, watchpoints, and catchpoints if you do not -know which numbers to use. - - A breakpoint, watchpoint, or catchpoint can have any of four -different states of enablement: - - * Enabled. The breakpoint stops your program. A breakpoint set - with the `break' command starts out in this state. - - * Disabled. The breakpoint has no effect on your program. - - * Enabled once. The breakpoint stops your program, but then becomes - disabled. A breakpoint set with the `tbreak' command starts out in - this state. - - * Enabled for deletion. The breakpoint stops your program, but - immediately after it does so it is deleted permanently. - - You can use the following commands to enable or disable breakpoints, -watchpoints, and catchpoints: - -`disable [breakpoints] [BNUMS...]' - 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 `disable' as `dis'. - -`enable [breakpoints] [BNUMS...]' - Enable the specified breakpoints (or all defined breakpoints). - They become effective once again in stopping your program. - -`enable [breakpoints] once BNUMS...' - Enable the specified breakpoints temporarily. GDB disables any of - these breakpoints immediately after stopping your program. - -`enable [breakpoints] delete BNUMS...' - Enable the specified breakpoints to work once, then die. GDB - deletes any of these breakpoints as soon as your program stops - there. - - Except for a breakpoint set with `tbreak' (*note Setting -breakpoints: Set Breaks.), breakpoints that you set are initially -enabled; subsequently, they become disabled or enabled only when you -use one of the commands above. (The command `until' can set and delete -a breakpoint of its own, but it does not change the state of your other -breakpoints; see *Note Continuing and stepping: Continuing and -Stepping.) - - -File: gdb.info, Node: Conditions, Next: Break Commands, Prev: Disabling, Up: Breakpoints - -Break conditions ----------------- - - The simplest sort of breakpoint breaks every time your program -reaches a specified place. You can also specify a "condition" for a -breakpoint. A condition is just a Boolean expression in your -programming language (*note Expressions: Expressions.). A breakpoint -with a condition evaluates the expression each time your program -reaches it, and your program stops only if the condition is *true*. - - 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 ASSERT, you should set the -condition `! ASSERT' on the appropriate breakpoint. - - 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. - - 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 (*note Breakpoint -command lists: Break Commands.). - - Break conditions can be specified when a breakpoint is set, by using -`if' in the arguments to the `break' command. *Note Setting -breakpoints: Set Breaks. They can also be changed at any time with the -`condition' command. The `watch' command does not recognize the `if' -keyword; `condition' is the only way to impose a further condition on a -watchpoint. - -`condition BNUM EXPRESSION' - Specify EXPRESSION as the break condition for breakpoint, - watchpoint, or catchpoint number BNUM. After you set a condition, - breakpoint BNUM stops your program only if the value of EXPRESSION - is true (nonzero, in C). When you use `condition', GDB checks - EXPRESSION immediately for syntactic correctness, and to determine - whether symbols in it have referents in the context of your - breakpoint. GDB does not actually evaluate EXPRESSION at the time - the `condition' command is given, however. *Note Expressions: - Expressions. - -`condition BNUM' - Remove the condition from breakpoint number BNUM. It becomes an - ordinary unconditional breakpoint. - - 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 "ignore count" -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 -N, the breakpoint does not stop the next N times your program reaches -it. - -`ignore BNUM COUNT' - Set the ignore count of breakpoint number BNUM to COUNT. The next - COUNT 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 `continue' to resume execution of your program from a - breakpoint, you can specify an ignore count directly as an - argument to `continue', rather than using `ignore'. *Note - Continuing and stepping: Continuing and Stepping. - - 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 `$foo-- <= 0' using a debugger convenience variable that - is decremented each time. *Note Convenience variables: - Convenience Vars. - - Ignore counts apply to breakpoints, watchpoints, and catchpoints. - |