Format Specifiers

Format Specifiers, i.e dispalying data types in C or C++ Most commonly used ones

Conversion  Argument        Converted      Default  Pre-
 Specifier    Type            Value          Base  cision
   %c       int x          (unsigned char)x
  %lc       wint_t x       wchar_t a[2] = {x}
   %d       int x          (int)x             10     1
  %hd       int x          (short)x           10     1
  %ld       long x         (long)x            10     1
   %e       double x       (double)x          10     6
  %Le       long double x  (long double)x     10     6
   %E       double x       (double)x          10     6
  %LE       long double x  (long double)x     10     6
   %f       double x       (double)x          10     6
  %Lf       long double x  (long double)x     10     6
   %g       double x       (double)x          10     6
  %Lg       long double x  (long double)x     10     6
   %G       double x       (double)x          10     6
  %LG       long double x  (long double)x     10     6
   %i       int x          (int)x             10     1
  %hi       int x          (short)x           10     1
  %li       long x         (long)x            10     1
   %n       int *x
  %hn       short *x
  %ln       long *x
   %o       int x          (unsigned int)x     8     1
  %ho       int x          (unsigned short)x   8     1
  %lo       long x         (unsigned long)x    8     1
   %p       void *x        (void *)x
   %s       char x[]       x[0]...                 large
  %ls       wchar_t x[]    x[0]...                 large
   %u       int x          (unsigned int)x    10     1
  %hu       int x          (unsigned short)x  10     1
  %lu       long x         (unsigned long)x   10     1
   %x       int x          (unsigned int)x    16     1
  %hx       int x          (unsigned short)x  16     1
  %lx       long x         (unsigned long)x   16     1
   %X       int x          (unsigned int)x    16     1
  %hX       int x          (unsigned short)x  16     1
  %lX       long x         (unsigned long)x   16     1
   %%       none           '%'

Enjoy Programming :-)

The Jail Subsystem

Table of Contents

4.1 Architecture

4.2 Restrictions

Evan SarmientoCopyright © 2001 Evan Sarmiento On most UNIX® systems, root has omnipotent power. This promotes insecurity. If an attacker gained root on a system, he would have every function at his fingertips. In FreeBSD there are sysctls which dilute the power of root, in order to minimize the damage caused by an attacker. Specifically, one of these functions is called secure levels. Similarly, another function which is present from FreeBSD 4.0 and onward, is a utility called jail(8). Jail chroots an environment and sets certain restrictions on processes which are forked within the jail. For example, a jailed process cannot affect processes outside the jail, utilize certain system calls, or inflict any damage on the host environment.
Jail is becoming the new security model. People are running potentially vulnerable servers such as Apache, BIND, and sendmail within jails, so that if an attacker gains root within the jail, it is only an annoyance, and not a devastation. This article mainly focuses on the internals (source code) of jail. If you are looking for a how-to on setting up a jail, I suggest you look at my other article in Sys Admin Magazine, May 2001, entitled "Securing FreeBSD using Jail."

4.1 Architecture

Jail consists of two realms: the userland program, jail(8), and the code implemented within the kernel: the jail(2) system call and associated restrictions. I will be discussing the userland program and then how jail is implemented within the kernel.

4.1.1 Userland Code

The source for the userland jail is located in /usr/src/usr.sbin/jail, consisting of one file, jail.c. The program takes these arguments: the path of the jail, hostname, IP address, and the command to be executed.

4.1.1.1 Data Structures

In jail.c, the first thing I would note is the declaration of an important structure struct jail j; which was included from /usr/include/sys/jail.h.
The definition of the jail structure is:

/usr/include/sys/jail.h: 

struct jail {
        u_int32_t       version;
        char            *path;
        char            *hostname;
        u_int32_t       ip_number;
};

As you can see, there is an entry for each of the arguments passed to the jail(8) program, and indeed, they are set during its execution.

/usr/src/usr.sbin/jail/jail.c
char path[PATH_MAX];
...
if (realpath(argv[0], path) == NULL)
    err(1, "realpath: %s", argv[0]);
if (chdir(path) != 0)
    err(1, "chdir: %s", path);
memset(&j, 0, sizeof(j));
j.version = 0;
j.path = path;
j.hostname = argv[1];

4.1.1.2 Networking

One of the arguments passed to the jail(8) program is an IP address with which the jail can be accessed over the network. jail(8) translates the IP address given into host byte order and then stores it in j (the jail structure).

/usr/src/usr.sbin/jail/jail.c:
struct in_addr in; 
... 
if (inet_aton(argv[2], &in) == 0)
    errx(1, "Could not make sense of ip-number: %s", argv[2]);
j.ip_number = ntohl(in.s_addr);

The inet_aton(3) function "interprets the specified character string as an Internet address, placing the address into the structure provided." The ip_number member in the jail structure is set only when the IP address placed onto the in structure by inet_aton(3) is translated into host byte order by ntohl(3).

4.1.1.3 Jailing The Process

Finally, the userland program jails the process. Jail now becomes an imprisoned process itself and then executes the command given using execv(3).

/usr/src/usr.sbin/jail/jail.c
i = jail(&j); 
... 
if (execv(argv[3], argv + 3) != 0)
    err(1, "execv: %s", argv[3]);

As you can see, the jail() function is called, and its argument is the jail structure which has been filled with the arguments given to the program. Finally, the program you specify is executed. I will now discuss how jail is implemented within the kernel.

4.1.2 Kernel Space

We will now be looking at the file /usr/src/sys/kern/kern_jail.c. This is the file where the jail(2) system call, appropriate sysctls, and networking functions are defined.

4.1.2.1 sysctls

In kern_jail.c, the following sysctls are defined:

/usr/src/sys/kern/kern_jail.c:

int     jail_set_hostname_allowed = 1;
SYSCTL_PROC(_security_jail, OID_AUTO, set_hostname_allowed, CTLFLAG_RW,
    &jail_set_hostname_allowed, 0,
    "Processes in jail can set their hostnames");

int     jail_socket_unixiproute_only = 1;
SYSCTL_PROC(_security_jail, OID_AUTO, socket_unixiproute_only, CTLFLAG_RW,
    &jail_socket_unixiproute_only, 0,
    "Processes in jail are limited to creating UNIX/IPv4/route sockets only");

int     jail_sysvipc_allowed = 0;
SYSCTL_PROC(_security_jail, OID_AUTO, sysvipc_allowed, CTLFLAG_RW,
    &jail_sysvipc_allowed, 0,
    "Processes in jail can use System V IPC primitives");

static int jail_enforce_statfs = 2;
SYSCTL_PROC(_security_jail, OID_AUTO, enforce_statfs, CTLFLAG_RW,
    &jail_enforce_statfs, 0,
    "Processes in jail cannot see all mounted file systems");

int    jail_allow_raw_sockets = 0;
SYSCTL_PROC(_security_jail, OID_AUTO, allow_raw_sockets, CTLFLAG_RW,
    &jail_allow_raw_sockets, 0,
    "Prison root can create raw sockets");

int    jail_chflags_allowed = 0;
SYSCTL_PROC(_security_jail, OID_AUTO, chflags_allowed, CTLFLAG_RW,
    &jail_chflags_allowed, 0,
    "Processes in jail can alter system file flags");

int     jail_mount_allowed = 0;
SYSCTL_PROC(_security_jail, OID_AUTO, mount_allowed, CTLFLAG_RW,
    &jail_mount_allowed, 0,
    "Processes in jail can mount/unmount jail-friendly file systems");

Each of these sysctls can be accessed by the user through the sysctl(8) program. Throughout the kernel, these specific sysctls are recognized by their name. For example, the name of the first sysctl is security.jail.set_hostname_allowed.

4.1.2.2 jail(2) system call

Like all system calls, the jail(2) system call takes two arguments, struct thread *td and struct jail_args *uap. td is a pointer to the thread structure which describes the calling thread. In this context, uap is a pointer to the structure in which a pointer to the jail structure passed by the userland jail.c is contained. When I described the userland program before, you saw that the jail(2) system call was given a jail structure as its own argument.

/usr/src/sys/kern/kern_jail.c:
/*
 * struct jail_args {
 *  struct jail *jail;
 * };
 */ 
int 
jail(struct thread *td, struct jail_args *uap)

Therefore, uap->jail can be used to access the jail structure which was passed to the system call. Next, the system call copies the jail structure into kernel space using the copyin(9) function. copyin(9) takes three arguments: the address of the data which is to be copied into kernel space, uap->jail, where to store it, j and the size of the storage. The jail structure pointed by uap->jail is copied into kernel space and is stored in another jail structure, j.

/usr/src/sys/kern/kern_jail.c: 
error = copyin(uap->jail, &j, sizeof(j));

There is another important structure defined in jail.h. It is the prison structure. The prison structure is used exclusively within kernel space. Here is the definition of the prison structure.

/usr/include/sys/jail.h:
struct prison {
        LIST_ENTRY(prison) pr_list;                     /* (a) all prisons */
        int              pr_id;                         /* (c) prison id */
        int              pr_ref;                        /* (p) refcount */
        char             pr_path[MAXPATHLEN];           /* (c) chroot path */
        struct vnode    *pr_root;                       /* (c) vnode to rdir */
        char             pr_host[MAXHOSTNAMELEN];       /* (p) jail hostname */
        u_int32_t        pr_ip;                         /* (c) ip addr host */
        void            *pr_linux;                      /* (p) linux abi */
        int              pr_securelevel;                /* (p) securelevel */
        struct task      pr_task;                       /* (d) destroy task */
        struct mtx       pr_mtx;
      void            **pr_slots;                     /* (p) additional data */
};

The jail(2) system call then allocates memory for a prison structure and copies data between the jail and prison structure.

/usr/src/sys/kern/kern_jail.c:
MALLOC(pr, struct prison *, sizeof(*pr), M_PRISON, M_WAITOK | M_ZERO);
...
error = copyinstr(j.path, &pr->pr_path, sizeof(pr->pr_path), 0);
if (error)
    goto e_killmtx;
...
error = copyinstr(j.hostname, &pr->pr_host, sizeof(pr->pr_host), 0);
if (error)
     goto e_dropvnref;
pr->pr_ip = j.ip_number;

Next, we will discuss another important system call jail_attach(2), which implements the function to put a process into the jail.

/usr/src/sys/kern/kern_jail.c:
/*
 * struct jail_attach_args {
 *      int jid;
 * };
 */
int
jail_attach(struct thread *td, struct jail_attach_args *uap)

This system call makes the changes that can distinguish a jailed process from those unjailed ones. To understand what jail_attach(2) does for us, certain background information is needed.
On FreeBSD, each kernel visible thread is identified by its thread structure, while the processes are described by their proc structures. You can find the definitions of the thread and proc structure in /usr/include/sys/proc.h. For example, the td argument in any system call is actually a pointer to the calling thread's thread structure, as stated before. The td_proc member in the thread structure pointed by td is a pointer to the proc structure which represents the process that contains the thread represented by td. The proc structure contains members which can describe the owner's identity(p_ucred), the process resource limits(p_limit), and so on. In the ucred structure pointed by p_ucred member in the proc structure, there is a pointer to the prison structure(cr_prison).

/usr/include/sys/proc.h: 
struct thread {
    ...
    struct proc *td_proc;
    ...
};
struct proc { 
    ...
    struct ucred *p_ucred; 
    ...
};
/usr/include/sys/ucred.h
struct ucred {
    ...
    struct prison *cr_prison;
    ...
};

In kern_jail.c, the function jail() then calls function jail_attach() with a given jid. And jail_attach() calls function change_root() to change the root directory of the calling process. The jail_attach() then creates a new ucred structure, and attaches the newly created ucred structure to the calling process after it has successfully attached the prison structure to the ucred structure. From then on, the calling process is recognized as jailed. When the kernel routine jailed() is called in the kernel with the newly created ucred structure as its argument, it returns 1 to tell that the credential is connected with a jail. The public ancestor process of all the process forked within the jail, is the process which runs jail(8), as it calls the jail(2) system call. When a program is executed through execve(2), it inherits the jailed property of its parent's ucred structure, therefore it has a jailed ucred structure.

/usr/src/sys/kern/kern_jail.c
int
jail(struct thread *td, struct jail_args *uap)
{
...
    struct jail_attach_args jaa;
...
    error = jail_attach(td, &jaa);
    if (error)
        goto e_dropprref;
...
}

int
jail_attach(struct thread *td, struct jail_attach_args *uap)
{
    struct proc *p;
    struct ucred *newcred, *oldcred;
    struct prison *pr;
...
    p = td->td_proc;
...
    pr = prison_find(uap->jid);
...
    change_root(pr->pr_root, td);
...
    newcred->cr_prison = pr;
    p->p_ucred = newcred;
...
}

When a process is forked from its parent process, the fork(2) system call uses crhold() to maintain the credential for the newly forked process. It inherently keep the newly forked child's credential consistent with its parent, so the child process is also jailed.

/usr/src/sys/kern/kern_fork.c:
p2->p_ucred = crhold(td->td_ucred);
...
td2->td_ucred = crhold(p2->p_ucred);

What is a Jail

What is a Jail

BSD-like operating systems have had chroot(2) since the time of 4.2BSD. The chroot(8) utility can be used to change the root directory of a set of processes, creating a safe environment, separate from the rest of the system. Processes created in the chrooted environment can not access files or resources outside of it. For that reason, compromising a service running in a chrooted environment should not allow the attacker to compromise the entire system. The chroot(8) utility is good for easy tasks, which do not require a lot of flexibility or complex and advanced features. Since the inception of the chroot concept, however, many ways have been found to escape from a chrooted environment and, although they have been fixed in modern versions of the FreeBSD kernel, it was clear that chroot(2) was not the ideal solution for securing services. A new subsystem had to be implemented.
This is one of the main reasons why jails were developed.
Jails improve on the concept of the traditional chroot(2) environment, in several ways. In a traditional chroot(2) environment, processes are only limited in the part of the file system they can access. The rest of the system resources (like the set of system users, the running processes, or the networking subsystem) are shared by the chrooted processes and the processes of the host system. Jails expand this model by virtualizing not only access to the file system, but also the set of users, the networking subsystem of the FreeBSD kernel and a few other things. A more complete set of fine-grained controls available for tuning the access of a jailed environment is described in Section 16.5.
A jail is characterized by four elements:

• A directory subtree -- the starting point from which a jail is entered. Once inside the jail, a process is not permitted to escape outside of this subtree. Traditional security issues which plagued the original chroot(2) design will not affect FreeBSD jails.
  
• A hostname -- the hostname which will be used within the jail. Jails are mainly used for hosting network services, therefore having a descriptive hostname for each jail can really help the system administrator.
  
• An IP address -- this will be assigned to the jail and cannot be changed in any way during the jail's life span. The IP address of a jail is usually an alias address for an existing network interface, but this is not strictly necessary.
  
• A command -- the path name of an executable to run inside the jail. This is relative to the root directory of the jail environment, and may vary a lot, depending on the type of the specific jail environment.
  

Apart from these, jails can have their own set of users and their own root user. Naturally, the powers of the root user are limited within the jail environment and, from the point of view of the host system, the jail root user is not an omnipotent user. In addition, the root user of a jail is not allowed to perform critical operations to the system outside of the associated jail(8) environment.

Creating and Controlling Jails

Some administrators divide jails into the following two types: “complete” jails, which resemble a real FreeBSD system, and “service” jails, dedicated to one application or service, possibly running with privileges. This is only a conceptual division and the process of building a jail is not affected by it. The jail(8) manual page is quite clear about the procedure for building a jail:

# setenv D /here/is/the/jail
# mkdir -p $D 
# cd /usr/src
# make buildworld 
# make installworld DESTDIR=$D 
# make distribution DESTDIR=$D 
# mount -t devfs devfs $D/dev 

Selecting a location for a jail is the best starting point. This is where the jail will physically reside within the file system of the jail's host. A good choice can be /usr/jail/jailname, where jailname is the hostname identifying the jail. The /usr/ file system usually has enough space for the jail file system, which for “complete” jails is, essentially, a replication of every file present in a default installation of the FreeBSD base system.

If you have already rebuilt your userland using make world or make buildworld, you can skip this step and install your existing userland into the new jail.

This command will populate the directory subtree chosen as jail's physical location on the file system with the necessary binaries, libraries, manual pages and so on.

The distribution target for make installs every needed configuration file. In simple words, it installs every installable file of /usr/src/etc/ to the /etc directory of the jail environment: $D/etc/.

Mounting the devfs(8) file system inside a jail is not required. On the other hand, any, or almost any application requires access to at least one device, depending on the purpose of the given application. It is very important to control access to devices from inside a jail, as improper settings could permit an attacker to do nasty things in the jail. Control over devfs(8) is managed through rulesets which are described in the devfs(8) and devfs.conf(5) manual pages.

Once a jail is installed, it can be started by using the jail(8) utility. The jail(8) utility takes four mandatory arguments which are described in the Section 16.3.1. Other arguments may be specified too, e.g., to run the jailed process with the credentials of a specific user. The command argument depends on the type of the jail; for a virtual system, /etc/rc is a good choice, since it will replicate the startup sequence of a real FreeBSD system. For a service jail, it depends on the service or application that will run within the jail.
Jails are often started at boot time and the FreeBSD rc mechanism provides an easy way to do this.

1. A list of the jails which are enabled to start at boot time should be added to the rc.conf(5) file:
   

   jail_enable="YES"   # Set to NO to disable starting of any jails
   jail_list="www"     # Space separated list of names of jails

   Note: Jail names in jail_list should contain alphanumeric characters only.
   

2. For each jail listed in jail_list, a group of rc.conf(5) settings, which describe the particular jail, should be added:
   

   jail_www_rootdir="/usr/jail/www"     # jail's root directory
   jail_www_hostname="www.example.org"  # jail's hostname
   jail_www_ip="192.168.0.10"           # jail's IP address
   jail_www_devfs_enable="YES"          # mount devfs in the jail
   jail_www_devfs_ruleset="www_ruleset" # devfs ruleset to apply to jail

   The default startup of jails configured in rc.conf(5), will run the /etc/rc script of the jail, which assumes the jail is a complete virtual system. For service jails, the default startup command of the jail should be changed, by setting the jail_jailname_exec_start option appropriately.
   

   Note: For a full list of available options, please see the rc.conf(5) manual page.
   

The /etc/rc.d/jail script can be used to start or stop a jail by hand, if an entry for it exists in rc.conf:

# /etc/rc.d/jail start www
# /etc/rc.d/jail stop www

A clean way to shut down a jail(8) is not available at the moment. This is because commands normally used to accomplish a clean system shutdown cannot be used inside a jail. The best way to shut down a jail is to run the following command from within the jail itself or using the jexec(8) utility from outside the jail:

# sh /etc/rc.shutdown

More information about this can be found in the jail(8) manual page.

Debugging With GDB

This file documents the gnu debugger gdb.
This is the Tenth Edition, of Debugging with gdb: the gnu Source-Level Debugger for gdb (GDB) Version 7.3.50.20111125.
Copyright © 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with the Invariant Sections being “Free Software” and “Free Software Needs Free Documentation”, with the Front-Cover Texts being “A GNU Manual,” and with the Back-Cover Texts as in (a) below.
(a) The FSF's Back-Cover Text is: “You are free to copy and modify this GNU Manual. Buying copies from GNU Press supports the FSF in developing GNU and promoting software freedom.”

---

Next: Summary, Previous: (dir), Up: (dir)

Debugging with gdb

This file describes gdb, the gnu symbolic debugger.
This is the Tenth Edition, for gdb (GDB) Version 7.3.50.20111125.
Copyright (C) 1988-2010 Free Software Foundation, Inc.
This edition of the GDB manual is dedicated to the memory of Fred Fish. Fred was a long-standing contributor to GDB and to Free software in general. We will miss him.

• Summary: Summary of gdb
• Sample Session: A sample gdb session
• Invocation: Getting in and out of gdb
• Commands: gdb commands
• Running: Running programs under gdb
• Stopping: Stopping and continuing
• Reverse Execution: Running programs backward
• Process Record and Replay: Recording inferior's execution and replaying it
• Stack: Examining the stack
• Source: Examining source files
• Data: Examining data
• Optimized Code: Debugging optimized code
• Macros: Preprocessor Macros
• Tracepoints: Debugging remote targets non-intrusively
• Overlays: Debugging programs that use overlays
• Languages: Using gdb with different languages
• Symbols: Examining the symbol table
• Altering: Altering execution
• GDB Files: gdb files
• Targets: Specifying a debugging target
• Remote Debugging: Debugging remote programs
• Configurations: Configuration-specific information
• Controlling GDB: Controlling gdb
• Extending GDB: Extending gdb
• Interpreters: Command Interpreters
• TUI: gdb Text User Interface
• Emacs: Using gdb under gnu Emacs
• GDB/MI: gdb's Machine Interface.
• Annotations: gdb's annotation interface.
• JIT Interface: Using the JIT debugging interface.
• GDB Bugs: Reporting bugs in gdb
• Command Line Editing: Command Line Editing
• Using History Interactively: Using History Interactively
• In Memoriam: In Memoriam
• Formatting Documentation: How to format and print gdb documentation
• Installing GDB: Installing GDB
• Maintenance Commands: Maintenance Commands
• Remote Protocol: GDB Remote Serial Protocol
• Agent Expressions: The GDB Agent Expression Mechanism
• Target Descriptions: How targets can describe themselves to gdb
• Operating System Information: Getting additional information from the operating system
• Trace File Format: GDB trace file format
• Index Section Format: .gdb_index section format
• Copying: GNU General Public License says how you can copy and share GDB
• GNU Free Documentation License: The license for this documentation
• Index: Index

Table of Contents

• Debugging with gdb
• Summary of gdb
  • Free Software
  • Free Software Needs Free Documentation
  • Contributors to gdb
• 1 A Sample gdb Session
• 2 Getting In and Out of gdb
  • 2.1 Invoking gdb
    • 2.1.1 Choosing Files
    • 2.1.2 Choosing Modes
    • 2.1.3 What gdb Does During Startup
  • 2.2 Quitting gdb
  • 2.3 Shell Commands
  • 2.4 Logging Output
• 3 gdb Commands
  • 3.1 Command Syntax
  • 3.2 Command Completion
  • 3.3 Getting Help
• 4 Running Programs Under gdb
  • 4.1 Compiling for Debugging
  • 4.2 Starting your Program
  • 4.3 Your Program's Arguments
  • 4.4 Your Program's Environment
  • 4.5 Your Program's Working Directory
  • 4.6 Your Program's Input and Output
  • 4.7 Debugging an Already-running Process
  • 4.8 Killing the Child Process
  • 4.9 Debugging Multiple Inferiors and Programs
  • 4.10 Debugging Programs with Multiple Threads
  • 4.11 Debugging Forks
  • 4.12 Setting a Bookmark to Return to Later
    • 4.12.1 A Non-obvious Benefit of Using Checkpoints
• 5 Stopping and Continuing
  • 5.1 Breakpoints, Watchpoints, and Catchpoints
    • 5.1.1 Setting Breakpoints
    • 5.1.2 Setting Watchpoints
    • 5.1.3 Setting Catchpoints
    • 5.1.4 Deleting Breakpoints
    • 5.1.5 Disabling Breakpoints
    • 5.1.6 Break Conditions
    • 5.1.7 Breakpoint Command Lists
    • 5.1.8 How to save breakpoints to a file
    • 5.1.9 “Cannot insert breakpoints”
    • 5.1.10 “Breakpoint address adjusted...”
  • 5.2 Continuing and Stepping
  • 5.3 Skipping Over Functions and Files
  • 5.4 Signals
  • 5.5 Stopping and Starting Multi-thread Programs
    • 5.5.1 All-Stop Mode
    • 5.5.2 Non-Stop Mode
    • 5.5.3 Background Execution
    • 5.5.4 Thread-Specific Breakpoints
    • 5.5.5 Interrupted System Calls
    • 5.5.6 Observer Mode
• 6 Running programs backward
• 7 Recording Inferior's Execution and Replaying It
• 8 Examining the Stack
  • 8.1 Stack Frames
  • 8.2 Backtraces
  • 8.3 Selecting a Frame
  • 8.4 Information About a Frame
• 9 Examining Source Files
  • 9.1 Printing Source Lines
  • 9.2 Specifying a Location
  • 9.3 Editing Source Files
    • 9.3.1 Choosing your Editor
  • 9.4 Searching Source Files
  • 9.5 Specifying Source Directories
  • 9.6 Source and Machine Code
• 10 Examining Data
  • 10.1 Expressions
  • 10.2 Ambiguous Expressions
  • 10.3 Program Variables
  • 10.4 Artificial Arrays
  • 10.5 Output Formats
  • 10.6 Examining Memory
  • 10.7 Automatic Display
  • 10.8 Print Settings
  • 10.9 Pretty Printing
    • 10.9.1 Pretty-Printer Introduction
    • 10.9.2 Pretty-Printer Example
    • 10.9.3 Pretty-Printer Commands
  • 10.10 Value History
  • 10.11 Convenience Variables
  • 10.12 Registers
  • 10.13 Floating Point Hardware
  • 10.14 Vector Unit
  • 10.15 Operating System Auxiliary Information
  • 10.16 Memory Region Attributes
    • 10.16.1 Attributes
      • 10.16.1.1 Memory Access Mode
      • 10.16.1.2 Memory Access Size
      • 10.16.1.3 Data Cache
    • 10.16.2 Memory Access Checking
  • 10.17 Copy Between Memory and a File
  • 10.18 How to Produce a Core File from Your Program
  • 10.19 Character Sets
  • 10.20 Caching Data of Remote Targets
  • 10.21 Search Memory
• 11 Debugging Optimized Code
  • 11.1 Inline Functions
  • 11.2 Tail Call Frames
• 12 C Preprocessor Macros
• 13 Tracepoints
  • 13.1 Commands to Set Tracepoints
    • 13.1.1 Create and Delete Tracepoints
    • 13.1.2 Enable and Disable Tracepoints
    • 13.1.3 Tracepoint Passcounts
    • 13.1.4 Tracepoint Conditions
    • 13.1.5 Trace State Variables
    • 13.1.6 Tracepoint Action Lists
    • 13.1.7 Listing Tracepoints
    • 13.1.8 Listing Static Tracepoint Markers
    • 13.1.9 Starting and Stopping Trace Experiments
    • 13.1.10 Tracepoint Restrictions
  • 13.2 Using the Collected Data
    • 13.2.1 tfind n
    • 13.2.2 tdump
    • 13.2.3 save tracepoints filename
  • 13.3 Convenience Variables for Tracepoints
  • 13.4 Using Trace Files
• 14 Debugging Programs That Use Overlays
  • 14.1 How Overlays Work
  • 14.2 Overlay Commands
  • 14.3 Automatic Overlay Debugging
  • 14.4 Overlay Sample Program
• 15 Using gdb with Different Languages
  • 15.1 Switching Between Source Languages
    • 15.1.1 List of Filename Extensions and Languages
    • 15.1.2 Setting the Working Language
    • 15.1.3 Having gdb Infer the Source Language
  • 15.2 Displaying the Language
  • 15.3 Type and Range Checking
    • 15.3.1 An Overview of Type Checking
    • 15.3.2 An Overview of Range Checking
  • 15.4 Supported Languages
    • 15.4.1 C and C++
      • 15.4.1.1 C and C++ Operators
      • 15.4.1.2 C and C++ Constants
      • 15.4.1.3 C++ Expressions
      • 15.4.1.4 C and C++ Defaults
      • 15.4.1.5 C and C++ Type and Range Checks
      • 15.4.1.6 gdb and C
      • 15.4.1.7 gdb Features for C++
      • 15.4.1.8 Decimal Floating Point format
    • 15.4.2 D
    • 15.4.3 Objective-C
      • 15.4.3.1 Method Names in Commands
      • 15.4.3.2 The Print Command With Objective-C
    • 15.4.4 OpenCL C
      • 15.4.4.1 OpenCL C Datatypes
      • 15.4.4.2 OpenCL C Expressions
      • 15.4.4.3 OpenCL C Operators
    • 15.4.5 Fortran
      • 15.4.5.1 Fortran Operators and Expressions
      • 15.4.5.2 Fortran Defaults
      • 15.4.5.3 Special Fortran Commands
    • 15.4.6 Pascal
    • 15.4.7 Modula-2
      • 15.4.7.1 Operators
      • 15.4.7.2 Built-in Functions and Procedures
      • 15.4.7.3 Constants
      • 15.4.7.4 Modula-2 Types
      • 15.4.7.5 Modula-2 Defaults
      • 15.4.7.6 Deviations from Standard Modula-2
      • 15.4.7.7 Modula-2 Type and Range Checks
      • 15.4.7.8 The Scope Operators :: and .
      • 15.4.7.9 gdb and Modula-2
    • 15.4.8 Ada
      • 15.4.8.1 Introduction
      • 15.4.8.2 Omissions from Ada
      • 15.4.8.3 Additions to Ada
      • 15.4.8.4 Stopping at the Very Beginning
      • 15.4.8.5 Extensions for Ada Tasks
      • 15.4.8.6 Tasking Support when Debugging Core Files
      • 15.4.8.7 Tasking Support when using the Ravenscar Profile
      • 15.4.8.8 Known Peculiarities of Ada Mode
  • 15.5 Unsupported Languages
• 16 Examining the Symbol Table
• 17 Altering Execution
  • 17.1 Assignment to Variables
  • 17.2 Continuing at a Different Address
  • 17.3 Giving your Program a Signal
  • 17.4 Returning from a Function
  • 17.5 Calling Program Functions
  • 17.6 Patching Programs
• 18 gdb Files
  • 18.1 Commands to Specify Files
  • 18.2 Debugging Information in Separate Files
  • 18.3 Index Files Speed Up gdb
  • 18.4 Errors Reading Symbol Files
  • 18.5 GDB Data Files
• 19 Specifying a Debugging Target
  • 19.1 Active Targets
  • 19.2 Commands for Managing Targets
  • 19.3 Choosing Target Byte Order
• 20 Debugging Remote Programs
  • 20.1 Connecting to a Remote Target
  • 20.2 Sending files to a remote system
  • 20.3 Using the gdbserver Program
    • 20.3.1 Running gdbserver
      • 20.3.1.1 Attaching to a Running Program
      • 20.3.1.2 Multi-Process Mode for gdbserver
      • 20.3.1.3 TCP port allocation lifecycle of gdbserver
      • 20.3.1.4 Other Command-Line Arguments for gdbserver
    • 20.3.2 Connecting to gdbserver
    • 20.3.3 Monitor Commands for gdbserver
    • 20.3.4 Tracepoints support in gdbserver
  • 20.4 Remote Configuration
  • 20.5 Implementing a Remote Stub
    • 20.5.1 What the Stub Can Do for You
    • 20.5.2 What You Must Do for the Stub
    • 20.5.3 Putting it All Together
• 21 Configuration-Specific Information
  • 21.1 Native
    • 21.1.1 HP-UX
    • 21.1.2 BSD libkvm Interface
    • 21.1.3 SVR4 Process Information
    • 21.1.4 Features for Debugging djgpp Programs
    • 21.1.5 Features for Debugging MS Windows PE Executables
      • 21.1.5.1 Support for DLLs without Debugging Symbols
      • 21.1.5.2 DLL Name Prefixes
      • 21.1.5.3 Working with Minimal Symbols
    • 21.1.6 Commands Specific to gnu Hurd Systems
    • 21.1.7 QNX Neutrino
    • 21.1.8 Darwin
  • 21.2 Embedded Operating Systems
    • 21.2.1 Using gdb with VxWorks
      • 21.2.1.1 Connecting to VxWorks
      • 21.2.1.2 VxWorks Download
      • 21.2.1.3 Running Tasks
  • 21.3 Embedded Processors
    • 21.3.1 ARM
    • 21.3.2 Renesas M32R/D and M32R/SDI
    • 21.3.3 M68k
    • 21.3.4 MicroBlaze
    • 21.3.5 MIPS Embedded
    • 21.3.6 OpenRISC 1000
    • 21.3.7 PowerPC Embedded
    • 21.3.8 HP PA Embedded
    • 21.3.9 Tsqware Sparclet
      • 21.3.9.1 Setting File to Debug
      • 21.3.9.2 Connecting to Sparclet
      • 21.3.9.3 Sparclet Download
      • 21.3.9.4 Running and Debugging
    • 21.3.10 Fujitsu Sparclite
    • 21.3.11 Zilog Z8000
    • 21.3.12 Atmel AVR
    • 21.3.13 CRIS
    • 21.3.14 Renesas Super-H
  • 21.4 Architectures
    • 21.4.1 x86 Architecture-specific Issues
    • 21.4.2 A29K
    • 21.4.3 Alpha
    • 21.4.4 MIPS
    • 21.4.5 HPPA
    • 21.4.6 Cell Broadband Engine SPU architecture
    • 21.4.7 PowerPC
• 22 Controlling gdb
  • 22.1 Prompt
  • 22.2 Command Editing
  • 22.3 Command History
  • 22.4 Screen Size
  • 22.5 Numbers
  • 22.6 Configuring the Current ABI
  • 22.7 Optional Warnings and Messages
  • 22.8 Optional Messages about Internal Happenings
  • 22.9 Other Miscellaneous Settings
• 23 Extending gdb
  • 23.1 Canned Sequences of Commands
    • 23.1.1 User-defined Commands
    • 23.1.2 User-defined Command Hooks
    • 23.1.3 Command Files
    • 23.1.4 Commands for Controlled Output
  • 23.2 Scripting gdb using Python
    • 23.2.1 Python Commands
    • 23.2.2 Python API
      • 23.2.2.1 Basic Python
      • 23.2.2.2 Exception Handling
      • 23.2.2.3 Values From Inferior
      • 23.2.2.4 Types In Python
      • 23.2.2.5 Pretty Printing API
      • 23.2.2.6 Selecting Pretty-Printers
      • 23.2.2.7 Writing a Pretty-Printer
      • 23.2.2.8 Inferiors In Python
      • 23.2.2.9 Events In Python
      • 23.2.2.10 Threads In Python
      • 23.2.2.11 Commands In Python
      • 23.2.2.12 Parameters In Python
      • 23.2.2.13 Writing new convenience functions
      • 23.2.2.14 Program Spaces In Python
      • 23.2.2.15 Objfiles In Python
      • 23.2.2.16 Accessing inferior stack frames from Python.
      • 23.2.2.17 Accessing frame blocks from Python.
      • 23.2.2.18 Python representation of Symbols.
      • 23.2.2.19 Symbol table representation in Python.
      • 23.2.2.20 Manipulating breakpoints using Python
      • 23.2.2.21 Python representation of lazy strings.
    • 23.2.3 Auto-loading
      • 23.2.3.1 The objfile-gdb.py file
      • 23.2.3.2 The .debug_gdb_scripts section
      • 23.2.3.3 Which flavor to choose?
    • 23.2.4 Python modules
      • 23.2.4.1 gdb.printing
      • 23.2.4.2 gdb.types
      • 23.2.4.3 gdb.prompt
  • 23.3 Creating new spellings of existing commands
• 24 Command Interpreters
• 25 gdb Text User Interface
  • 25.1 TUI Overview
  • 25.2 TUI Key Bindings
  • 25.3 TUI Single Key Mode
  • 25.4 TUI-specific Commands
  • 25.5 TUI Configuration Variables
• 26 Using gdb under gnu Emacs
• 27 The gdb/mi Interface
  • Function and Purpose
  • Notation and Terminology
  • 27.1 gdb/mi General Design
    • 27.1.1 Context management
    • 27.1.2 Asynchronous command execution and non-stop mode
    • 27.1.3 Thread groups
  • 27.2 gdb/mi Command Syntax
    • 27.2.1 gdb/mi Input Syntax
    • 27.2.2 gdb/mi Output Syntax
  • 27.3 gdb/mi Compatibility with CLI
  • 27.4 gdb/mi Development and Front Ends
  • 27.5 gdb/mi Output Records
    • 27.5.1 gdb/mi Result Records
    • 27.5.2 gdb/mi Stream Records
    • 27.5.3 gdb/mi Async Records
    • 27.5.4 gdb/mi Frame Information
    • 27.5.5 gdb/mi Thread Information
    • 27.5.6 gdb/mi Ada Exception Information
  • 27.6 Simple Examples of gdb/mi Interaction
  • 27.7 gdb/mi Command Description Format
  • 27.8 gdb/mi Breakpoint Commands
  • 27.9 gdb/mi Program Context
  • 27.10 gdb/mi Thread Commands
  • 27.11 gdb/mi Ada Tasking Commands
  • 27.12 gdb/mi Program Execution
  • 27.13 gdb/mi Stack Manipulation Commands
  • 27.14 gdb/mi Variable Objects
  • 27.15 gdb/mi Data Manipulation
  • 27.16 gdb/mi Tracepoint Commands
  • 27.17 gdb/mi Symbol Query Commands
  • 27.18 gdb/mi File Commands
  • 27.19 gdb/mi Target Manipulation Commands
  • 27.20 gdb/mi File Transfer Commands
  • 27.21 Miscellaneous gdb/mi Commands
• 28 gdb Annotations
  • 28.1 What is an Annotation?
  • 28.2 The Server Prefix
  • 28.3 Annotation for gdb Input
  • 28.4 Errors
  • 28.5 Invalidation Notices
  • 28.6 Running the Program
  • 28.7 Displaying Source
• 29 JIT Compilation Interface
  • 29.1 JIT Declarations
  • 29.2 Registering Code
  • 29.3 Unregistering Code
  • 29.4 Custom Debug Info
    • 29.4.1 Using JIT Debug Info Readers
    • 29.4.2 Writing JIT Debug Info Readers
• 30 Reporting Bugs in gdb
  • 30.1 Have You Found a Bug?
  • 30.2 How to Report Bugs
• 31 Command Line Editing
  • 31.1 Introduction to Line Editing
  • 31.2 Readline Interaction
    • 31.2.1 Readline Bare Essentials
    • 31.2.2 Readline Movement Commands
    • 31.2.3 Readline Killing Commands
    • 31.2.4 Readline Arguments
    • 31.2.5 Searching for Commands in the History
  • 31.3 Readline Init File
    • 31.3.1 Readline Init File Syntax
    • 31.3.2 Conditional Init Constructs
    • 31.3.3 Sample Init File
  • 31.4 Bindable Readline Commands
    • 31.4.1 Commands For Moving
    • 31.4.2 Commands For Manipulating The History
    • 31.4.3 Commands For Changing Text
    • 31.4.4 Killing And Yanking
    • 31.4.5 Specifying Numeric Arguments
    • 31.4.6 Letting Readline Type For You
    • 31.4.7 Keyboard Macros
    • 31.4.8 Some Miscellaneous Commands
  • 31.5 Readline vi Mode
• 32 Using History Interactively
  • 32.1 History Expansion
    • 32.1.1 Event Designators
    • 32.1.2 Word Designators
    • 32.1.3 Modifiers
• Appendix A In Memoriam
• Appendix B Formatting Documentation
• Appendix C Installing gdb
  • C.1 Requirements for Building gdb
  • C.2 Invoking the gdb configure Script
  • C.3 Compiling gdb in Another Directory
  • C.4 Specifying Names for Hosts and Targets
  • C.5 configure Options
  • C.6 System-wide configuration and settings
• Appendix D Maintenance Commands
• Appendix E gdb Remote Serial Protocol
  • E.1 Overview
  • E.2 Packets
  • E.3 Stop Reply Packets
  • E.4 General Query Packets
  • E.5 Architecture-Specific Protocol Details
    • E.5.1 ARM
      • E.5.1.1 Breakpoint Kinds
    • E.5.2 MIPS
      • E.5.2.1 Register Packet Format
  • E.6 Tracepoint Packets
    • E.6.1 Relocate instruction reply packet
  • E.7 Host I/O Packets
  • E.8 Interrupts
  • E.9 Notification Packets
  • E.10 Remote Protocol Support for Non-Stop Mode
  • E.11 Packet Acknowledgment
  • E.12 Examples
  • E.13 File-I/O Remote Protocol Extension
    • E.13.1 File-I/O Overview
    • E.13.2 Protocol Basics
    • E.13.3 The F Request Packet
    • E.13.4 The F Reply Packet
    • E.13.5 The `Ctrl-C' Message
    • E.13.6 Console I/O
    • E.13.7 List of Supported Calls
      • open
      • close
      • read
      • write
      • lseek
      • rename
      • unlink
      • stat/fstat
      • gettimeofday
      • isatty
      • system
    • E.13.8 Protocol-specific Representation of Datatypes
      • Integral Datatypes
      • Pointer Values
      • Memory Transfer
      • struct stat
      • struct timeval
    • E.13.9 Constants
      • Open Flags
      • mode_t Values
      • Errno Values
      • Lseek Flags
      • Limits
    • E.13.10 File-I/O Examples
  • E.14 Library List Format
  • E.15 Memory Map Format
  • E.16 Thread List Format
  • E.17 Traceframe Info Format
• Appendix F The GDB Agent Expression Mechanism
  • F.1 General Bytecode Design
  • F.2 Bytecode Descriptions
  • F.3 Using Agent Expressions
  • F.4 Varying Target Capabilities
  • F.5 Rationale
• Appendix G Target Descriptions
  • G.1 Retrieving Descriptions
  • G.2 Target Description Format
    • G.2.1 Inclusion
    • G.2.2 Architecture
    • G.2.3 OS ABI
    • G.2.4 Compatible Architecture
    • G.2.5 Features
    • G.2.6 Types
    • G.2.7 Registers
  • G.3 Predefined Target Types
  • G.4 Standard Target Features
    • G.4.1 ARM Features
    • G.4.2 i386 Features
    • G.4.3 MIPS Features
    • G.4.4 M68K Features
    • G.4.5 PowerPC Features
    • G.4.6 TMS320C6x Features
• Appendix H Operating System Information
  • H.1 Process list
• Appendix I Trace File Format
• Appendix J .gdb_index section format
• Appendix K GNU GENERAL PUBLIC LICENSE
• Appendix L GNU Free Documentation License
• Index

---

Next: Sample Session, Previous: Top, Up: Top

Summary of gdb

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:

• Start your program, specifying anything that might affect its behavior.
• Make your program stop on specified conditions.
• Examine what has happened, when your program has stopped.
• Change things in your program, so you can experiment with correcting the effects of one bug and go on to learn about another.

You can use gdb to debug programs written in C and C++. For more information, see Supported Languages. For more information, see C and C++.
Support for D is partial. For information on D, see D.
Support for Modula-2 is partial. For information on Modula-2, see Modula-2.
Support for OpenCL C is partial. For information on OpenCL C, see OpenCL C.
Debugging Pascal programs which use sets, subranges, file variables, or nested functions does not currently work. gdb does not support entering expressions, printing values, or similar features using Pascal syntax.
gdb can be used to debug programs written in Fortran, although it may be necessary to refer to some variables with a trailing underscore.
gdb can be used to debug programs written in Objective-C, using either the Apple/NeXT or the GNU Objective-C runtime.

• Free Software: Freely redistributable software
• Contributors: Contributors to GDB

---

Next: Contributors, Up: Summary

Free Software

gdb is free software, protected by the gnu General Public License (GPL). The GPL gives you the freedom to copy or adapt a licensed program—but every person getting a copy also gets with it the freedom to modify that copy (which means that they must get access to the source code), and the freedom to distribute further copies. Typical software companies use copyrights to limit your freedoms; the Free Software Foundation uses the GPL to preserve these freedoms.
Fundamentally, the General Public License is a license which says that you have these freedoms and that you cannot take these freedoms away from anyone else.

Free Software Needs Free Documentation

The biggest deficiency in the free software community today is not in the software—it is the lack of good free documentation that we can include with the free software. Many of our most important programs do not come with free reference manuals and free introductory texts. Documentation is an essential part of any software package; when an important free software package does not come with a free manual and a free tutorial, that is a major gap. We have many such gaps today.
Consider Perl, for instance. The tutorial manuals that people normally use are non-free. How did this come about? Because the authors of those manuals published them with restrictive terms—no copying, no modification, source files not available—which exclude them from the free software world.
That wasn't the first time this sort of thing happened, and it was far from the last. Many times we have heard a GNU user eagerly describe a manual that he is writing, his intended contribution to the community, only to learn that he had ruined everything by signing a publication contract to make it non-free.
Free documentation, like free software, is a matter of freedom, not price. The problem with the non-free manual is not that publishers charge a price for printed copies—that in itself is fine. (The Free Software Foundation sells printed copies of manuals, too.) The problem is the restrictions on the use of the manual. Free manuals are available in source code form, and give you permission to copy and modify. Non-free manuals do not allow this.
The criteria of freedom for a free manual are roughly the same as for free software. Redistribution (including the normal kinds of commercial redistribution) must be permitted, so that the manual can accompany every copy of the program, both on-line and on paper.
Permission for modification of the technical content is crucial too. When people modify the software, adding or changing features, if they are conscientious they will change the manual too—so they can provide accurate and clear documentation for the modified program. A manual that leaves you no choice but to write a new manual to document a changed version of the program is not really available to our community.
Some kinds of limits on the way modification is handled are acceptable. For example, requirements to preserve the original author's copyright notice, the distribution terms, or the list of authors, are ok. It is also no problem to require modified versions to include notice that they were modified. Even entire sections that may not be deleted or changed are acceptable, as long as they deal with nontechnical topics (like this one). These kinds of restrictions are acceptable because they don't obstruct the community's normal use of the manual.
However, it must be possible to modify all the technical content of the manual, and then distribute the result in all the usual media, through all the usual channels. Otherwise, the restrictions obstruct the use of the manual, it is not free, and we need another manual to replace it.
Please spread the word about this issue. Our community continues to lose manuals to proprietary publishing. If we spread the word that free software needs free reference manuals and free tutorials, perhaps the next person who wants to contribute by writing documentation will realize, before it is too late, that only free manuals contribute to the free software community.
If you are writing documentation, please insist on publishing it under the GNU Free Documentation License or another free documentation license. Remember that this decision requires your approval—you don't have to let the publisher decide. Some commercial publishers will use a free license if you insist, but they will not propose the option; it is up to you to raise the issue and say firmly that this is what you want. If the publisher you are dealing with refuses, please try other publishers. If you're not sure whether a proposed license is free, write to licensing@gnu.org.
You can encourage commercial publishers to sell more free, copylefted manuals and tutorials by buying them, and particularly by buying copies from the publishers that paid for their writing or for major improvements. Meanwhile, try to avoid buying non-free documentation at all. Check the distribution terms of a manual before you buy it, and insist that whoever seeks your business must respect your freedom. Check the history of the book, and try to reward the publishers that have paid or pay the authors to work on it.
The Free Software Foundation maintains a list of free documentation published by other publishers, at http://www.fsf.org/doc/other-free-books.html.

---

Previous: Free Software, Up: Summary

Contributors to gdb

Richard Stallman was the original author of gdb, and of many other gnu programs. Many others have contributed to its development. This section attempts to credit major contributors. One of the virtues of free software is that everyone is free to contribute to it; with regret, we cannot actually acknowledge everyone here. The file ChangeLog in the gdb distribution approximates a blow-by-blow account.
Changes much prior to version 2.0 are lost in the mists of time.

Plea: Additions to this section are particularly welcome. If you or your friends (or enemies, to be evenhanded) have been unfairly omitted from this list, we would like to add your names!

So that they may not regard their many labors as thankless, we particularly thank those who shepherded gdb through major releases: Andrew Cagney (releases 6.3, 6.2, 6.1, 6.0, 5.3, 5.2, 5.1 and 5.0); Jim Blandy (release 4.18); Jason Molenda (release 4.17); Stan Shebs (release 4.14); Fred Fish (releases 4.16, 4.15, 4.13, 4.12, 4.11, 4.10, and 4.9); Stu Grossman and John Gilmore (releases 4.8, 4.7, 4.6, 4.5, and 4.4); John Gilmore (releases 4.3, 4.2, 4.1, 4.0, and 3.9); Jim Kingdon (releases 3.5, 3.4, and 3.3); and Randy Smith (releases 3.2, 3.1, and 3.0).
Richard Stallman, assisted at various times by Peter TerMaat, Chris Hanson, and Richard Mlynarik, handled releases through 2.8.
Michael Tiemann is the author of most of the gnu C++ support in gdb, with significant additional contributions from Per Bothner and Daniel Berlin. James Clark wrote the gnu C++ demangler. Early work on C++ was by Peter TerMaat (who also did much general update work leading to release 3.0).
gdb uses the BFD subroutine library to examine multiple object-file formats; BFD was a joint project of David V. Henkel-Wallace, Rich Pixley, Steve Chamberlain, and John Gilmore.
David Johnson wrote the original COFF support; Pace Willison did the original support for encapsulated COFF.
Brent Benson of Harris Computer Systems contributed DWARF 2 support.
Adam de Boor and Bradley Davis contributed the ISI Optimum V support. Per Bothner, Noboyuki Hikichi, and Alessandro Forin contributed MIPS support. Jean-Daniel Fekete contributed Sun 386i support. Chris Hanson improved the HP9000 support. Noboyuki Hikichi and Tomoyuki Hasei contributed Sony/News OS 3 support. David Johnson contributed Encore Umax support. Jyrki Kuoppala contributed Altos 3068 support. Jeff Law contributed HP PA and SOM support. Keith Packard contributed NS32K support. Doug Rabson contributed Acorn Risc Machine support. Bob Rusk contributed Harris Nighthawk CX-UX support. Chris Smith contributed Convex support (and Fortran debugging). Jonathan Stone contributed Pyramid support. Michael Tiemann contributed SPARC support. Tim Tucker contributed support for the Gould NP1 and Gould Powernode. Pace Willison contributed Intel 386 support. Jay Vosburgh contributed Symmetry support. Marko Mlinar contributed OpenRISC 1000 support.
Andreas Schwab contributed M68K gnu/Linux support.
Rich Schaefer and Peter Schauer helped with support of SunOS shared libraries.
Jay Fenlason and Roland McGrath ensured that gdb and GAS agree about several machine instruction sets.
Patrick Duval, Ted Goldstein, Vikram Koka and Glenn Engel helped develop remote debugging. Intel Corporation, Wind River Systems, AMD, and ARM contributed remote debugging modules for the i960, VxWorks, A29K UDI, and RDI targets, respectively.
Brian Fox is the author of the readline libraries providing command-line editing and command history.
Andrew Beers of SUNY Buffalo wrote the language-switching code, the Modula-2 support, and contributed the Languages chapter of this manual.
Fred Fish wrote most of the support for Unix System Vr4. He also enhanced the command-completion support to cover C++ overloaded symbols.
Hitachi America (now Renesas America), Ltd. sponsored the support for H8/300, H8/500, and Super-H processors.
NEC sponsored the support for the v850, Vr4xxx, and Vr5xxx processors.
Mitsubishi (now Renesas) sponsored the support for D10V, D30V, and M32R/D processors.
Toshiba sponsored the support for the TX39 Mips processor.
Matsushita sponsored the support for the MN10200 and MN10300 processors.
Fujitsu sponsored the support for SPARClite and FR30 processors.
Kung Hsu, Jeff Law, and Rick Sladkey added support for hardware watchpoints.
Michael Snyder added support for tracepoints.
Stu Grossman wrote gdbserver.
Jim Kingdon, Peter Schauer, Ian Taylor, and Stu Grossman made nearly innumerable bug fixes and cleanups throughout gdb.
The following people at the Hewlett-Packard Company contributed support for the PA-RISC 2.0 architecture, HP-UX 10.20, 10.30, and 11.0 (narrow mode), HP's implementation of kernel threads, HP's aC++ compiler, and the Text User Interface (nee Terminal User Interface): Ben Krepp, Richard Title, John Bishop, Susan Macchia, Kathy Mann, Satish Pai, India Paul, Steve Rehrauer, and Elena Zannoni. Kim Haase provided HP-specific information in this manual.
DJ Delorie ported gdb to MS-DOS, for the DJGPP project. Robert Hoehne made significant contributions to the DJGPP port.
Cygnus Solutions has sponsored gdb maintenance and much of its development since 1991. Cygnus engineers who have worked on gdb fulltime include Mark Alexander, Jim Blandy, Per Bothner, Kevin Buettner, Edith Epstein, Chris Faylor, Fred Fish, Martin Hunt, Jim Ingham, John Gilmore, Stu Grossman, Kung Hsu, Jim Kingdon, John Metzler, Fernando Nasser, Geoffrey Noer, Dawn Perchik, Rich Pixley, Zdenek Radouch, Keith Seitz, Stan Shebs, David Taylor, and Elena Zannoni. In addition, Dave Brolley, Ian Carmichael, Steve Chamberlain, Nick Clifton, JT Conklin, Stan Cox, DJ Delorie, Ulrich Drepper, Frank Eigler, Doug Evans, Sean Fagan, David Henkel-Wallace, Richard Henderson, Jeff Holcomb, Jeff Law, Jim Lemke, Tom Lord, Bob Manson, Michael Meissner, Jason Merrill, Catherine Moore, Drew Moseley, Ken Raeburn, Gavin Romig-Koch, Rob Savoye, Jamie Smith, Mike Stump, Ian Taylor, Angela Thomas, Michael Tiemann, Tom Tromey, Ron Unrau, Jim Wilson, and David Zuhn have made contributions both large and small.
Andrew Cagney, Fernando Nasser, and Elena Zannoni, while working for Cygnus Solutions, implemented the original gdb/mi interface.
Jim Blandy added support for preprocessor macros, while working for Red Hat.
Andrew Cagney designed gdb's architecture vector. Many people including Andrew Cagney, Stephane Carrez, Randolph Chung, Nick Duffek, Richard Henderson, Mark Kettenis, Grace Sainsbury, Kei Sakamoto, Yoshinori Sato, Michael Snyder, Andreas Schwab, Jason Thorpe, Corinna Vinschen, Ulrich Weigand, and Elena Zannoni, helped with the migration of old architectures to this new framework.
Andrew Cagney completely re-designed and re-implemented gdb's unwinder framework, this consisting of a fresh new design featuring frame IDs, independent frame sniffers, and the sentinel frame. Mark Kettenis implemented the dwarf 2 unwinder, Jeff Johnston the libunwind unwinder, and Andrew Cagney the dummy, sentinel, tramp, and trad unwinders. The architecture-specific changes, each involving a complete rewrite of the architecture's frame code, were carried out by Jim Blandy, Joel Brobecker, Kevin Buettner, Andrew Cagney, Stephane Carrez, Randolph Chung, Orjan Friberg, Richard Henderson, Daniel Jacobowitz, Jeff Johnston, Mark Kettenis, Theodore A. Roth, Kei Sakamoto, Yoshinori Sato, Michael Snyder, Corinna Vinschen, and Ulrich Weigand.
Christian Zankel, Ross Morley, Bob Wilson, and Maxim Grigoriev from Tensilica, Inc. contributed support for Xtensa processors. Others who have worked on the Xtensa port of gdb in the past include Steve Tjiang, John Newlin, and Scott Foehner.
Michael Eager and staff of Xilinx, Inc., contributed support for the Xilinx MicroBlaze architecture.

---

Next: Invocation, Previous: Summary, Up: Top

1 A Sample gdb Session

You can use this manual at your leisure to read all about gdb. However, a handful of commands are enough to get started using the debugger. This chapter illustrates those commands.
One of the preliminary versions of gnu m4 (a generic macro processor) exhibits the following bug: sometimes, when we change its quote strings from the default, the commands used to capture one macro definition within another stop working. In the following short m4 session, we define a macro foo which expands to 0000; we then use the m4 built-in defn to define bar as the same thing. However, when we change the open quote string to <QUOTE> and the close quote string to <UNQUOTE>, the same procedure fails to define a new synonym baz:

     $ cd gnu/m4
     $ ./m4
     define(foo,0000)
     
     foo
     0000
     define(bar,defn(`foo'))
     
     bar
     0000
     changequote(<QUOTE>,<UNQUOTE>)
     
     define(baz,defn(<QUOTE>foo<UNQUOTE>))
     baz
     Ctrl-d
     m4: End of input: 0: fatal error: EOF in string

Let us use gdb to try to see what is going on.

     $ gdb m4
     
     
     gdb is free software and you are welcome to distribute copies
      of it under certain conditions; type "show copying" to see
      the conditions.
     There is absolutely no warranty for gdb; type "show warranty"
      for details.
     
     gdb 7.3.50.20111125, Copyright 1999 Free Software Foundation, Inc...
     (gdb)

gdb reads only enough symbol data to know where to find the rest when needed; as a result, the first prompt comes up very quickly. We now tell gdb to use a narrower display width than usual, so that examples fit in this manual.

     (gdb) set width 70

We need to see how the m4 built-in changequote works. Having looked at the source, we know the relevant subroutine is m4_changequote, so we set a breakpoint there with the gdb break command.

     (gdb) break m4_changequote
     Breakpoint 1 at 0x62f4: file builtin.c, line 879.

Using the run command, we start m4 running under gdb control; as long as control does not reach the m4_changequote subroutine, the program runs as usual:

     (gdb) run
     Starting program: /work/Editorial/gdb/gnu/m4/m4
     define(foo,0000)
     
     foo
     0000

To trigger the breakpoint, we call changequote. gdb suspends execution of m4, displaying information about the context where it stops.

     changequote(<QUOTE>,<UNQUOTE>)
     
     Breakpoint 1, m4_changequote (argc=3, argv=0x33c70)
         at builtin.c:879
     879         if (bad_argc(TOKEN_DATA_TEXT(argv[0]),argc,1,3))

Now we use the command n (next) to advance execution to the next line of the current function.

     (gdb) n
     882         set_quotes((argc >= 2) ? TOKEN_DATA_TEXT(argv[1])\
      : nil,

set_quotes looks like a promising subroutine. We can go into it by using the command s (step) instead of next. step goes to the next line to be executed in any subroutine, so it steps into set_quotes.

     (gdb) s
     set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>")
         at input.c:530
     530         if (lquote != def_lquote)

The display that shows the subroutine where m4 is now suspended (and its arguments) is called a stack frame display. It shows a summary of the stack. We can use the backtrace command (which can also be spelled bt), to see where we are in the stack as a whole: the backtrace command displays a stack frame for each active subroutine.

     (gdb) bt
     #0  set_quotes (lq=0x34c78 "<QUOTE>", rq=0x34c88 "<UNQUOTE>")
         at input.c:530
     #1  0x6344 in m4_changequote (argc=3, argv=0x33c70)
         at builtin.c:882
     #2  0x8174 in expand_macro (sym=0x33320) at macro.c:242
     #3  0x7a88 in expand_token (obs=0x0, t=209696, td=0xf7fffa30)
         at macro.c:71
     #4  0x79dc in expand_input () at macro.c:40
     #5  0x2930 in main (argc=0, argv=0xf7fffb20) at m4.c:195

We step through a few more lines to see what happens. The first two times, we can use `s'; the next two times we use n to avoid falling into the xstrdup subroutine.

     (gdb) s
     0x3b5c  532         if (rquote != def_rquote)
     (gdb) s
     0x3b80  535         lquote = (lq == nil || *lq == '\0') ?  \
     def_lquote : xstrdup(lq);
     (gdb) n
     536         rquote = (rq == nil || *rq == '\0') ? def_rquote\
      : xstrdup(rq);
     (gdb) n
     538         len_lquote = strlen(rquote);

The last line displayed looks a little odd; we can examine the variables lquote and rquote to see if they are in fact the new left and right quotes we specified. We use the command p (print) to see their values.

     (gdb) p lquote
     $1 = 0x35d40 "<QUOTE>"
     (gdb) p rquote
     $2 = 0x35d50 "<UNQUOTE>"

lquote and rquote are indeed the new left and right quotes. To look at some context, we can display ten lines of source surrounding the current line with the l (list) command.

     (gdb) l
     533             xfree(rquote);
     534
     535         lquote = (lq == nil || *lq == '\0') ? def_lquote\
      : xstrdup (lq);
     536         rquote = (rq == nil || *rq == '\0') ? def_rquote\
      : xstrdup (rq);
     537
     538         len_lquote = strlen(rquote);
     539         len_rquote = strlen(lquote);
     540     }
     541
     542     void

Let us step past the two lines that set len_lquote and len_rquote, and then examine the values of those variables.

     (gdb) n
     539         len_rquote = strlen(lquote);
     (gdb) n
     540     }
     (gdb) p len_lquote
     $3 = 9
     (gdb) p len_rquote
     $4 = 7

That certainly looks wrong, assuming len_lquote and len_rquote are meant to be the lengths of lquote and rquote respectively. We can set them to better values using the p command, since it can print the value of any expression—and that expression can include subroutine calls and assignments.

     (gdb) p len_lquote=strlen(lquote)
     $5 = 7
     (gdb) p len_rquote=strlen(rquote)
     $6 = 9

Is that enough to fix the problem of using the new quotes with the m4 built-in defn? We can allow m4 to continue executing with the c (continue) command, and then try the example that caused trouble initially:

     (gdb) c
     Continuing.
     
     define(baz,defn(<QUOTE>foo<UNQUOTE>))
     
     baz
     0000

Success! The new quotes now work just as well as the default ones. The problem seems to have been just the two typos defining the wrong lengths. We allow m4 exit by giving it an EOF as input:

     Ctrl-d
     Program exited normally.

The message `Program exited normally.' is from gdb; it indicates m4 has finished executing. We can end our gdb session with the gdb quit command.

     (gdb) quit

---

Next: Commands, Previous: Sample Session, Up: Top

2 Getting In and Out of gdb

This chapter discusses how to start gdb, and how to get out of it. The essentials are:

• type `gdb' to start gdb.
• type quit or Ctrl-d to exit.

• Invoking GDB: How to start gdb
• Quitting GDB: How to quit gdb
• Shell Commands: How to use shell commands inside gdb
• Logging Output: How to log gdb's output to a file

---

Next: Quitting GDB, Up: Invocation

2.1 Invoking gdb

Invoke gdb by running the program gdb. Once started, gdb reads commands from the terminal until you tell it to exit.
You can also run gdb with a variety of arguments and options, to specify more of your debugging environment at the outset.
The command-line options described here are designed to cover a variety of situations; in some environments, some of these options may effectively be unavailable.
The most usual way to start gdb is with one argument, specifying an executable program:

     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).

Taking advantage of the second command-line argument requires a fairly complete operating system; when you use gdb as a remote debugger attached to a bare board, there may not be any notion of “process”, and there is often no way to get a core dump. gdb will warn you if it is unable to attach or to read core dumps.
You can optionally have gdb pass any arguments after the executable file to the inferior using --args. This option stops option processing.

     gdb --args gcc -O2 -c foo.c

This will cause gdb to debug gcc, and to set gcc's command-line arguments (see Arguments) to `-O2 -c foo.c'.
You can run gdb without printing the front material, which describes gdb's non-warranty, by specifying -silent:

     gdb -silent

You can further control how gdb starts up by using command-line options. gdb itself can remind you of the options available.

Type

     gdb -help

to display all available options and briefly describe their use (`gdb -h' is a shorter equivalent).

All options and command line arguments you give are processed in sequential order. The order makes a difference when the `-x' option is used.

• File Options: Choosing files
• Mode Options: Choosing modes
• Startup: What gdb does during startup

---

Next: Mode Options, Up: Invoking GDB

2.1.1 Choosing Files

When gdb starts, it reads any arguments other than options as specifying an executable file and core file (or process ID). This is the same as if the arguments were specified by the `-se' and `-c' (or `-p') options respectively. (gdb reads the first argument that does not have an associated option flag as equivalent to the `-se' option followed by that argument; and the second argument that does not have an associated option flag, if any, as equivalent to the `-c'/`-p' option followed by that argument.) If the second argument begins with a decimal digit, gdb will first attempt to attach to it as a process, and if that fails, attempt to open it as a corefile. If you have a corefile whose name begins with a digit, you can prevent gdb from treating it as a pid by prefixing it with ./, e.g. ./12345.
If gdb has not been configured to included core file support, such as for most embedded targets, then it will complain about a second argument and ignore it.
Many options have both long and short forms; both are shown in the following list. gdb also recognizes the long forms 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.)

-symbols file

-s file

Read symbol table from file file.

-exec file

-e file

Use file file as the executable file to execute when appropriate, 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.

-pid number

-p number

Connect to process ID number, as with the attach command.

-command file

-x file

Execute commands from file file. The contents of this file is evaluated exactly as the source command would. See Command files.

-eval-command command

-ex command

Execute a single gdb command. This option may be used multiple times to call multiple commands. It may also be interleaved with `-command' as required.

          gdb -ex 'target sim' -ex 'load' \
             -x setbreakpoints -ex 'run' a.out
     

-directory directory

-d directory

Add directory to the path to search for source and script files.

-r

-readnow

Read each symbol file's entire symbol table immediately, rather than the default, which is to read it incrementally as it is needed. This makes startup slower, but makes future operations faster.

---

Next: Startup, Previous: File Options, Up: Invoking GDB

2.1.2 Choosing Modes

You can run gdb in various alternative modes—for example, in batch mode or quiet mode.

-nx

-n

Do not execute commands found in any initialization files. Normally, gdb executes the commands in these files after all the command options and arguments have been processed. See Command Files.

-quiet

-silent

-q

“Quiet”. Do not print the introductory and copyright messages. 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 all commands from initialization files, if not inhibited with `-n'). Exit with nonzero status if an error occurs in executing the gdb commands in the command files. Batch mode also disables pagination, sets unlimited terminal width and height see Screen Size, and acts as if set confirm off were in effect (see Messages/Warnings). Batch mode may be useful for running gdb as a filter, for example 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.

-batch-silent

Run in batch mode exactly like `-batch', but totally silently. All gdb output to stdout is prevented (stderr is unaffected). This is much quieter than `-silent' and would be useless for an interactive session. This is particularly useful when using targets that give `Loading section' messages, for example.
Note that targets that give their output via gdb, as opposed to writing directly to stdout, will also be made silent.

-return-child-result

The return code from gdb will be the return code from the child process (the process being debugged), with the following exceptions:

• gdb exits abnormally. E.g., due to an incorrect argument or an internal error. In this case the exit code is the same as it would have been without `-return-child-result'.
• The user quits with an explicit value. E.g., `quit 1'.
• The child process never runs, or is not allowed to terminate, in which case the exit code will be -1.

This option is useful in conjunction with `-batch' or `-batch-silent', when gdb is being used as a remote program loader or simulator interface.

-nowindows

-nw

“No windows”. If gdb comes with a graphical user interface (GUI) built in, then this option tells gdb to only use the command-line interface. If no GUI is available, this option has no effect.

-windows

-w

If gdb includes a GUI, then this option requires it to be used if possible.

-cd directory

Run gdb using directory as its working directory, instead of the current directory.

-data-directory directory

Run gdb using directory as its data directory. The data directory is where gdb searches for its auxiliary files. See Data Files.

-fullname

-f

gnu 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 displayed (which includes each time your program stops). This recognizable format looks like two `\032' 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 `\032' characters as a signal to display the source code for the frame.

-epoch

The Epoch Emacs-gdb interface sets this option when it runs gdb as a subprocess. It tells gdb to modify its print routines so as to allow Epoch to display values of expressions in a separate window.

-annotate level

This option sets the annotation level inside gdb. Its effect is identical to using `set annotate level' (see Annotations). The annotation level controls how much information gdb prints together with its prompt, values of expressions, source lines, and other types of output. Level 0 is the normal, level 1 is for use when gdb is run as a subprocess of gnu Emacs, level 3 is the maximum annotation suitable for programs that control gdb, and level 2 has been deprecated. The annotation mechanism has largely been superseded by gdb/mi (see GDB/MI).

--args

Change interpretation of command line so that arguments following the executable file are passed as command line arguments to the inferior. This option stops option processing.

-baud bps

-b bps

Set the line speed (baud rate or bits per second) of any serial interface used by gdb for remote debugging.

-l timeout

Set the timeout (in seconds) of any communication used by gdb for remote debugging.

-tty device

-t device

Run using device for your program's standard input and output.

-tui

Activate the Text User Interface when starting. The Text User Interface manages several text windows on the terminal, showing source, assembly, registers and gdb command outputs (see gdb Text User Interface). Alternatively, the Text User Interface can be enabled by invoking the program `gdbtui'. Do not use this option if you run gdb from Emacs (see Using gdb under gnu Emacs).

-interpreter interp

Use the interpreter interp for interface with the controlling program or device. This option is meant to be set by programs which communicate with gdb using it as a back end. See Command Interpreters. `--interpreter=mi' (or `--interpreter=mi2') causes gdb to use the gdb/mi interface (see The gdb/mi Interface) included since gdb version 6.0. The previous gdb/mi interface, included in gdb version 5.3 and selected with `--interpreter=mi1', is deprecated. Earlier gdb/mi interfaces are no longer supported.

-write

Open the executable and core files for both reading and writing. This is equivalent to the `set write on' command inside gdb (see Patching).

-statistics

This option causes gdb to print statistics about time and memory usage after it completes each command and returns to the prompt.

-version

This option causes gdb to print its version number and no-warranty blurb, and exit.

---

Previous: Mode Options, Up: Invoking GDB

2.1.3 What gdb Does During Startup

Here's the description of what gdb does during session startup:

1. Sets up the command interpreter as specified by the command line (see interpreter).
2. Reads the system-wide init file (if --with-system-gdbinit was used when building gdb; see System-wide configuration and settings) and executes all the commands in that file.
3. Reads the init file (if any) in your home directory¹ and executes all the commands in that file.
4. Processes command line options and operands.
5. Reads and executes the commands from init file (if any) in the current working directory. This is only done if the current directory is different from your home directory. Thus, you can have more than one init file, one generic in your home directory, and another, specific to the program you are debugging, in the directory where you invoke gdb.
6. If the command line specified a program to debug, or a process to attach to, or a core file, gdb loads any auto-loaded scripts provided for the program or for its loaded shared libraries. See Auto-loading. If you wish to disable the auto-loading during startup, you must do something like the following:
   

             $ gdb -ex "set auto-load-scripts off" -ex "file myprogram"
        

   The following does not work because the auto-loading is turned off too late:
   

             $ gdb -ex "set auto-load-scripts off" myprogram
        

7. Reads command files specified by the `-x' option. See Command Files, for more details about gdb command files.
8. Reads the command history recorded in the history file. See Command History, for more details about the command history and the files where gdb records it.

