DragonFly On-Line Manual Pages

Search: Section:  


gdb(1)				   GNU Tools				gdb(1)

NAME

gdb - The GNU Debugger

SYNOPSIS

gdb [-help] [-nh] [-nx] [-q] [-batch] [-cd=dir] [-f] [-b bps] [-tty=dev] [-s symfile] [-e prog] [-se prog] [-c core] [-x file] [-ex cmd] [-d dir] [prog[core|procID]]

DESCRIPTION

The purpose of a debugger such as GDB is to allow you to see what is going on ``inside'' another program while it executes--or what another program was doing at the moment it crashed. GDB can do four main kinds of things (plus other things in support of these) to help you catch bugs in the act: o Start your program, specifying anything that might affect its behavior. o Make your program stop on specified conditions. o Examine what has happened, when your program has stopped. o Change things in your program, so you can experiment with cor- recting the effects of one bug and go on to learn about another. You can use GDB to debug programs written in C, C++, and Modula-2. Fortran support will be added when a GNU Fortran compiler is ready. GDB is invoked with the shell command gdb. Once started, it reads com- mands from the terminal until you tell it to exit with the GDB command quit. You can get online help from gdb itself by using the command help. You can run gdb with no arguments or options; but the most usual way to start GDB is with one argument or two, specifying an executable program as the argument: gdb program You can also start with both an executable program and a core file specified: gdb program core You can, instead, specify a process ID as a second argument, if you want to debug a running process: gdb program 1234 would attach GDB to process 1234 (unless you also have a file named `1234'; GDB does check for a core file first). Here are some of the most frequently needed GDB commands: break [file:]function Set a breakpoint at function (in file). run [arglist] Start your program (with arglist, if specified). bt Backtrace: display the program stack. print expr Display the value of an expression. c Continue running your program (after stopping, e.g. at a break- point). next Execute next program line (after stopping); step over any func- tion calls in the line. edit [file:]function look at the program line where it is presently stopped. list [file:]function type the text of the program in the vicinity of where it is presently stopped. step Execute next program line (after stopping); step into any func- tion calls in the line. help [name] Show information about GDB command name, or general information about using GDB. quit Exit from GDB. For full details on GDB, see Using GDB: A Guide to the GNU Source-Level Debugger, by Richard M. Stallman and Roland H. Pesch. The same text is available online as the gdb entry in the info program.

OPTIONS

Any arguments other than options specify an executable file and core file (or process ID); that is, the first argument encountered with no associated option flag is equivalent to a `-se' option, and the second, if any, is equivalent to a `-c' option if it's the name of a file. Many options have both long and short forms; both are shown here. The long forms are also recognized if you truncate them, so long as enough of the option is present to be unambiguous. (If you prefer, you can flag option arguments with `*' rather than `-', though we illustrate the more usual convention.) All the options and command line arguments you give are processed in sequential order. The order makes a difference when the `-x' option is used. -help -h List all options, with brief explanations. -symbols=file -s file Read symbol table from file file. -write Enable writing into executable and core files. -exec=file -e file Use file file as the executable file to execute when appropri- ate, and for examining pure data in conjunction with a core dump. -se=file Read symbol table from file file and use it as the executable file. -core=file -c file Use file file as a core dump to examine. -command=file -x file Execute GDB commands from file file. -ex command Execute given GDB command. -directory=directory -d directory Add directory to the path to search for source files. -nh Do not execute commands from ~/.gdbinit. -nx -n Do not execute commands from any `.gdbinit' initialization files. -quiet -q ``Quiet''. Do not print the introductory and copyright mes- sages. These messages are also suppressed in batch mode. -batch Run in batch mode. Exit with status 0 after processing all the command files specified with `-x' (and `.gdbinit', if not inhib- ited). Exit with nonzero status if an error occurs in executing the GDB commands in the command files. Batch mode may be useful for running GDB as a filter, for exam- ple to download and run a program on another computer; in order to make this more useful, the message Program exited normally. (which is ordinarily issued whenever a program running under GDB control terminates) is not issued when running in batch mode. -cd=directory Run GDB using directory as its working directory, instead of the current directory. -fullname -f Emacs sets this option when it runs GDB as a subprocess. It tells GDB to output the full file name and line number in a standard, recognizable fashion each time a stack frame is dis- played (which includes each time the program stops). This rec- ognizable format looks like two ` 32' characters, followed by the file name, line number and character position separated by colons, and a newline. The Emacs-to-GDB interface program uses the two ` 32' characters as a signal to display the source code for the frame. -b bps Set the line speed (baud rate or bits per second) of any serial interface used by GDB for remote debugging. -tty=device Run using device for your program's standard input and output.

SEE ALSO

The full documentation for gdb is maintained as a Texinfo manual. If the info and gdb programs and GDB's Texinfo documentation are properly installed at your site, the command info gdb should give you access to the complete manual. Using GDB: A Guide to the GNU Source-Level Debugger, Richard M. Stall- man and Roland H. Pesch, July 1991.

COPYING

Copyright (c) 1991, 2010 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 that the entire resulting derived work is distributed under the terms of a per- mission notice identical to this one. Permission is granted to copy and distribute translations of this man- ual into another language, under the above conditions for modified ver- sions, except that this permission notice may be included in transla- tions approved by the Free Software Foundation instead of in the origi- nal English. GNU Tools 22may2002 gdb(1) GDB(4) DragonFly Kernel Interfaces Manual GDB(4)

NAME

gdb -- external kernel debugger

SYNOPSIS

makeoptions DEBUG=-g options DDB options GDB_REMOTE_CHAT

DESCRIPTION

The gdb kernel debugger is a variation of gdb(1) which understands some aspects of the FreeBSD kernel environment. It can be used in a number of ways: * It can be used to examine the memory of the processor on which it runs. * It can be used to analyse a processor dump after a panic. * It can be used to debug another system interactively via a serial or firewire link. In this mode, the processor can be stopped and single stepped. * With a firewire link, it can be used to examine the memory of a remote system without the participation of that system. In this mode, the processor cannot be stopped and single stepped, but it can be of use when the remote system has crashed and is no longer responding. When used for remote debugging, gdb requires the presence of the ddb(4) kernel debugger. Commands exist to switch between gdb and ddb(4).

PREPARING FOR DEBUGGING

When debugging kernels, it is practically essential to have built a ker- nel with debugging symbols (makeoptions DEBUG=-g). It is easiest to per- form operations from the kernel build directory, by default /usr/obj/usr/src/sys/X86_64_GENERIC. First, ensure you have a copy of the debug macros in the directory: make gdbinit This command performs some transformations on the macros installed in /usr/src/tools/debugscripts to adapt them to the local environment. Inspecting the environment of the local machine To look at and change the contents of the memory of the system you are running on, gdb -k -wcore kernel.debug /dev/mem In this mode, you need the -k flag to indicate to gdb(1) that the ``dump file'' /dev/mem is a kernel data file. You can look at live data, and if you include the -wcore option, you can change it at your peril. The sys- tem does not stop (obviously), so a number of things will not work. You can set breakpoints, but you cannot ``continue'' execution, so they will not work. Debugging a crash dump By default, crash dumps are stored in the directory /var/crash. Investi- gate them from the kernel build directory with: gdb -k kernel.debug /var/crash/vmcore.29 In this mode, the system is obviously stopped, so you can only look at it. Debugging a live system with a remote link In the following discussion, the term ``local system'' refers to the sys- tem running the debugger, and ``remote system'' refers to the live system being debugged. To debug a live system with a remote link, the kernel must be compiled with the option options DDB. The option options BREAK_TO_DEBUGGER enables the debugging machine stop the debugged machine once a connection has been established by pressing `^C'. Debugging a live system with a remote serial link When using a serial port for the remote link on the i386 platform, the serial port must be identified by setting the flag bit 0x80 for the spec- ified interface. Generally, this port will also be used as a serial con- sole (flag bit 0x10), so the flags field for the interface in the kernel configuration file should be: flags 0x90 To share a console and debug connection on a serial line, use the options GDB_REMOTE_CHAT option. Debugging a live system with a remote firewire link As with serial debugging, to debug a live system with a firewire link, the kernel must be compiled with the option options DDB. The options GDB_REMOTE_CHAT is not necessary, since the firewire implementation uses separate ports for the console and debug connection. A number of steps must be performed to set up a firewire link: * Ensure that both systems have firewire(4) support, and that the ker- nel of the remote system includes the dcons(4) and dcons_crom(4) drivers. If they are not compiled into the kernel, load the KLDs: kldload firewire On the remote system only: kldload dcons kldload dcons_crom You should see something like this in the dmesg(8) output of the remote system: fwohci0: BUS reset fwohci0: node_id=0x8800ffc0, gen=2, non CYCLEMASTER mode firewire0: 2 nodes, maxhop <= 1, cable IRM = 1 firewire0: bus manager 1 firewire0: New S400 device ID:00c04f3226e88061 dcons_crom0: <dcons configuration ROM> on firewire0 dcons_crom0: bus_addr 0x22a000 It is a good idea to load these modules at boot time with the follow- ing entry in /boot/loader.conf: dcons_crom_enable="YES" This ensures that all three modules are loaded. There is no harm in loading dcons(4) and dcons_crom(4) on the local system, but if you only want to load the firewire(4) module, include the following in /boot/loader.conf: firewire_enable="YES" * Next, use fwcontrol(8) to find the firewire node corresponding to the remote machine. On the local machine you might see: # fwcontrol 2 devices (info_len=2) node EUI64 status 1 0x00c04f3226e88061 0 0 0x000199000003622b 1 The first node is always the local system, so in this case, node 0 is the remote system. If there are more than two systems, check from the other end to find which node corresponds to the remote system. On the remote machine, it looks like this: # fwcontrol 2 devices (info_len=2) node EUI64 status 0 0x000199000003622b 0 1 0x00c04f3226e88061 1 * Next, establish a firewire connection with dconschat(8): dconschat -br -G 5556 -t 0x000199000003622b 0x000199000003622b is the EUI64 address of the remote node, as deter- mined from the output of fwcontrol(8) above. When started in this manner, dconschat(8) establishes a local tunnel connection from port localhost:5556 to the remote debugger. You can also establish a con- sole port connection with the -C option to the same invocation dconschat(8). See the dconschat(8) manpage for further details. The dconschat(8) utility does not return control to the user. It displays error messages and console output for the remote system, so it is a good idea to start it in its own window. * Finally, establish connection: # gdb kernel.debug GNU gdb 5.2.1 (FreeBSD) (political statements omitted) Ready to go. Enter 'tr' to connect to the remote target with /dev/cuaa0, 'tr /dev/cuaa1' to connect to a different port or 'trf portno' to connect to the remote target with the firewire interface. portno defaults to 5556. Type 'getsyms' after connection to load kld symbols. If you're debugging a local system, you can use 'kldsyms' instead to load the kld symbols. That's a less obnoxious interface. (gdb) trf 0xc21bd378 in ?? () The trf macro assumes a connection on port 5556. If you want to use a different port (by changing the invocation of dconschat(8) above), use the tr macro instead. For example, if you want to use port 4711, run dconschat(8) like this: dconschat -br -G 4711 -t 0x000199000003622b Then establish connection with: (gdb) tr localhost:4711 0xc21bd378 in ?? () Non-cooperative debugging a live system with a remote firewire link In addition to the conventional debugging via firewire described in the previous section, it is possible to debug a remote system without its cooperation, once an initial connection has been established. This cor- responds to debugging a local machine using /dev/mem. It can be very useful if a system crashes and the debugger no longer responds. To use this method, set the sysctl(8) variables hw.firewire.fwmem.eui64_hi and hw.firewire.fwmem.eui64_lo to the upper and lower halves of the EUI64 ID of the remote system, respectively. From the previous example, the remote machine shows: # fwcontrol 2 devices (info_len=2) node EUI64 status 0 0x000199000003622b 0 1 0x00c04f3226e88061 1 Enter: # sysctl -w hw.firewire.fwmem.eui64_hi=0x00019900 hw.firewire.fwmem.eui64_hi: 0 -> 104704 # sysctl -w hw.firewire.fwmem.eui64_lo=0x0003622b hw.firewire.fwmem.eui64_lo: 0 -> 221739 Note that the variables must be explicitly stated in hexadecimal. After this, you can examine the remote machine's state with the following input: # gdb -k kernel.debug /dev/fwmem0.0 GNU gdb 5.2.1 (FreeBSD) (messages omitted) Reading symbols from /modules/dcons.ko...done. Loaded symbols for /modules/dcons.ko Reading symbols from /modules/dcons_crom.ko...done. Loaded symbols for /modules/dcons_crom.ko #0 sched_switch (td=0xc0922fe0) at /usr/src/sys/kern/sched_4bsd.c:621 0xc21bd378 in ?? () In this case, it is not necessary to load the symbols explicitly. The remote system continues to run.

COMMANDS

The user interface to gdb is via gdb(1), so gdb(1) commands also work. This section discusses only the extensions for kernel debugging that get installed in the kernel build directory. Debugging environment The following macros manipulate the debugging environment: ddb Switch back to ddb(4). This command is only meaningful when per- forming remote debugging. getsyms Display kldstat information for the target machine and invite user to paste it back in. This is required because gdb does not allow data to be passed to shell scripts. It is necessary for remote debugging and crash dumps; for local memory debugging use kldsyms instead. kldsyms Read in the symbol tables for the debugging machine. This does not work for remote debugging and crash dumps; use getsyms instead. tr interface Debug a remote system via the specified serial or firewire inter- face. tr0 Debug a remote system via serial interface /dev/cuaa0. tr1 Debug a remote system via serial interface /dev/cuaa1. trf Debug a remote system via firewire interface at default port 5556. The commands tr0, tr1 and trf are convenience commands which invoke tr. The current process environment The following macros are convenience functions intended to make things easier than the standard gdb(1) commands. f0 Select stack frame 0 and show assembler-level details. f1 Select stack frame 1 and show assembler-level details. f2 Select stack frame 2 and show assembler-level details. f3 Select stack frame 3 and show assembler-level details. f4 Select stack frame 4 and show assembler-level details. f5 Select stack frame 5 and show assembler-level details. xb Show 12 words in hex, starting at current ebp value. xi List the next 10 instructions from the current eip value. xp Show the register contents and the first four parameters of the current stack frame. xp0 Show the first parameter of current stack frame in various for- mats. xp1 Show the second parameter of current stack frame in various for- mats. xp2 Show the third parameter of current stack frame in various for- mats. xp3 Show the fourth parameter of current stack frame in various for- mats. xp4 Show the fifth parameter of current stack frame in various for- mats. xs Show the last 12 words on stack in hexadecimal. xxp Show the register contents and the first ten parameters. z Single step 1 instruction (over calls) and show next instruction. zs Single step 1 instruction (through calls) and show next instruc- tion. Examining other processes The following macros access other processes. The gdb debugger does not understand the concept of multiple processes, so they effectively bypass the entire gdb environment. btp pid Show a backtrace for the process pid. btpa Show backtraces for all processes in the system. btpp Show a backtrace for the process previously selected with defproc. btr ebp Show a backtrace from the ebp address specified. defproc pid Specify the PID of the process for some other commands in this section. fr frame Show frame frame of the stack of the process previously selected with defproc. pcb proc Show some PCB contents of the process proc. Examining data structures You can use standard gdb(1) commands to look at most data structures. The macros in this section are convenience functions which typically dis- play the data in a more readable format, or which omit less interesting parts of the structure. bp Show information about the buffer header pointed to by the vari- able bp in the current frame. bpd Show the contents (char *) of bp->data in the current frame. bpl Show detailed information about the buffer header (struct bp) pointed at by the local variable bp. bpp bp Show summary information about the buffer header (struct bp) pointed at by the parameter bp. bx Print a number of fields from the buffer header pointed at in by the pointer bp in the current environment. vdev Show some information of the vnode pointed to by the local vari- able vp. Miscellaneous macros checkmem Check unallocated memory for modifications. This assumes that the kernel has been compiled with options DIAGNOSTIC This causes the contents of free memory to be set to 0xdeadc0de. dmesg Print the system message buffer. This corresponds to the dmesg(8) utility. This macro used to be called msgbuf. It can take a very long time over a serial line, and it is even slower via firewire or local memory due to inefficiencies in gdb. When debugging a crash dump or over firewire, it is not necessary to start gdb to access the message buffer: instead, use an appropri- ate variation of dmesg -M /var/crash/vmcore.0 -N kernel.debug dmesg -M /dev/fwmem0.0 -N kernel.debug kldstat Equivalent of the kldstat(8) utility without options. pname Print the command name of the current process. ps Show process status. This corresponds in concept, but not in appearance, to the ps(1) utility. When debugging a crash dump or over firewire, it is not necessary to start gdb to display the ps(1) output: instead, use an appropriate variation of ps -M /var/crash/vmcore.0 -N kernel.debug ps -M /dev/fwmem0.0 -N kernel.debug y Kludge for writing macros. When writing macros, it is convenient to paste them back into the gdb window. Unfortunately, if the macro is already defined, gdb insists on asking Redefine foo? It will not give up until you answer `y'. This command is that answer. It does nothing else except to print a warning message to remind you to remove it again.

SEE ALSO

gdb(1), ps(1), ddb(4), firewire(4), vinumdebug(4), dconschat(8), dmesg(8), fwcontrol(8), kldload(8)

AUTHORS

This man page was written by Greg Lehey <grog@FreeBSD.org>.

BUGS

The gdb(1) debugger was never designed to debug kernels, and it is not a very good match. Many problems exist. The gdb implementation is very inefficient, and many operations are slow. Serial debugging is even slower, and race conditions can make it diffi- cult to run the link at more than 9600 bps. Firewire connections do not have this problem. The debugging macros ``just growed''. In general, the person who wrote them did so while looking for a specific problem, so they may not be gen- eral enough, and they may behave badly when used in ways for which they were not intended, even if those ways make sense. Many of these commands only work on the ia32 architecture. DragonFly 5.3 June 20, 2015 DragonFly 5.3

Search: Section: