GDB Overview

Libraries used by GDB

GDB relies on a number of libraries:

`config/'

Configuration options shared by GDB and all of the libraries it uses. GDB has it's own much more extensive configuration in `gdb/config'.

`readline/'

Contains the -lreadline and -lhistory libraries for command-line processing. The -lreadline library handles command-line editing, terminal interface, keymap interfaces, and file completion; the -lhistory library handles history processing and history substitution using csh-style syntax. For more information, see `readline/doc/hist.texi' and `readline/doc/rlman.texi'.

`bfd/'

BFD is a package which allows applications to use the same routines to operate on object files whatever the object file format. A new object file format can be supported simply by creating a new BFD back end and adding it to the library. BFD is split into two parts: the front end, and the back ends (one for each object file format).

• The front end of BFD provides the interface to the user. It manages memory and various canonical data structures. The front end also decides which back end to use and when to call back end routines.
• The back ends provide BFD its view of the real world. Each back end provides a set of calls which the BFD front end can use to maintain its canonical form. The back ends also may keep around information for their own use, for greater efficiency.

For more information on BFD, see `bfd/doc/bfd.texi'. For more information on the use of BFD in GDB, @xref{BFD support for GDB}.

`opcodes/'

A collection of routines to parse/print machine-language instructions and arguments for a number of processors.

`mmalloc/'

The gnu malloc() library.

`sim/'

Simulators for a number of common microprocessors. Allows GDB to debug machine code for architectures for which no CPU is readily available or which are not yet capable of interacting with GDB directly. Generally used to simulate and/or debug embedded systems.

`texinfo/'

Texinfo is a documentation system that uses a single source file to produce both online information and printed output. Most GDB-related documentation is produced using this system. For more information, see `texinfo/doc/texinfo.texi'.

`libiberty/'

Contains the -liberty library of free software. It is a collection of subroutines used by various GNU programs, typically functions that are included in GNU libc, but not in certain vendor versions of libc. Example functions provided by -liberty:

getopt

get options from command line

obstack

stacks of arbitrarily-sized objects

strerror

error message strings corresponding to errno

strtol

string-to-long conversion

strtoul

string-to-unsigned-long conversion

GDB Directory Structure

The sources to GDB itself are currently stored in four subdirectories, all of which are used to build the final executable:

`gdb/'

The main GDB sources as provided by the FSF. Changes to this directory have been kept as small as possible to minimize the effort of merging them with the FSF sources (though many changes still have been made).

`gdb-next/'

Apple-specific additions to the GDB source base. These will eventually be merged into the `gdb/' directory, but are currently kept separate to make them easier to manage.

`gdb-4.14/'

GDB sources as modified by NeXT for gdb-4.14. These are nearly obsolete, but are kept around until I have merged all of the original NeXT changes into the new GDB source base.

`gdb-next-4.14/'

Apple-specific additions to the (nearly obsolete) GDB 4.14 source base. These are kept around solely for the purpose of building GDB 4.14 binaries when necessary.

Until recently, it was possible to build both GDB 4.17 and the GDB 4.14/4.17 hybrid that shipped with DR1 from the same source tree. GDB 4.17 was built in `gdb' and used files from `gdb-next' and `gdb/', in that order, and GDB 4.14 was built in `gdb-4.14' and used the files from `gdb-next-4.14/', `gdb-next/', `gdb-4.14/', and `gdb/', also in that order.

As of January 8, I have stopped building GDB 4.14 along with GDB 4.17 from the same sources. I suspect GDB 4.14 will no longer build from these sources without modification, although I suspect the necessary changes would be relatively minor.

GDB also uses the following subdirectories:

`include/'

Header files shared by GDB and all of the libraries it uses. These files typically will typically apply to either:

• General operating-system functions (such as symbol reading, IEEE floats, etc.) for which GDB and it's libraries want to have a common interface.
• Interfaces between GDB and one of its libraries (such as `remote-sim.h' and `libiberty.h').

`gdb/config/'

Contains GDB-specific configuration files. For more information @xref{Config}.

Overview of Source Files

Top Level

`main.c'

Contains the GDB top-level interpreter. Parses command-line arguments, performs GDB initialization, and passes control to command-line interpreter.

`maint.c'

Collection of utility functions for viewing/debugging the internal state of GDB.

`top.c'

Top-level routine used by GDB. Evaluates commands, and provides a number of top-level functions and mechanisms to set general purpose variables.