Init files use the same syntax as command files (see Command Files) and are processed by gdb in the same way. The init file in your home directory can set options (such as `set complaints') that affect subsequent processing of command line options and operands. Init files are not executed if you use the `-nx' option (see Choosing Modes).
To display the list of init files loaded by gdb at startup, you can use gdb --help.
The gdb init files are normally called .gdbinit. The DJGPP port of gdb uses the name gdb.ini, due to the limitations of file names imposed by DOS filesystems. The Windows ports of gdb use the standard name, but if they find a gdb.ini file, they warn you about that and suggest to rename the file to the standard name.

---

Next: Shell Commands, Previous: Invoking GDB, Up: Invocation

2.2 Quitting gdb

quit [expression]

q

To exit gdb, use the quit command (abbreviated q), or type an end-of-file character (usually Ctrl-d). If you do not supply expression, gdb will terminate normally; otherwise it will terminate using the result of expression as the error code.

An interrupt (often Ctrl-c) does not exit from gdb, but rather terminates the action of any gdb command that is in progress and returns to gdb command level. It is safe to type the interrupt character at any time because gdb does not allow it to take effect until a time when it is safe.
If you have been using gdb to control an attached process or device, you can release it with the detach command (see Debugging an Already-running Process).

---

Next: Logging Output, Previous: Quitting GDB, Up: Invocation

2.3 Shell Commands

If you need to execute occasional shell commands during your debugging session, there is no need to leave or suspend gdb; you can just use the shell command.

shell command-string

!command-string

Invoke a standard shell to execute command-string. Note that no space is needed between ! and command-string. If it exists, the environment variable SHELL determines which shell to run. Otherwise gdb uses the default shell (/bin/sh on Unix systems, COMMAND.COM on MS-DOS, etc.).

The utility make is often needed in development environments. You do not have to use the shell command for this purpose in gdb:

make make-args

Execute the make program with the specified arguments. This is equivalent to `shell make make-args'.

---

Previous: Shell Commands, Up: Invocation

2.4 Logging Output

You may want to save the output of gdb commands to a file. There are several commands to control gdb's logging.

set logging on

Enable logging.

set logging off

Disable logging.

set logging file file

Change the name of the current logfile. The default logfile is gdb.txt.

set logging overwrite [on|off]

By default, gdb will append to the logfile. Set overwrite if you want set logging on to overwrite the logfile instead.

set logging redirect [on|off]

By default, gdb output will go to both the terminal and the logfile. Set redirect if you want output to go only to the log file.

show logging

Show the current values of the logging settings.

---

Next: Running, Previous: Invocation, Up: Top

3 gdb Commands

You can abbreviate a gdb command to the first few letters of the command name, if that abbreviation is unambiguous; and you can repeat certain gdb commands by typing just <RET>. You can also use the <TAB> key to get gdb to fill out the rest of a word in a command (or to show you the alternatives available, if there is more than one possibility).

• Command Syntax: How to give commands to gdb
• Completion: Command completion
• Help: How to ask gdb for help

---

Next: Completion, Up: Commands

3.1 Command Syntax

A gdb command is a single line of input. There is no limit on how long it can be. It starts with a command name, which is followed by arguments whose meaning depends on the command name. For example, the command step accepts an argument which is the number of times to step, as in `step 5'. You can also use the step command with no arguments. Some commands do not allow any arguments.
gdb command names may always be truncated if that abbreviation is unambiguous. Other possible command abbreviations are listed in the documentation for individual commands. In some cases, even ambiguous abbreviations are allowed; for example, s is specially defined as equivalent to step even though there are other commands whose names start with s. You can test abbreviations by using them as arguments to the help command.
A blank line as input to gdb (typing just <RET>) means to repeat the previous command. Certain commands (for example, run) will not repeat this way; these are commands whose unintentional repetition might cause trouble and which you are unlikely to want to repeat. User-defined commands can disable this feature; see dont-repeat.
The list and x commands, when you repeat them with <RET>, construct new arguments rather than repeating exactly as typed. This permits easy scanning of source or memory.
gdb can also use <RET> in another way: to partition lengthy output, in a way similar to the common utility more (see Screen Size). Since it is easy to press one <RET> too many in this situation, gdb disables command repetition after any command that generates this sort of display.
Any text from a # to the end of the line is a comment; it does nothing. This is useful mainly in command files (see Command Files).
The Ctrl-o binding is useful for repeating a complex sequence of commands. This command accepts the current line, like <RET>, and then fetches the next line relative to the current line from the history for editing.

---

Next: Help, Previous: Command Syntax, Up: Commands

3.2 Command Completion

gdb can fill in the rest of a word in a command for you, if there is only one possibility; it can also show you what the valid possibilities are for the next word in a command, at any time. This works for gdb commands, gdb subcommands, and the names of symbols in your program.
Press the <TAB> key whenever you want gdb to fill out the rest of a word. If there is only one possibility, gdb fills in the word, and waits for you to finish the command (or press <RET> to enter it). For example, if you type

     (gdb) info bre <TAB>

gdb fills in the rest of the word `breakpoints', since that is the only info subcommand beginning with `bre':

     (gdb) info breakpoints

You can either press <RET> at this point, to run the info breakpoints command, or backspace and enter something else, if `breakpoints' does not look like the command you expected. (If you were sure you wanted info breakpoints in the first place, you might as well just type <RET> immediately after `info bre', to exploit command abbreviations rather than command completion).

If there is more than one possibility for the next word when you press <TAB>, gdb sounds a bell. You can either supply more characters and try again, or just press <TAB> a second time; gdb displays all the possible completions for that word. For example, you might want to set a breakpoint on a subroutine whose name begins with `make_', but when you type b make_<TAB> gdb just sounds the bell. Typing <TAB> again displays all the function names in your program that begin with those characters, for example:

     (gdb) b make_ <TAB>

gdb sounds bell; press <TAB> again, to see:

     make_a_section_from_file     make_environ
     make_abs_section             make_function_type
     make_blockvector             make_pointer_type
     make_cleanup                 make_reference_type
     make_command                 make_symbol_completion_list
     (gdb) b make_

After displaying the available possibilities, gdb copies your partial input (`b make_' in the example) so you can finish the command.

If you just want to see the list of alternatives in the first place, you can press M-? rather than pressing <TAB> twice. M-? means <META> ?. You can type this either by holding down a key designated as the <META> shift on your keyboard (if there is one) while typing ?, or as <ESC> followed by ?.
Sometimes the string you need, while logically a “word”, may contain parentheses or other characters that gdb normally excludes from its notion of a word. To permit word completion to work in this situation, you may enclose words in ' (single quote marks) in gdb commands.
The most likely situation where you might need this is in typing the name of a C++ function. This is because C++ allows function overloading (multiple definitions of the same function, distinguished by argument type). For example, when you want to set a breakpoint you may need to distinguish whether you mean the version of name that takes an int parameter, name(int), or the version that takes a float parameter, name(float). To use the word-completion facilities in this situation, type a single quote ' at the beginning of the function name. This alerts gdb that it may need to consider more information than usual when you press <TAB> or M-? to request word completion:

     (gdb) b 'bubble( M-?
     bubble(double,double)    bubble(int,int)
     (gdb) b 'bubble(

In some cases, gdb can tell that completing a name requires using quotes. When this happens, gdb inserts the quote for you (while completing as much as it can) if you do not type the quote in the first place:

     (gdb) b bub <TAB>

gdb alters your input line to the following, and rings a bell:

     (gdb) b 'bubble(

In general, gdb can tell that a quote is needed (and inserts it) if you have not yet started typing the argument list when you ask for completion on an overloaded symbol.

For more information about overloaded functions, see C++ Expressions. You can use the command set overload-resolution off to disable overload resolution; see gdb Features for C++.
When completing in an expression which looks up a field in a structure, gdb also tries² to limit completions to the field names available in the type of the left-hand-side:

     (gdb) p gdb_stdout.M-?
     magic                to_fputs             to_rewind
     to_data              to_isatty            to_write
     to_delete            to_put               to_write_async_safe
     to_flush             to_read

This is because the gdb_stdout is a variable of the type struct ui_file that is defined in gdb sources as follows:

     struct ui_file
     {
        int *magic;
        ui_file_flush_ftype *to_flush;
        ui_file_write_ftype *to_write;
        ui_file_write_async_safe_ftype *to_write_async_safe;
        ui_file_fputs_ftype *to_fputs;
        ui_file_read_ftype *to_read;
        ui_file_delete_ftype *to_delete;
        ui_file_isatty_ftype *to_isatty;
        ui_file_rewind_ftype *to_rewind;
        ui_file_put_ftype *to_put;
        void *to_data;
     }

---

Previous: Completion, Up: Commands

3.3 Getting Help

You can always ask gdb itself for information on its commands, using the command help.

help

h

You can use help (abbreviated h) with no arguments to display a short list of named classes of commands:

          (gdb) help
          List of classes of commands:
          
          aliases -- Aliases of other commands
          breakpoints -- Making program stop at certain points
          data -- Examining data
          files -- Specifying and examining files
          internals -- Maintenance commands
          obscure -- Obscure features
          running -- Running the program
          stack -- Examining the stack
          status -- Status inquiries
          support -- Support facilities
          tracepoints -- Tracing of program execution without
                         stopping the program
          user-defined -- User-defined commands
          
          Type "help" followed by a class name for a list of
          commands in that class.
          Type "help" followed by command name for full
          documentation.
          Command name abbreviations are allowed if unambiguous.
          (gdb)
     

help class

Using one of the general help classes as an argument, you can get a list of the individual commands in that class. For example, here is the help display for the class status:

          (gdb) help status
          Status inquiries.
          
          List of commands:
          
          
          
          info -- Generic command for showing things
                  about the program being debugged
          show -- Generic command for showing things
                  about the debugger
          
          Type "help" followed by command name for full
          documentation.
          Command name abbreviations are allowed if unambiguous.
          (gdb)
     

help command

With a command name as help argument, gdb displays a short paragraph on how to use that command.

apropos args

The apropos command searches through all of the gdb commands, and their documentation, for the regular expression specified in args. It prints out all matches found. For example:

          apropos reload
     

results in:

          
          set symbol-reloading -- Set dynamic symbol table reloading
                                  multiple times in one run
          show symbol-reloading -- Show dynamic symbol table reloading
                                  multiple times in one run
          
     

complete args

The complete args command lists all the possible completions for the beginning of a command. Use args to specify the beginning of the command you want completed. For example:

          complete i
     

results in:

          if
          ignore
          info
          inspect
     

This is intended for use by gnu Emacs.

In addition to help, you can use the gdb commands info and show to inquire about the state of your program, or the state of gdb itself. Each command supports many topics of inquiry; this manual introduces each of them in the appropriate context. The listings under info and under show in the Index point to all the sub-commands. See Index.

info

This command (abbreviated i) is for describing the state of your program. For example, you can show the arguments passed to a function with info args, list the registers currently in use with info registers, or list the breakpoints you have set with info breakpoints. You can get a complete list of the info sub-commands with help info.

set

You can assign the result of an expression to an environment variable with set. For example, you can set the gdb prompt to a $-sign with set prompt $.

show

In contrast to info, show is for describing the state of gdb itself. You can change most of the things you can show, by using the related command set; for example, you can control what number system is used for displays with set radix, or simply inquire which is currently in use with show radix. To display all the settable parameters and their current values, you can use show with no arguments; you may also use info set. Both commands produce the same display.

Here are three miscellaneous show subcommands, all of which are exceptional in lacking corresponding set commands:

show version

Show what version of gdb is running. You should include this information in gdb bug-reports. If multiple versions of gdb are in use at your site, you may need to determine which version of gdb you are running; as gdb evolves, new commands are introduced, and old ones may wither away. Also, many system vendors ship variant versions of gdb, and there are variant versions of gdb in gnu/Linux distributions as well. The version number is the same as the one announced when you start gdb.

show copying

info copying

Display information about permission for copying gdb.

show warranty

info warranty

Display the gnu “NO WARRANTY” statement, or a warranty, if your version of gdb comes with one.

---

Next: Stopping, Previous: Commands, Up: Top

4 Running Programs Under gdb

When you run a program under gdb, you must first generate debugging information when you compile it.
You may start gdb with its arguments, if any, in an environment of your choice. If you are doing native debugging, you may redirect your program's input and output, debug an already running process, or kill a child process.

• Compilation: Compiling for debugging
• Starting: Starting your program
• Arguments: Your program's arguments
• Environment: Your program's environment
• Working Directory: Your program's working directory
• Input/Output: Your program's input and output
• Attach: Debugging an already-running process
• Kill Process: Killing the child process
• Inferiors and Programs: Debugging multiple inferiors and programs
• Threads: Debugging programs with multiple threads
• Forks: Debugging forks
• Checkpoint/Restart: Setting a bookmark to return to later

---

Next: Starting, Up: Running

4.1 Compiling for Debugging

In order to debug a program effectively, you need to generate debugging information when you compile it. This debugging information is stored in the object file; it describes the data type of each variable or function and the correspondence between source line numbers and addresses in the executable code.
To request debugging information, specify the `-g' option when you run the compiler.
Programs that are to be shipped to your customers are compiled with optimizations, using the `-O' compiler option. However, some compilers are unable to handle the `-g' and `-O' options together. Using those compilers, you cannot generate optimized executables containing debugging information.
gcc, the gnu C/C++ compiler, supports `-g' with or without `-O', making it possible to debug optimized code. We recommend that you always use `-g' whenever you compile a program. You may think your program is correct, but there is no sense in pushing your luck. For more information, see Optimized Code.
Older versions of the gnu C compiler permitted a variant option `-gg' for debugging information. gdb no longer supports this format; if your gnu C compiler has this option, do not use it.
gdb knows about preprocessor macros and can show you their expansion (see Macros). Most compilers do not include information about preprocessor macros in the debugging information if you specify the -g flag alone. Version 3.1 and later of gcc, the gnu C compiler, provides macro information if you are using the DWARF debugging format, and specify the option -g3.
See Options for Debugging Your Program or GCC, for more information on gcc options affecting debug information.
You will have the best debugging experience if you use the latest version of the DWARF debugging format that your compiler supports. DWARF is currently the most expressive and best supported debugging format in gdb.

---

Next: Arguments, Previous: Compilation, Up: Running

4.2 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 (see Getting In and Out of gdb), or by using the file or exec-file command (see Commands to Specify 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 some environments without processes, run jumps to the start of your program. Other targets, like `remote', are always running. If you get an error message like this one:

     The "remote" target does not support "run".
     Try "help target" or "continue".

then use continue to run your program. You may need load first (see load).

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. See Your Program's 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. See Your Program's 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. See Your Program's 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. See Your Program's Input and 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. See Stopping and Continuing, 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. See Examining 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.

start

The name of the main procedure can vary from language to language. With C or C++, the main procedure name is always main, but other languages such as Ada do not require a specific name for their main procedure. The debugger provides a convenient way to start the execution of the program and to stop at the beginning of the main procedure, depending on the language used. The `start' command does the equivalent of setting a temporary breakpoint at the beginning of the main procedure and then invoking the `run' command.
Some programs contain an elaboration phase where some startup code is executed before the main procedure is called. This depends on the languages used to write your program. In C++, for instance, constructors for static and global objects are executed before main is called. It is therefore possible that the debugger stops before reaching the main procedure. However, the temporary breakpoint will remain to halt execution.
Specify the arguments to give to your program as arguments to the `start' command. These arguments will be given verbatim to the underlying `run' command. Note that the same arguments will be reused if no argument is provided during subsequent calls to `start' or `run'.
It is sometimes necessary to debug the program during elaboration. In these cases, using the start command would stop the execution of your program too late, as the program would have already completed the elaboration phase. Under these circumstances, insert breakpoints in your elaboration code before running your program.

set exec-wrapper wrapper

show exec-wrapper

unset exec-wrapper

When `exec-wrapper' is set, the specified wrapper is used to launch programs for debugging. gdb starts your program with a shell command of the form exec wrapper program. Quoting is added to program and its arguments, but not to wrapper, so you should add quotes if appropriate for your shell. The wrapper runs until it executes your program, and then gdb takes control. You can use any program that eventually calls execve with its arguments as a wrapper. Several standard Unix utilities do this, e.g. env and nohup. Any Unix shell script ending with exec "$@" will also work.
For example, you can use env to pass an environment variable to the debugged program, without setting the variable in your shell's environment:

          (gdb) set exec-wrapper env 'LD_PRELOAD=libtest.so'
          (gdb) run
     

This command is available when debugging locally on most targets, excluding djgpp, Cygwin, MS Windows, and QNX Neutrino.

set disable-randomization

set disable-randomization on

This option (enabled by default in gdb) will turn off the native randomization of the virtual address space of the started program. This option is useful for multiple debugging sessions to make the execution better reproducible and memory addresses reusable across debugging sessions. This feature is implemented only on certain targets, including gnu/Linux. On gnu/Linux you can get the same behavior using

          (gdb) set exec-wrapper setarch `uname -m` -R
     

set disable-randomization off

Leave the behavior of the started executable unchanged. Some bugs rear their ugly heads only when the program is loaded at certain addresses. If your bug disappears when you run the program under gdb, that might be because gdb by default disables the address randomization on platforms, such as gnu/Linux, which do that for stand-alone programs. Use set disable-randomization off to try to reproduce such elusive bugs. On targets where it is available, virtual address space randomization protects the programs against certain kinds of security attacks. In these cases the attacker needs to know the exact location of a concrete executable code. Randomizing its location makes it impossible to inject jumps misusing a code at its expected addresses.
Prelinking shared libraries provides a startup performance advantage but it makes addresses in these libraries predictable for privileged processes by having just unprivileged access at the target system. Reading the shared library binary gives enough information for assembling the malicious code misusing it. Still even a prelinked shared library can get loaded at a new random address just requiring the regular relocation process during the startup. Shared libraries not already prelinked are always loaded at a randomly chosen address.
Position independent executables (PIE) contain position independent code similar to the shared libraries and therefore such executables get loaded at a randomly chosen address upon startup. PIE executables always load even already prelinked shared libraries at a random address. You can build such executable using gcc -fPIE -pie.
Heap (malloc storage), stack and custom mmap areas are always placed randomly (as long as the randomization is enabled).

show disable-randomization

Show the current setting of the explicit disable of the native randomization of the virtual address space of the started program.

---

Next: Environment, Previous: Starting, Up: Running

4.3 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 the default shell (/bin/sh on Unix).
On non-Unix systems, the program is usually invoked directly by gdb, which emulates I/O redirection via the appropriate system calls, and the wildcard characters are expanded by the startup code of the program, not by the shell.
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.

---

Next: Working Directory, Previous: Arguments, Up: Running

4.4 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) that will be passed to your program. The value of PATH used by gdb does not change. You may specify several directory names, separated by whitespace or by a system-dependent separator character (`:' on Unix, `;' on MS-DOS and MS-Windows). 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 the debugged 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: On Unix systems, 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.

---

Next: Input/Output, Previous: Environment, Up: Running

4.5 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. See Commands to Specify Files.

cd directory

Set the gdb working directory to directory.

pwd

Print the gdb working directory.

It is generally impossible to find the current working directory of the process being debugged (since a program can change its directory during its run). If you work on a system where gdb is configured with the /proc support, you can use the info proc command (see SVR4 Process Information) to find out the current working directory of the debuggee.

---

Next: Attach, Previous: Working Directory, Up: Running

4.6 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. tty is an alias for set inferior-tty.
You can use the show inferior-tty command to tell gdb to display the name of the terminal that will be used for future runs of your program.

set inferior-tty /dev/ttyb

Set the tty for the program being debugged to /dev/ttyb.

show inferior-tty

Show the current tty for the program being debugged.

---

Next: Kill Process, Previous: Input/Output, Up: Running

4.7 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 (see Specifying Source Directories). You can also use the file command to load the program. See Commands to Specify 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 while you have an attached process, you detach that process. If you use the run command, 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 (see Optional Warnings and Messages).

---

Next: Inferiors and Programs, Previous: Attach, Up: Running

4.8 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).

---

Next: Threads, Previous: Kill Process, Up: Running

4.9 Debugging Multiple Inferiors and Programs

gdb lets you run and debug multiple programs in a single session. In addition, gdb on some systems may let you run several programs simultaneously (otherwise you have to exit from one before starting another). In the most general case, you can have multiple threads of execution in each of multiple processes, launched from multiple executables.
gdb represents the state of each program execution with an object called an inferior. An inferior typically corresponds to a process, but is more general and applies also to targets that do not have processes. Inferiors may be created before a process runs, and may be retained after a process exits. Inferiors have unique identifiers that are different from process ids. Usually each inferior will also have its own distinct address space, although some embedded targets may have several inferiors running in different parts of a single address space. Each inferior may in turn have multiple threads running in it.
To find out what inferiors exist at any moment, use info inferiors:

info inferiors

Print a list of all inferiors currently being managed by gdb. gdb displays for each inferior (in this order):

1. the inferior number assigned by gdb
2. the target system's inferior identifier
3. the name of the executable the inferior is running.

An asterisk `*' preceding the gdb inferior number indicates the current inferior.

For example,

     (gdb) info inferiors
       Num  Description       Executable
       2    process 2307      hello
     * 1    process 3401      goodbye

To switch focus between inferiors, use the inferior command:

inferior infno

Make inferior number infno the current inferior. The argument infno is the inferior number assigned by gdb, as shown in the first field of the `info inferiors' display.

You can get multiple executables into a debugging session via the add-inferior and clone-inferior commands. On some systems gdb can add inferiors to the debug session automatically by following calls to fork and exec. To remove inferiors from the debugging session use the remove-inferiors command.

add-inferior [ -copies n ] [ -exec executable ]

Adds n inferiors to be run using executable as the executable. n defaults to 1. If no executable is specified, the inferiors begins empty, with no program. You can still assign or change the program assigned to the inferior at any time by using the file command with the executable name as its argument.

clone-inferior [ -copies n ] [ infno ]

Adds n inferiors ready to execute the same program as inferior infno. n defaults to 1. infno defaults to the number of the current inferior. This is a convenient command when you want to run another instance of the inferior you are debugging.

          (gdb) info inferiors
            Num  Description       Executable
          * 1    process 29964     helloworld
          (gdb) clone-inferior
          Added inferior 2.
          1 inferiors added.
          (gdb) info inferiors
            Num  Description       Executable
            2    <null>            helloworld
          * 1    process 29964     helloworld
     

You can now simply switch focus to inferior 2 and run it.

remove-inferiors infno...

Removes the inferior or inferiors infno.... It is not possible to remove an inferior that is running with this command. For those, use the kill or detach command first.

To quit debugging one of the running inferiors that is not the current inferior, you can either detach from it by using the detach inferior command (allowing it to run independently), or kill it using the kill inferiors command:

detach inferior infno...

Detach from the inferior or inferiors identified by gdb inferior number(s) infno.... Note that the inferior's entry still stays on the list of inferiors shown by info inferiors, but its Description will show `<null>'.

kill inferiors infno...

Kill the inferior or inferiors identified by gdb inferior number(s) infno.... Note that the inferior's entry still stays on the list of inferiors shown by info inferiors, but its Description will show `<null>'.

After the successful completion of a command such as detach, detach inferiors, kill or kill inferiors, or after a normal process exit, the inferior is still valid and listed with info inferiors, ready to be restarted.
To be notified when inferiors are started or exit under gdb's control use set print inferior-events:

set print inferior-events

set print inferior-events on

set print inferior-events off

The set print inferior-events command allows you to enable or disable printing of messages when gdb notices that new inferiors have started or that inferiors have exited or have been detached. By default, these messages will not be printed.

show print inferior-events

Show whether messages will be printed when gdb detects that inferiors have started, exited or have been detached.

Many commands will work the same with multiple programs as with a single program: e.g., print myglobal will simply display the value of myglobal in the current inferior.
Occasionaly, when debugging gdb itself, it may be useful to get more info about the relationship of inferiors, programs, address spaces in a debug session. You can do that with the maint info program-spaces command.

maint info program-spaces

Print a list of all program spaces currently being managed by gdb. gdb displays for each program space (in this order):

1. the program space number assigned by gdb
2. the name of the executable loaded into the program space, with e.g., the file command.

An asterisk `*' preceding the gdb program space number indicates the current program space.

In addition, below each program space line, gdb prints extra information that isn't suitable to display in tabular form. For example, the list of inferiors bound to the program space.

          (gdb) maint info program-spaces
            Id   Executable
            2    goodbye
                  Bound inferiors: ID 1 (process 21561)
          * 1    hello
     

Here we can see that no inferior is running the program hello, while process 21561 is running the program goodbye. On some targets, it is possible that multiple inferiors are bound to the same program space. The most common example is that of debugging both the parent and child processes of a vfork call. For example,

          (gdb) maint info program-spaces
            Id   Executable
          * 1    vfork-test
                  Bound inferiors: ID 2 (process 18050), ID 1 (process 18045)
     

Here, both inferior 2 and inferior 1 are running in the same program space as a result of inferior 1 having executed a vfork call.

---

Next: Forks, Previous: Inferiors and Programs, Up: Running

4.10 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
• `set print thread-events', which controls printing of messages on thread start and exit.
• `set libthread-db-search-path path', which lets the user specify which libthread_db to use if the default choice isn't compatible with the program.

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 gnu/Linux, you might see

     [New Thread 0x41e02940 (LWP 25582)]

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 [id...]

Display a summary of all threads currently in your program. Optional argument id... is one or more thread ids separated by spaces, and means to print information only about the specified thread or threads. 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 thread's name, if one is known. A thread can either be named by the user (see thread name, below), or, in some cases, by the program itself.
4. 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
       Id   Target Id         Frame
       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

On Solaris, you can display more information about user threads with a Solaris-specific command:

maint info sol-threads

Display info on Solaris user threads.

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 thread 2 (Thread 0xb7fdab70 (LWP 12747))]
          #0  some_function (ignore=0x0) at example.c:8
          8     printf ("hello\n");
     

As with the `[New ...]' message, the form of the text after `Switching to' depends on your system's conventions for identifying threads.

The debugger convenience variable `$_thread' contains the number of the current thread. You may find this useful in writing breakpoint conditional expressions, command scripts, and so forth. See See Convenience Variables, for general information on convenience variables.

thread apply [threadno | all] command

The thread apply command allows you to apply the named command to one or more threads. Specify the numbers of the threads that you want affected with the command argument threadno. It can be a single thread number, one of the numbers shown in the first field of the `info threads' display; or it could be a range of thread numbers, as in 2-4. To apply a command to all threads, type thread apply all command.

thread name [name]

This command assigns a name to the current thread. If no argument is given, any existing user-specified name is removed. The thread name appears in the `info threads' display. On some systems, such as gnu/Linux, gdb is able to determine the name of the thread as given by the OS. On these systems, a name specified with `thread name' will override the system-give name, and removing the user-specified name will cause gdb to once again display the system-specified name.

thread find [regexp]

Search for and display thread ids whose name or systag matches the supplied regular expression. As well as being the complement to the `thread name' command, this command also allows you to identify a thread by its target systag. For instance, on gnu/Linux, the target systag is the LWP id.

          (gdb) thread find 26688
          Thread 4 has target id 'Thread 0x41e02940 (LWP 26688)'
          (gdb) info thread 4
            Id   Target Id         Frame
            4    Thread 0x41e02940 (LWP 26688) 0x00000031ca6cd372 in select ()
     

set print thread-events

set print thread-events on

set print thread-events off

The set print thread-events command allows you to enable or disable printing of messages when gdb notices that new threads have started or that threads have exited. By default, these messages will be printed if detection of these events is supported by the target. Note that these messages cannot be disabled on all targets.

show print thread-events

Show whether messages will be printed when gdb detects that threads have started and exited.

See Stopping and Starting Multi-thread Programs, for more information about how gdb behaves when you stop and start programs with multiple threads.
See Setting Watchpoints, for information about watchpoints in programs with multiple threads.

set libthread-db-search-path [path]

If this variable is set, path is a colon-separated list of directories gdb will use to search for libthread_db. If you omit path, `libthread-db-search-path' will be reset to its default value ($sdir:$pdir on gnu/Linux and Solaris systems). Internally, the default value comes from the LIBTHREAD_DB_SEARCH_PATH macro. On gnu/Linux and Solaris systems, gdb uses a “helper” libthread_db library to obtain information about threads in the inferior process. gdb will use `libthread-db-search-path' to find libthread_db.
A special entry `$sdir' for `libthread-db-search-path' refers to the default system directories that are normally searched for loading shared libraries.
A special entry `$pdir' for `libthread-db-search-path' refers to the directory from which libpthread was loaded in the inferior process.
For any libthread_db library gdb finds in above directories, gdb attempts to initialize it with the current inferior process. If this initialization fails (which could happen because of a version mismatch between libthread_db and libpthread), gdb will unload libthread_db, and continue with the next directory. If none of libthread_db libraries initialize successfully, gdb will issue a warning and thread debugging will be disabled.
Setting libthread-db-search-path is currently implemented only on some platforms.

show libthread-db-search-path

Display current libthread_db search path.

set debug libthread-db

show debug libthread-db

Turns on or off display of libthread_db-related events. Use 1 to enable, 0 to disable.

---

Next: Checkpoint/Restart, Previous: Threads, Up: Running

4.11 Debugging Forks

On most systems, 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 Attach). From that point on you can debug the child process just like any other process which you attached to.
On some systems, gdb provides support for debugging programs that create additional processes using the fork or vfork functions. Currently, the only platforms with this feature are HP-UX (11.x and later only?) and gnu/Linux (kernel version 2.5.60 and later).
By default, when a program forks, gdb will continue to debug the parent process and the child process will run unimpeded.
If you want to follow the child process instead of the parent process, use the command set follow-fork-mode.

set follow-fork-mode mode

Set the debugger response to a program call of fork or vfork. A call to fork or vfork creates a new process. The mode argument can be:

parent

The original process is debugged after a fork. The child process runs unimpeded. This is the default.

child

The new process is debugged after a fork. The parent process runs unimpeded.

show follow-fork-mode

Display the current debugger response to a fork or vfork call.

On Linux, if you want to debug both the parent and child processes, use the command set detach-on-fork.

set detach-on-fork mode

Tells gdb whether to detach one of the processes after a fork, or retain debugger control over them both.

on

The child process (or parent process, depending on the value of follow-fork-mode) will be detached and allowed to run independently. This is the default.

off

Both processes will be held under the control of gdb. One process (child or parent, depending on the value of follow-fork-mode) is debugged as usual, while the other is held suspended.

show detach-on-fork

Show whether detach-on-fork mode is on/off.

If you choose to set `detach-on-fork' mode off, then gdb will retain control of all forked processes (including nested forks). You can list the forked processes under the control of gdb by using the info inferiors command, and switch from one fork to another by using the inferior command (see Debugging Multiple Inferiors and Programs).
To quit debugging one of the forked processes, you can either detach from it by using the detach inferiors command (allowing it to run independently), or kill it using the kill inferiors command. See Debugging Multiple Inferiors and Programs.
If you ask to debug a child process and a vfork is followed by an exec, gdb executes the new target up to the first breakpoint in the new target. If you have a breakpoint set on main in your original program, the breakpoint will also be set on the child process's main.
On some systems, when a child process is spawned by vfork, you cannot debug the child or parent until an exec call completes.
If you issue a run command to gdb after an exec call executes, the new target restarts. To restart the parent process, use the file command with the parent executable name as its argument. By default, after an exec call executes, gdb discards the symbols of the previous executable image. You can change this behaviour with the set follow-exec-mode command.

set follow-exec-mode mode

Set debugger response to a program call of exec. An exec call replaces the program image of a process. follow-exec-mode can be:

new

gdb creates a new inferior and rebinds the process to this new inferior. The program the process was running before the exec call can be restarted afterwards by restarting the original inferior. For example:

               (gdb) info inferiors
               (gdb) info inferior
                 Id   Description   Executable
               * 1    <null>        prog1
               (gdb) run
               process 12020 is executing new program: prog2
               Program exited normally.
               (gdb) info inferiors
                 Id   Description   Executable
               * 2    <null>        prog2
                 1    <null>        prog1
          

same

gdb keeps the process bound to the same inferior. The new executable image replaces the previous executable loaded in the inferior. Restarting the inferior after the exec call, with e.g., the run command, restarts the executable the process was running after the exec call. This is the default mode. For example:

               (gdb) info inferiors
                 Id   Description   Executable
               * 1    <null>        prog1
               (gdb) run
               process 12020 is executing new program: prog2
               Program exited normally.
               (gdb) info inferiors
                 Id   Description   Executable
               * 1    <null>        prog2
          

You can use the catch command to make gdb stop whenever a fork, vfork, or exec call is made. See Setting Catchpoints.

---

Previous: Forks, Up: Running

4.12 Setting a Bookmark to Return to Later

On certain operating systems³, gdb is able to save a snapshot of a program's state, called a checkpoint, and come back to it later.
Returning to a checkpoint effectively undoes everything that has happened in the program since the checkpoint was saved. This includes changes in memory, registers, and even (within some limits) system state. Effectively, it is like going back in time to the moment when the checkpoint was saved.
Thus, if you're stepping thru a program and you think you're getting close to the point where things go wrong, you can save a checkpoint. Then, if you accidentally go too far and miss the critical statement, instead of having to restart your program from the beginning, you can just go back to the checkpoint and start again from there.
This can be especially useful if it takes a lot of time or steps to reach the point where you think the bug occurs.
To use the checkpoint/restart method of debugging:

checkpoint

Save a snapshot of the debugged program's current execution state. The checkpoint command takes no arguments, but each checkpoint is assigned a small integer id, similar to a breakpoint id.

info checkpoints

List the checkpoints that have been saved in the current debugging session. For each checkpoint, the following information will be listed:

Checkpoint ID

Process ID

Code Address

Source line, or label

restart checkpoint-id

Restore the program state that was saved as checkpoint number checkpoint-id. All program variables, registers, stack frames etc. will be returned to the values that they had when the checkpoint was saved. In essence, gdb will “wind back the clock” to the point in time when the checkpoint was saved. Note that breakpoints, gdb variables, command history etc. are not affected by restoring a checkpoint. In general, a checkpoint only restores things that reside in the program being debugged, not in the debugger.

delete checkpoint checkpoint-id

Delete the previously-saved checkpoint identified by checkpoint-id.

Returning to a previously saved checkpoint will restore the user state of the program being debugged, plus a significant subset of the system (OS) state, including file pointers. It won't “un-write” data from a file, but it will rewind the file pointer to the previous location, so that the previously written data can be overwritten. For files opened in read mode, the pointer will also be restored so that the previously read data can be read again.
Of course, characters that have been sent to a printer (or other external device) cannot be “snatched back”, and characters received from eg. a serial device can be removed from internal program buffers, but they cannot be “pushed back” into the serial pipeline, ready to be received again. Similarly, the actual contents of files that have been changed cannot be restored (at this time).
However, within those constraints, you actually can “rewind” your program to a previously saved point in time, and begin debugging it again — and you can change the course of events so as to debug a different execution path this time.
Finally, there is one bit of internal program state that will be different when you return to a checkpoint — the program's process id. Each checkpoint will have a unique process id (or pid), and each will be different from the program's original pid. If your program has saved a local copy of its process id, this could potentially pose a problem.

4.12.1 A Non-obvious Benefit of Using Checkpoints

On some systems such as gnu/Linux, address space randomization is performed on new processes for security reasons. This makes it difficult or impossible to set a breakpoint, or watchpoint, on an absolute address if you have to restart the program, since the absolute location of a symbol will change from one execution to the next.
A checkpoint, however, is an identical copy of a process. Therefore if you create a checkpoint at (eg.) the start of main, and simply return to that checkpoint instead of restarting the process, you can avoid the effects of address randomization and your symbols will all stay in the same place.

---

Next: Reverse Execution, Previous: Running, Up: Top

5 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.

• Breakpoints: Breakpoints, watchpoints, and catchpoints
• Continuing and Stepping: Resuming execution
• Skipping Over Functions and Files Skipping over functions and files
• Signals: Signals
• Thread Stops: Stopping and starting multi-thread programs

---

Next: Continuing and Stepping, Up: Stopping

5.1 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 (see Setting Breakpoints), to specify the place where your program should stop by line number, function name or exact address in the program.
On some systems, 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. The expression may be a value of a variable, or it could involve values of one or more variables combined by operators, such as `a + b'. This is sometimes called data breakpoints. You must use a different command to set watchpoints (see Setting 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. See Automatic 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 (see Setting 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; see 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.
Some gdb commands accept a range of breakpoints on which to operate. A breakpoint range is either a single breakpoint number, like `5', or two such numbers, in increasing order, separated by a hyphen, like `5-7'. When a breakpoint range is given to a command, all breakpoints in that range are operated on.

• 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
• Save Breakpoints: How to save breakpoints in a file
• Error in Breakpoints: ``Cannot insert breakpoints''
• Breakpoint-related Warnings: ``Breakpoint address adjusted...''

---

Next: Set Watchpoints, Up: Breakpoints

5.1.1 Setting Breakpoints

Breakpoints are set with the break command (abbreviated b). The debugger convenience variable `$bpnum' records the number of the breakpoint you've set most recently; see Convenience Variables, for a discussion of what you can do with convenience variables.

break location

Set a breakpoint at the given location, which can specify a function name, a line number, or an address of an instruction. (See Specify Location, for a list of all the possible ways to specify a location.) The breakpoint will stop your program just before it executes any of the code in the specified location. When using source languages that permit overloading of symbols, such as C++, a function name may refer to more than one possible place to break. See Ambiguous Expressions, for a discussion of that situation.
It is also possible to insert a breakpoint that will stop the program only if a specific thread (see Thread-Specific Breakpoints) or a specific task (see Ada Tasks) hits that breakpoint.

break

When called without any arguments, break sets a breakpoint at the next instruction to be executed in the selected stack frame (see Examining the 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. See Break 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. See Disabling Breakpoints.

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 and most x86-based targets. These targets 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 take a limited number of breakpoints. For example, on the DSU, only two data breakpoints can be set at a time, and gdb will reject this command if more than two are used. Delete or disable unused hardware breakpoints before setting new ones (see Disabling Breakpoints). See Break Conditions. For remote targets, you can restrict the number of hardware breakpoints gdb will use, see set remote hardware-breakpoint-limit.

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. See Disabling Breakpoints. See also Break 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. The syntax of the regular expression is the standard one used with tools like grep. Note that this is different from the syntax used by shells, so for instance foo* matches all functions that include an fo followed by zero or more os. There is an implicit .* leading and trailing the regular expression you supply, so to match only functions that begin with foo, use ^foo.
When debugging C++ programs, rbreak is useful for setting breakpoints on overloaded functions that are not members of any special classes.
The rbreak command can be used to set breakpoints in all the functions in a program, like this:

          (gdb) rbreak .
     

rbreak file:regex

If rbreak is called with a filename qualification, it limits the search for functions matching the given regular expression to the specified file. This can be used, for example, to set breakpoints on every function in a given file:

          (gdb) rbreak file.c:.
     

The colon separating the filename qualifier from the regex may optionally be surrounded by spaces.

info breakpoints [n...]

info break [n...]

Print a table of all breakpoints, watchpoints, and catchpoints set and not deleted. Optional argument n means print information only about the specified breakpoint(s) (or watchpoint(s) or catchpoint(s)). For each breakpoint, following columns are printed:

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. For a pending breakpoint whose address is not yet known, this field will contain `<PENDING>'. Such breakpoint won't fire until a shared library that has the symbol or line referred by breakpoint is loaded. See below for details. A breakpoint with several locations will have `<MULTIPLE>' in this field—see below for details.

What

Where the breakpoint is in the source for your program, as a file and line number. For a pending breakpoint, the original string passed to the breakpoint command will be listed as it cannot be resolved until the appropriate shared library is loaded in the future.

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. A pending breakpoint is allowed to have a condition specified for it. The condition is not parsed for validity until a shared library is loaded that allows the pending breakpoint to resolve to a valid location.

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 (see Examining 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 (see Break Conditions).
It is possible that a breakpoint corresponds to several locations in your program. Examples of this situation are:

• For a C++ constructor, the gcc compiler generates several instances of the function body, used in different cases.
• For a C++ template function, a given line in the function can correspond to any number of instantiations.
• For an inlined function, a given source line can correspond to several places where that function is inlined.

In all those cases, gdb will insert a breakpoint at all the relevant locations⁴.
A breakpoint with multiple locations is displayed in the breakpoint table using several rows—one header row, followed by one row for each breakpoint location. The header row has `<MULTIPLE>' in the address column. The rows for individual locations contain the actual addresses for locations, and show the functions to which those locations belong. The number column for a location is of the form breakpoint-number.location-number.
For example:

     Num     Type           Disp Enb  Address    What
     1       breakpoint     keep y    <MULTIPLE>
             stop only if i==1
             breakpoint already hit 1 time
     1.1                         y    0x080486a2 in void foo<int>() at t.cc:8
     1.2                         y    0x080486ca in void foo<double>() at t.cc:8

Each location can be individually enabled or disabled by passing breakpoint-number.location-number as argument to the enable and disable commands. Note that you cannot delete the individual locations from the list, you can only delete the entire list of locations that belong to their parent breakpoint (with the delete num command, where num is the number of the parent breakpoint, 1 in the above example). Disabling or enabling the parent breakpoint (see Disabling) affects all of the locations that belong to that breakpoint.
It's quite common to have a breakpoint inside a shared library. Shared libraries can be loaded and unloaded explicitly, and possibly repeatedly, as the program is executed. To support this use case, gdb updates breakpoint locations whenever any shared library is loaded or unloaded. Typically, you would set a breakpoint in a shared library at the beginning of your debugging session, when the library is not loaded, and when the symbols from the library are not available. When you try to set breakpoint, gdb will ask you if you want to set a so called pending breakpoint—breakpoint whose address is not yet resolved.
After the program is run, whenever a new shared library is loaded, gdb reevaluates all the breakpoints. When a newly loaded shared library contains the symbol or line referred to by some pending breakpoint, that breakpoint is resolved and becomes an ordinary breakpoint. When a library is unloaded, all breakpoints that refer to its symbols or source lines become pending again.
This logic works for breakpoints with multiple locations, too. For example, if you have a breakpoint in a C++ template function, and a newly loaded shared library has an instantiation of that template, a new location is added to the list of locations for the breakpoint.
Except for having unresolved address, pending breakpoints do not differ from regular breakpoints. You can set conditions or commands, enable and disable them and perform other breakpoint operations.
gdb provides some additional commands for controlling what happens when the `break' command cannot resolve breakpoint address specification to an address:

set breakpoint pending auto

This is the default behavior. When gdb cannot find the breakpoint location, it queries you whether a pending breakpoint should be created.

set breakpoint pending on

This indicates that an unrecognized breakpoint location should automatically result in a pending breakpoint being created.

set breakpoint pending off

This indicates that pending breakpoints are not to be created. Any unrecognized breakpoint location results in an error. This setting does not affect any pending breakpoints previously created.

show breakpoint pending

Show the current behavior setting for creating pending breakpoints.

The settings above only affect the break command and its variants. Once breakpoint is set, it will be automatically updated as shared libraries are loaded and unloaded.
For some targets, gdb can automatically decide if hardware or software breakpoints should be used, depending on whether the breakpoint address is read-only or read-write. This applies to breakpoints set with the break command as well as to internal breakpoints set by commands like next and finish. For breakpoints set with hbreak, gdb will always use hardware breakpoints.
You can control this automatic behaviour with the following commands::

set breakpoint auto-hw on

This is the default behavior. When gdb sets a breakpoint, it will try to use the target memory map to decide if software or hardware breakpoint must be used.

set breakpoint auto-hw off

This indicates gdb should not automatically select breakpoint type. If the target provides a memory map, gdb will warn when trying to set software breakpoint at a read-only address.

gdb normally implements breakpoints by replacing the program code at the breakpoint address with a special instruction, which, when executed, given control to the debugger. By default, the program code is so modified only when the program is resumed. As soon as the program stops, gdb restores the original instructions. This behaviour guards against leaving breakpoints inserted in the target should gdb abrubptly disconnect. However, with slow remote targets, inserting and removing breakpoint can reduce the performance. This behavior can be controlled with the following commands::

set breakpoint always-inserted off

All breakpoints, including newly added by the user, are inserted in the target only when the target is resumed. All breakpoints are removed from the target when it stops.

set breakpoint always-inserted on

Causes all breakpoints to be inserted in the target at all times. If the user adds a new breakpoint, or changes an existing breakpoint, the breakpoints in the target are updated immediately. A breakpoint is removed from the target only when breakpoint itself is removed.

set breakpoint always-inserted auto

This is the default mode. If gdb is controlling the inferior in non-stop mode (see Non-Stop Mode), gdb behaves as if breakpoint always-inserted mode is on. If gdb is controlling the inferior in all-stop mode, gdb behaves as if breakpoint always-inserted mode is off.

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' (see maint info breakpoints).

---

Next: Set Catchpoints, Previous: Set Breaks, Up: Breakpoints

5.1.2 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. (This is sometimes called a data breakpoint.) The expression may be as simple as the value of a single variable, or as complex as many variables combined by operators. Examples include:

• A reference to the value of a single variable.
• An address cast to an appropriate data type. For example, `*(int *)0x12345678' will watch a 4-byte region at the specified address (assuming an int occupies 4 bytes).
• An arbitrarily complex expression, such as `a*b + c/d'. The expression can use any operators valid in the program's native language (see Languages).

You can set a watchpoint on an expression even if the expression can not be evaluated yet. For instance, you can set a watchpoint on `*global_ptr' before `global_ptr' is initialized. gdb will stop when your program sets `global_ptr' and the expression produces a valid value. If the expression becomes valid in some other way than changing a variable (e.g. if the memory pointed to by `*global_ptr' becomes readable as the result of a malloc call), gdb may not stop until the next time the expression changes.
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, PowerPC, gnu/Linux and most other x86-based targets, gdb includes support for hardware watchpoints, which do not slow down the running of your program.