`command.c'

parse and evaluate gdb commands and command documentation

`printcmd.c'

user commands for printing expressions and displaying memory

GDB Targets / Program Control

`target.c'

Defines the target abstraction, used to encapsulate all communications between GDB and a target. See the comments in `target.h' for more information.

`exec.c'

Interface between executable files and the 'target' abstraction. Allows GDB to inspect/analyze executable images, without necessarily having a debuggable process available.

`corefile.c'

Interface between core images and the 'target' abstraction. Allows GDB to inspect/analyze memory and register dumps from corefile images. Not used in GDB 4.14.

`thread.c'

Interface between GDB and multiply-threaded subprocesses. Not currently used by either GDB 4.14 or GDB 4.17.

`fork-child.c'

Code to create an inferior process on UNIX systems.

`infcmd.c'

User-level commands for inspecting/controlling the state of process execution. Commands such as 'step', 'next', 'finish', and 'continue' go here.

`inflow.c'

Handles terminal modes and signal handling for UNIX child processes.

`infrun.c'

Target-independent code to control the execution of an inferior process. Handles breakpoints, signal handling, shared library handling (on some systems), as well as far too many other things. Contains wait_for_inferior, probably the hairiest function in all of GDB.

`inftarg.c'

Interface between the GDB 'target' abstraction and UNIX child processes. Many of the functions in the file are overridden (via macros) in the nextstep-* functions.

Types, Values, and Expressions

A type is the fundamental data structure in GDB for representing type information. Each type structure is associated with a particular object file, with the exception of a few pre-created type structures used for backwards compatibility with other parts of GDB. GDB provides a number of "fundamental" data types; more complex data types can be represented by nesting type structures within each other. See section Types, Values, and Expressions for more information.

A value is the GDB data structure for representing both R- and L-values of any type. A value contains a pointer to a GDB type structure, as well as a region of memory containing the value's contents (for an R-value) or address (for an L-value).

A expression is the GDB data structure for all expressions in all programming languages. Expressions can be parsed and evaluated interactively according to the current language syntax, can be used by breakpoints and watchpoints to compute values, and can cause execution to take place within a target process (by evaluating function expressions). Expressions are parsed, evaluated, and printed using the language-dispatching mechanisms described in `language.c' and section Language-Specific Sources.

GDB source files to manipulate type structures:

`typeprint.c'

Prints type information structures in readable form. Interfaces to the language-specific type printing routines described in section Language-Specific Sources.

`gdbtypes.c'

Fundamental type definitions used by GDB.

GDB source files to manipulate expression structures:

`parse.c'

Parse expressions typed at the command-line into expression. Interfaces to the language-specific expression parsing routines described in section Language-Specific Sources.

`eval.c'

Evaluates expression structures in the current execution context.

`expprint.c'

Prints expression structures in readable (infix) form. Interfaces to the language-specific type printing routines described in section Language-Specific Sources.

GDB source files to manipulate value structures:

`valarith.c'

perform arithmetic operations on values

`valops.c'

perform non-arithmetic operations on values

`valprint.c'

print functions for values

`values.c'

low-level packing/unpacking of value objects to/from raw format

`findvar.c'

resolve variables to their value structures (as appropriate to the current stack environment).

Stack Analysis

`blockframe.c'

machine-independent code to analyze stack frames

`stack.c'

machine-independent stack frame analysis, user-level commands to manage and inspect the stack.

Breakpoints

`breakpoint.c'

Machine-independent breakpoint code. Handles and dispatches all forms of breakpoints, including hardware breakpoints, software breakpoints, hardware and software watchpoints, and shared library breakpoints. Contains top-level commands to set, inspect, and manipulate breakpoints and watchpoints. Provides routine to read memory from inferior, replacing any memory that may have been overwritten by a breakpoint with its saved value.

`mem-break.c'

Implements software breakpoints. To set a breakpoint at a given location, GDB saves the instruction at that location and inserts a software trap instruction in its place.

Symbol File Management

The following files allow GDB to parse and manage symbol information in a variety of formats. For an overview of GDB object file and symbol handling, @xref{Symbol Tables}.

`objfiles.c'

create/destroy/manage objfile structures

`symfile.c'

top-level commands to handle objfiles, also handles overlays (unused)

`symmisc.c'

various objfile and (p)symtab utilities (mainly debugging)

`symtab.c'

basic symbol table utilities (mainly lookup)

`minsyms.c'

manage minimal symbol tables

`buildsym.c'

build complete symbol data structures

The following source files provide symbol-reading interfaces for various file formats. Although all these files are compiled into GDB for Mac OS X, only the first three (`stabsread', `dbxread', and `machoread') are actively used by the rest of GDB.

`stabsread.c'

common stabs parsing routines

`dbxread.c'

read DBX (stabs) symbol files

`machoread.c'

read Mach-O (stabs) symbol files

`nlmread.c'

read Netware NLM symbol files (unused)

`os9kread.c'

read OS9/OS9K symbol files (unused)

`dwarf2read.c'

read DWARF2 symbol files (unused)

`dwarfread.c'

read DWARF symbol files (unused)

`elfread.c'

read ELF symbol files (unused)

`coffread.c'

read COFF symbol files (unused)

`mdebugread.c'

read ECOFF symbol files (unused)

`mipsread.c'

read MIPS symbol files (unused)

Language-Specific Sources

The following files are used to provide language-specific expression evaluation and printing support. The file lang-exp handles expression parsing, lang-typeprint prints human-readable versions of GDB 'type' structures, and lang-valprint prints human-readable versions of GDB 'value' structures, and lang-lang provides general language-specific support functions. For more information on language-specific support in GDB, @xref{Languages}.

C

`c-exp', `c-lang', `c-typeprint', `c-valprint'

C++

`cp-valprint'

Objective-C

`objc-exp', `objc-lang', `objc'

Chill

`ch-exp', `ch-lang', `ch-typeprint', `ch-valprint'

Fortran

`f-exp', `f-lang', `f-typeprint', `f-valprint'

Java

`jv-exp', `jv-lang', `jv-typeprint', `jv-valprint'

Modula II

`m2-exp', `m2-lang', `m2-typeprint', `m2-valprint'

Scheme

`scm-exp', `scm-lang', `scm-valprint'

Kernel Debugging

`remote-kdp.c'

interface gdb 'target' interface to a remote Mac OS X kernel via KDP

`kdp-udp.c'

communications library for KDP

`remote-utils.c'

more serial-line support (unused)

`remote.c'

generic serial-line debugging (unused)

`ser-tcp.c'

treat TCP connection as serial line (unused)

`ser-unix.c'

interface to unix serial ports (unused)

`serial.c'

implement generic serial routines (unused)

Sources Specific to Mac OS X

`nextstep-nat-dyld.c'

handle dyld debugging messages and take action (mainly load symfiles)

`nextstep-nat-inferior.c'

interface between GDB 'target' abstraction and Mach process control functions

`nextstep-nat-mutils.c'

mach functions to read/write memory, other manipulations

`nextstep-nat-sigthread.c'

create/manage thread to detect signals sent to the inferior process

`nextstep-nat-threads.c'

interface gdb 'target' interface to a running Mac OS X process on the same machine

`nextstep-tdep.c'

extra functions needed for all nextstep targets (empty)

`nextstep-xdep.c'

extra functions needed for nextstep hosts (empty)

PowerPC-specific Sources

`ppc-frameinfo.c'

determine/print PPC stack frame info (find prologue, etc)

`ppc-frameops.c'

basic PPC stack frame operations (push dummy, push args, pop, find saved regs)

`ppc-next-tcore.c'

fetch/store PPC registers to/from running Mach thread

`ppc-next-tdep.c'

fetch/store PPC registers from Mach data structure

`ppc-tdep.c'

PPC analysis functions used by rest of GDB

Miscellaneous

`demangle'

Allow user to explicitly select function name demangling style (e.g. 'k+r', 'lucid', 'GNU').

`language'

Multiple-language support for GDB. Contains dispatch tables to the language-specific routines, routines to detect the language of a source file / object module, and explicit commands to print/set the current language environment.

`source'

View and navigate through source files. Also responsible for directory search path mechanisms.

Assorted Utilities

`bcache'

efficiency additions for obstack

`gnu-regex'

regular expression library

`dcache'

caches inferior memory accesses (for remote targets)

`complaints'

error-printing for symbol file reading allows error messages to be printed only once per operation, rather than repeated incessantly

`copying'

prints license/warranty information

`version'

automatically generated, contains version string

`annotate'

convenience functions to print annotations for libgdb

`environ'

utilities to read/modify the process environment

`utils'

Utilities used by GDB. Provides routines to provide formatted output, memory management, and data conversion routines.

Go to the first, previous, next, last section, table of contents.