watch [-l|-location] expr [thread threadnum] [mask maskvalue]

Set a watchpoint for an expression. gdb will break when the expression expr is written into by the program and its value changes. The simplest (and the most popular) use of this command is to watch the value of a single variable:

          (gdb) watch foo
     

If the command includes a [thread threadnum] argument, gdb breaks only when the thread identified by threadnum changes the value of expr. If any other threads change the value of expr, gdb will not break. Note that watchpoints restricted to a single thread in this way only work with Hardware Watchpoints.
Ordinarily a watchpoint respects the scope of variables in expr (see below). The -location argument tells gdb to instead watch the memory referred to by expr. In this case, gdb will evaluate expr, take the address of the result, and watch the memory at that address. The type of the result is used to determine the size of the watched memory. If the expression's result does not have an address, then gdb will print an error.
The [mask maskvalue] argument allows creation of masked watchpoints, if the current architecture supports this feature (e.g., PowerPC Embedded architecture, see PowerPC Embedded.) A masked watchpoint specifies a mask in addition to an address to watch. The mask specifies that some bits of an address (the bits which are reset in the mask) should be ignored when matching the address accessed by the inferior against the watchpoint address. Thus, a masked watchpoint watches many addresses simultaneously—those addresses whose unmasked bits are identical to the unmasked bits in the watchpoint address. The mask argument implies -location. Examples:

          (gdb) watch foo mask 0xffff00ff
          (gdb) watch *0xdeadbeef mask 0xffffff00
     

rwatch [-l|-location] expr [thread threadnum] [mask maskvalue]

Set a watchpoint that will break when the value of expr is read by the program.

awatch [-l|-location] expr [thread threadnum] [mask maskvalue]

Set a watchpoint that will break when expr is either read from or written into by the program.

info watchpoints [n...]

This command prints a list of watchpoints, using the same format as info break (see Set Breaks).

If you watch for a change in a numerically entered address you need to dereference it, as the address itself is just a constant number which will never change. gdb refuses to create a watchpoint that watches a never-changing value:

     (gdb) watch 0x600850
     Cannot watch constant value 0x600850.
     (gdb) watch *(int *) 0x600850
     Watchpoint 1: *(int *) 6293584

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.
You can force gdb to use only software watchpoints with the set can-use-hw-watchpoints 0 command. With this variable set to zero, gdb will never try to use hardware watchpoints, even if the underlying system supports them. (Note that hardware-assisted watchpoints that were set before setting can-use-hw-watchpoints to zero will still use the hardware mechanism of watching expression values.)

set can-use-hw-watchpoints

Set whether or not to use hardware watchpoints.

show can-use-hw-watchpoints

Show the current mode of using hardware watchpoints.

For remote targets, you can restrict the number of hardware watchpoints gdb will use, see set remote hardware-breakpoint-limit.
When you issue the watch command, gdb reports

     Hardware watchpoint num: expr

if it was able to set a hardware watchpoint.

Currently, the awatch and rwatch commands can only set hardware watchpoints, because accesses to data that don't change the value of the watched expression cannot be detected without examining every instruction as it is being executed, and gdb does not do that currently. If gdb finds that it is unable to set a hardware breakpoint with the awatch or rwatch command, it will print a message like this:

     Expression cannot be implemented with read/access watchpoint.

Sometimes, gdb cannot set a hardware watchpoint because the data type of the watched expression is wider than what a hardware watchpoint on the target machine can handle. For example, some systems can only watch regions that are up to 4 bytes wide; on such systems you cannot set hardware watchpoints for an expression that yields a double-precision floating-point number (which is typically 8 bytes wide). As a work-around, it might be possible to break the large region into a series of smaller ones and watch them with separate watchpoints.
If you set too many hardware watchpoints, gdb might be unable to insert all of them when you resume the execution of your program. Since the precise number of active watchpoints is unknown until such time as the program is about to be resumed, gdb might not be able to warn you about this when you set the watchpoints, and the warning will be printed only when the program is resumed:

     Hardware watchpoint num: Could not insert watchpoint

If this happens, delete or disable some of the watchpoints.

Watching complex expressions that reference many variables can also exhaust the resources available for hardware-assisted watchpoints. That's because gdb needs to watch every variable in the expression with separately allocated resources.
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.
gdb automatically deletes watchpoints that watch local (automatic) variables, or expressions that involve such variables, when they go out of scope, that is, when the execution leaves the block in which these variables were defined. In particular, when the program being debugged terminates, all local variables go out of scope, and so only watchpoints that watch global variables remain set. If you rerun the program, you will need to set all such watchpoints again. One way of doing that would be to set a code breakpoint at the entry to the main function and when it breaks, set all the watchpoints.
In multi-threaded programs, watchpoints will detect changes to the watched expression from every thread.

Warning: In multi-threaded programs, software watchpoints have only limited usefulness. If gdb creates a software watchpoint, it 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 software watchpoints as usual. However, gdb may not notice when a non-current thread's activity changes the expression. (Hardware watchpoints, in contrast, watch an expression in all threads.)

See set remote hardware-watchpoint-limit.

---

Next: Delete Breaks, Previous: Set Watchpoints, Up: Breakpoints

5.1.3 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.

exception

An Ada exception being raised. If an exception name is specified at the end of the command (eg catch exception Program_Error), the debugger will stop only when this specific exception is raised. Otherwise, the debugger stops execution when any Ada exception is raised. When inserting an exception catchpoint on a user-defined exception whose name is identical to one of the exceptions defined by the language, the fully qualified name must be used as the exception name. Otherwise, gdb will assume that it should stop on the pre-defined exception rather than the user-defined one. For instance, assuming an exception called Constraint_Error is defined in package Pck, then the command to use to catch such exceptions is catch exception Pck.Constraint_Error.

exception unhandled

An exception that was raised but is not handled by the program.

assert

A failed Ada assertion.

exec

A call to exec. This is currently only available for HP-UX and gnu/Linux.

syscall

syscall [name | number] ...

A call to or return from a system call, a.k.a. syscall. A syscall is a mechanism for application programs to request a service from the operating system (OS) or one of the OS system services. gdb can catch some or all of the syscalls issued by the debuggee, and show the related information for each syscall. If no argument is specified, calls to and returns from all system calls will be caught. name can be any system call name that is valid for the underlying OS. Just what syscalls are valid depends on the OS. On GNU and Unix systems, you can find the full list of valid syscall names on /usr/include/asm/unistd.h.
Normally, gdb knows in advance which syscalls are valid for each OS, so you can use the gdb command-line completion facilities (see command completion) to list the available choices.
You may also specify the system call numerically. A syscall's number is the value passed to the OS's syscall dispatcher to identify the requested service. When you specify the syscall by its name, gdb uses its database of syscalls to convert the name into the corresponding numeric code, but using the number directly may be useful if gdb's database does not have the complete list of syscalls on your system (e.g., because gdb lags behind the OS upgrades).
The example below illustrates how this command works if you don't provide arguments to it:

               (gdb) catch syscall
               Catchpoint 1 (syscall)
               (gdb) r
               Starting program: /tmp/catch-syscall
               
               Catchpoint 1 (call to syscall 'close'), \
                   0xffffe424 in __kernel_vsyscall ()
               (gdb) c
               Continuing.
               
               Catchpoint 1 (returned from syscall 'close'), \
                0xffffe424 in __kernel_vsyscall ()
               (gdb)
          

Here is an example of catching a system call by name:

               (gdb) catch syscall chroot
               Catchpoint 1 (syscall 'chroot' [61])
               (gdb) r
               Starting program: /tmp/catch-syscall
               
               Catchpoint 1 (call to syscall 'chroot'), \
                    0xffffe424 in __kernel_vsyscall ()
               (gdb) c
               Continuing.
               
               Catchpoint 1 (returned from syscall 'chroot'), \
                0xffffe424 in __kernel_vsyscall ()
               (gdb)
          

An example of specifying a system call numerically. In the case below, the syscall number has a corresponding entry in the XML file, so gdb finds its name and prints it:

               (gdb) catch syscall 252
               Catchpoint 1 (syscall(s) 'exit_group')
               (gdb) r
               Starting program: /tmp/catch-syscall
               
               Catchpoint 1 (call to syscall 'exit_group'), \
                    0xffffe424 in __kernel_vsyscall ()
               (gdb) c
               Continuing.
               
               Program exited normally.
               (gdb)
          

However, there can be situations when there is no corresponding name in XML file for that syscall number. In this case, gdb prints a warning message saying that it was not able to find the syscall name, but the catchpoint will be set anyway. See the example below:

               (gdb) catch syscall 764
               warning: The number '764' does not represent a known syscall.
               Catchpoint 2 (syscall 764)
               (gdb)
          

If you configure gdb using the `--without-expat' option, it will not be able to display syscall names. Also, if your architecture does not have an XML file describing its system calls, you will not be able to see the syscall names. It is important to notice that these two features are used for accessing the syscall name database. In either case, you will see a warning like this:

               (gdb) catch syscall
               warning: Could not open "syscalls/i386-linux.xml"
               warning: Could not load the syscall XML file 'syscalls/i386-linux.xml'.
               GDB will not be able to display syscall names.
               Catchpoint 1 (syscall)
               (gdb)
          

Of course, the file name will change depending on your architecture and system.
Still using the example above, you can also try to catch a syscall by its number. In this case, you would see something like:

               (gdb) catch syscall 252
               Catchpoint 1 (syscall(s) 252)
          

Again, in this case gdb would not be able to display syscall's names.

fork

A call to fork. This is currently only available for HP-UX and gnu/Linux.

vfork

A call to vfork. This is currently only available for HP-UX and gnu/Linux.

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 (see Breakpoints; Watchpoints; and Exceptions).

With a conditional breakpoint (see Break 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.

---

Next: Disabling, Previous: Set Catchpoints, Up: Breakpoints

5.1.4 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 (see Selecting a Frame). When the innermost frame is selected, this is a good way to delete a breakpoint where your program just stopped.

clear location

Delete any breakpoints set at the specified location. See Specify Location, for the various forms of location; the most useful ones are listed below:

clear function

clear filename:function

Delete any breakpoints set at entry to the named function.

clear linenum

clear filename:linenum

Delete any breakpoints set at or within the code of the specified linenum of the specified filename.

delete [breakpoints] [range...]

Delete the breakpoints, watchpoints, or catchpoints of the breakpoint ranges 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.

---

Next: Conditions, Previous: Delete Breaks, Up: Breakpoints

5.1.5 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 to print a list of all breakpoints, watchpoints, and catchpoints if you do not know which numbers to use.
Disabling and enabling a breakpoint that has multiple locations affects all of its locations.
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.
• Enabled for deletion. The breakpoint stops your program, but immediately after it does so it is deleted permanently. A breakpoint set with the tbreak command starts out in this state.

You can use the following commands to enable or disable breakpoints, watchpoints, and catchpoints:

disable [breakpoints] [range...]

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] [range...]

Enable the specified breakpoints (or all defined breakpoints). They become effective once again in stopping your program.

enable [breakpoints] once range...

Enable the specified breakpoints temporarily. gdb disables any of these breakpoints immediately after stopping your program.

enable [breakpoints] delete range...

Enable the specified breakpoints to work once, then die. gdb deletes any of these breakpoints as soon as your program stops there. Breakpoints set by the tbreak command start out in this state.

Except for a breakpoint set with tbreak (see Setting Breakpoints), 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 Continuing and Stepping.)

---

Next: Break Commands, Previous: Disabling, Up: Breakpoints

5.1.6 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 (see 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 than break conditions for the purpose of performing side effects when a breakpoint is reached (see Breakpoint Command Lists).
Break conditions can be specified when a breakpoint is set, by using `if' in the arguments to the break command. See Setting Breakpoints. They can also be changed at any time with the condition command.
You can also use the if keyword with the watch command. The catch command does not recognize the if keyword; condition is the only way to impose a further condition on a catchpoint.

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. If expression uses symbols not referenced in the context of the breakpoint, gdb prints an error message:

          No symbol "foo" in current context.
     

gdb does not actually evaluate expression at the time the condition command (or a command that sets a breakpoint with a condition, like break if ...) is given, however. See 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. See 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. See Convenience Variables.

Ignore counts apply to breakpoints, watchpoints, and catchpoints.

---

Next: Save Breakpoints, Previous: Conditions, Up: Breakpoints

5.1.7 Breakpoint Command Lists

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.

commands [range...]

... command-list ...

end

Specify a list of commands for the given breakpoints. The commands themselves appear on the following lines. Type a line containing just end to terminate the commands. To remove all commands from a breakpoint, type commands and follow it immediately with end; that is, give no commands.
With no argument, commands refers to the last breakpoint, watchpoint, or catchpoint set (not to the breakpoint most recently encountered). If the most recent breakpoints were set with a single command, then the commands will apply to all the breakpoints set by that command. This applies to breakpoints set by rbreak, and also applies when a single break command creates multiple breakpoints (see Ambiguous Expressions).

Pressing <RET> as a means of repeating the last gdb command is disabled within a command-list.
You can use breakpoint commands to start your program up again. Simply use the continue command, or step, or any other command that resumes execution.
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 next or step), you may encounter another breakpoint—which could have its own command list, leading to ambiguities about which list to execute.
If the first command you specify in a command list is silent, 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. silent is meaningful only at the beginning of a breakpoint command list.
The commands echo, output, and printf allow you to print precisely controlled output, and are often useful in silent breakpoints. See Commands for Controlled Output.
For example, here is how you could use breakpoint commands to print the value of x at entry to foo whenever x is positive.

     break foo if x>0
     commands
     silent
     printf "x is %d\n",x
     cont
     end

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 continue command so that your program does not stop, and start with the silent command so that no output is produced. Here is an example:

     break 403
     commands
     silent
     set x = y + 4
     cont
     end

---

Next: Error in Breakpoints, Previous: Break Commands, Up: Breakpoints

5.1.8 How to save breakpoints to a file

To save breakpoint definitions to a file use the save breakpoints command.

save breakpoints [filename]

This command saves all current breakpoint definitions together with their commands and ignore counts, into a file filename suitable for use in a later debugging session. This includes all types of breakpoints (breakpoints, watchpoints, catchpoints, tracepoints). To read the saved breakpoint definitions, use the source command (see Command Files). Note that watchpoints with expressions involving local variables may fail to be recreated because it may not be possible to access the context where the watchpoint is valid anymore. Because the saved breakpoint definitions are simply a sequence of gdb commands that recreate the breakpoints, you can edit the file in your favorite editing program, and remove the breakpoint definitions you're not interested in, or that can no longer be recreated.

---

Next: Breakpoint-related Warnings, Previous: Save Breakpoints, Up: Breakpoints

5.1.9 “Cannot insert breakpoints”

If you request too many active hardware-assisted breakpoints and watchpoints, you will see this error message: