\input texinfo @c -*-texinfo-*-
-@c Copyright (C) 1988-2017 Free Software Foundation, Inc.
+@c Copyright (C) 1988-2018 Free Software Foundation, Inc.
@c
@c %**start of header
@c makeinfo ignores cmds prev to setfilename, so its arg cannot make use
@copying
@c man begin COPYRIGHT
-Copyright @copyright{} 1988-2017 Free Software Foundation, Inc.
+Copyright @copyright{} 1988-2018 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
@end ifset
Version @value{GDBVN}.
-Copyright (C) 1988-2017 Free Software Foundation, Inc.
+Copyright (C) 1988-2018 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
You can also change @value{GDBN}'s current working directory by using
the @code{cd} command.
-@xref{cd command}
+@xref{cd command}.
@kindex show cwd
@cindex show inferior's working directory
The @value{GDBN} working directory serves as a default for the
commands that specify files for @value{GDBN} to operate on.
@xref{Files, ,Commands to Specify Files}.
-@xref{set cwd command}
+@xref{set cwd command}.
@kindex pwd
@item pwd
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 @value{GDBN} is
-configured with the @file{/proc} support, you can use the @code{info
-proc} command (@pxref{SVR4 Process Information}) to find out the
+during its run). If you work on a system where @value{GDBN} supports
+the @code{info proc} command (@pxref{Process Information}), you can
+use the @code{info proc} command to find out the
current working directory of the debuggee.
@node Input/Output
the command to use to catch such exceptions is @kbd{catch exception
Pck.Constraint_Error}.
+@item handlers
+@kindex catch handlers
+@cindex Ada exception handlers catching
+@cindex catch Ada exceptions when handled
+An Ada exception being handled. If an exception name is
+specified at the end of the command
+ (eg @kbd{catch handlers Program_Error}), the debugger will stop
+only when this specific exception is handled.
+Otherwise, the debugger stops execution when any Ada exception is handled.
+
+When inserting a handlers 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, @value{GDBN} will assume that it
+should stop on the pre-defined exception rather than the
+user-defined one. For instance, assuming an exception called
+ @code{Constraint_Error} is defined in package @code{Pck}, then the
+command to use to catch such exceptions handling is
+@kbd{catch handlers Pck.Constraint_Error}.
+
@item exception unhandled
@kindex catch exception unhandled
An exception that was raised but is not handled by the program.
@table @code
@kindex info line
-@item info line @var{location}
+@item info line
+@itemx info line @var{location}
Print the starting and ending addresses of the compiled code for
source line @var{location}. You can specify source lines in any of
-the ways documented in @ref{Specify Location}.
+the ways documented in @ref{Specify Location}. With no @var{location}
+information about the current source line is printed.
@end table
For example, we can use @code{info line} to discover the location of
the object code for the first line of function
@code{m4_changequote}:
-@c FIXME: I think this example should also show the addresses in
-@c symbolic form, as they usually would be displayed.
@smallexample
(@value{GDBP}) info line m4_changequote
-Line 895 of "builtin.c" starts at pc 0x634c and ends at 0x6350.
+Line 895 of "builtin.c" starts at pc 0x634c <m4_changequote> and \
+ ends at 0x6350 <m4_changequote+4>.
@end smallexample
@noindent
@var{location}) what source line covers a particular address:
@smallexample
(@value{GDBP}) info line *0x63ff
-Line 926 of "builtin.c" starts at pc 0x63e4 and ends at 0x6404.
+Line 926 of "builtin.c" starts at pc 0x63e4 <m4_changequote+152> and \
+ ends at 0x6404 <m4_changequote+184>.
@end smallexample
@cindex @code{$_} and @code{info line}
convenience variable @code{$_} (@pxref{Convenience Vars, ,Convenience
Variables}).
+@cindex info line, repeated calls
+After @code{info line}, using @code{info line} again without
+specifying a location will display information about the next source
+line.
+
@table @code
@kindex disassemble
@cindex assembly instructions
Print the names and values of all registers, including floating-point
and vector registers (in the selected stack frame).
+@item info registers @var{reggroup} @dots{}
+Print the name and value of the registers in each of the specified
+@var{reggroup}s. The @var{reggoup} can be any of those returned by
+@code{maint print reggroups} (@pxref{Maintenance Commands}).
+
@item info registers @var{regname} @dots{}
Print the @dfn{relativized} value of each specified register @var{regname}.
As discussed in detail below, register values are normally relative to
@value{GDBN} provides a way to build an index, which speeds up
startup.
+For convenience, @value{GDBN} comes with a program,
+@command{gdb-add-index}, which can be used to add the index to a
+symbol file. It takes the symbol file as its only argument:
+
+@smallexample
+$ gdb-add-index symfile
+@end smallexample
+
+@xref{gdb-add-index}.
+
+It is also possible to do the work manually. Here is what
+@command{gdb-add-index} does behind the curtains.
+
The index is stored as a section in the symbol file. @value{GDBN} can
write the index to a file, then you can put it into the symbol file
using @command{objcopy}.
@menu
* BSD libkvm Interface:: Debugging BSD kernel memory images
-* SVR4 Process Information:: SVR4 process information
+* Process Information:: Process information
* DJGPP Native:: Features specific to the DJGPP port
* Cygwin Native:: Features specific to the Cygwin port
* Hurd Native:: Features specific to @sc{gnu} Hurd
modern FreeBSD systems.
@end table
-@node SVR4 Process Information
-@subsection SVR4 Process Information
+@node Process Information
+@subsection Process Information
@cindex /proc
@cindex examine process image
@cindex process info via @file{/proc}
-Many versions of SVR4 and compatible systems provide a facility called
-@samp{/proc} that can be used to examine the image of a running
-process using file-system subroutines.
+Some operating systems provide interfaces to fetch additional
+information about running processes beyond memory and per-thread
+register state. If @value{GDBN} is configured for an operating system
+with a supported interface, the command @code{info proc} is available
+to report information about the process running your program, or about
+any process running on your system.
-If @value{GDBN} is configured for an operating system with this
-facility, the command @code{info proc} is available to report
-information about the process running your program, or about any
-process running on your system. This includes, as of this writing,
-@sc{gnu}/Linux and Solaris, for example.
+One supported interface is a facility called @samp{/proc} that can be
+used to examine the image of a running process using file-system
+subroutines. This facility is supported on @sc{gnu}/Linux and Solaris
+systems.
-This command may also work on core files that were created on a system
-that has the @samp{/proc} facility.
+On FreeBSD systems, system control nodes are used to query process
+information.
+
+In addition, some systems may provide additional process information
+in core files. Note that a core file may include a subset of the
+information available from a live process. Process information is
+currently avaiable from cores created on @sc{gnu}/Linux and FreeBSD
+systems.
@table @code
@kindex info proc
@item info proc cmdline
@cindex info proc cmdline
Show the original command line of the process. This command is
-specific to @sc{gnu}/Linux.
+supported on @sc{gnu}/Linux and FreeBSD.
@item info proc cwd
@cindex info proc cwd
Show the current working directory of the process. This command is
-specific to @sc{gnu}/Linux.
+supported on @sc{gnu}/Linux and FreeBSD.
@item info proc exe
@cindex info proc exe
-Show the name of executable of the process. This command is specific
-to @sc{gnu}/Linux.
+Show the name of executable of the process. This command is supported
+on @sc{gnu}/Linux and FreeBSD.
@item info proc mappings
@cindex memory address space mappings
-Report the memory address space ranges accessible in the program, with
-information on whether the process has read, write, or execute access
-rights to each range. On @sc{gnu}/Linux systems, each memory range
-includes the object file which is mapped to that range, instead of the
-memory access rights to that range.
+Report the memory address space ranges accessible in the program. On
+Solaris and FreeBSD systems, each memory range includes information on
+whether the process has read, write, or execute access rights to each
+range. On @sc{gnu}/Linux and FreeBSD systems, each memory range
+includes the object file which is mapped to that range.
@item info proc stat
@itemx info proc status
@cindex process detailed status information
-These subcommands are specific to @sc{gnu}/Linux systems. They show
-the process-related information, including the user ID and group ID;
-how many threads are there in the process; its virtual memory usage;
-the signals that are pending, blocked, and ignored; its TTY; its
-consumption of system and user time; its stack size; its @samp{nice}
-value; etc. For more information, see the @samp{proc} man page
-(type @kbd{man 5 proc} from your shell prompt).
+Show additional process-related information, including the user ID and
+group ID; virtual memory usage; the signals that are pending, blocked,
+and ignored; its TTY; its consumption of system and user time; its
+stack size; its @samp{nice} value; etc. These commands are supported
+on @sc{gnu}/Linux and FreeBSD.
+
+For @sc{gnu}/Linux systems, see the @samp{proc} man page for more
+information (type @kbd{man 5 proc} from your shell prompt).
+
+For FreeBSD systems, @code{info proc stat} is an alias for @code{info
+proc status}.
@item info proc all
Show all the information about the process described under all of the
Turns on or off debugging messages from the FreeBSD LWP debug support.
@item show debug fbsd-lwp
Show the current state of FreeBSD LWP debugging messages.
+@item set debug fbsd-nat
+@cindex FreeBSD native target debug messages
+Turns on or off debugging messages from the FreeBSD native target.
+@item show debug fbsd-nat
+Show the current state of FreeBSD native target debugging messages.
@item set debug frame
@cindex frame debugging info
Turns on or off display of @value{GDBN} frame debugging info. The
(gdb)
@end smallexample
+@subheading The @code{-catch-handlers} Command
+@findex -catch-handlers
+
+@subsubheading Synopsis
+
+@smallexample
+ -catch-handlers [ -c @var{condition}] [ -d ] [ -e @var{exception-name} ]
+ [ -t ]
+@end smallexample
+
+Add a catchpoint stopping when Ada exceptions are handled.
+By default, the command stops the program when any Ada exception
+gets handled. But it is also possible, by using some of the
+optional parameters described below, to create more selective
+catchpoints.
+
+The possible optional parameters for this command are:
+
+@table @samp
+@item -c @var{condition}
+Make the catchpoint conditional on @var{condition}.
+@item -d
+Create a disabled catchpoint.
+@item -e @var{exception-name}
+Only stop when @var{exception-name} is handled.
+@item -t
+Create a temporary catchpoint.
+@end table
+
+@subsubheading @value{GDBN} Command
+
+The corresponding @value{GDBN} command is @samp{catch handlers}.
+
+@subsubheading Example
+
+@smallexample
+-catch-handlers -e Constraint_Error
+^done,bkptno="4",bkpt=@{number="4",type="breakpoint",disp="keep",
+enabled="y",addr="0x0000000000402f68",
+what="`Constraint_Error' Ada exception handlers",thread-groups=["i1"],
+times="0",original-location="__gnat_begin_handler"@}
+(gdb)
+@end smallexample
+
@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@node GDB/MI Program Context
@section @sc{gdb/mi} Program Context
@var{bitsize}. The default is @code{int}.
@item group
-The register group to which this register belongs. It must
-be either @code{general}, @code{float}, or @code{vector}. If no
-@var{group} is specified, @value{GDBN} will not display the register
-in @code{info registers}.
+The register group to which this register belongs. It can be one of the
+standard register groups @code{general}, @code{float}, @code{vector} or an
+arbitrary string. Group names should be limited to alphanumeric characters.
+If a group name is made up of multiple words the words may be separated by
+hyphens; e.g.@: @code{special-group} or @code{ultra-special-group}. If no
+@var{group} is specified, @value{GDBN} will not display the register in
+@code{info registers}.
@end table
* gdbserver man:: Remote Server for the GNU Debugger man page
* gcore man:: Generate a core file of a running program
* gdbinit man:: gdbinit scripts
+* gdb-add-index man:: Add index files to speed up GDB
@end menu
@node gdb man
@end ifset
@c man end
+@node gdb-add-index man
+@heading gdb-add-index
+@pindex gdb-add-index
+@anchor{gdb-add-index}
+
+@c man title gdb-add-index Add index files to speed up GDB
+
+@c man begin SYNOPSIS gdb-add-index
+gdb-add-index @var{filename}
+@c man end
+
+@c man begin DESCRIPTION gdb-add-index
+When @value{GDBN} finds a symbol file, it scans the symbols in the
+file in order to construct an internal symbol table. This lets most
+@value{GDBN} operations work quickly--at the cost of a delay early on.
+For large programs, this delay can be quite lengthy, so @value{GDBN}
+provides a way to build an index, which speeds up startup.
+
+To determine whether a file contains such an index, use the command
+@kbd{readelf -S filename}: the index is stored in a section named
+@code{.gdb_index}. The index file can only be produced on systems
+which use ELF binaries and DWARF debug information (i.e., sections
+named @code{.debug_*}).
+
+@command{gdb-add-index} uses @value{GDBN} and @command{objdump} found
+in the @env{PATH} environment variable. If you want to use different
+versions of these programs, you can specify them through the
+@env{GDB} and @env{OBJDUMP} environment variables.
+
+See more in
+@ifset man
+the @value{GDBN} manual in node @code{Index Files}
+-- shell command @kbd{info -f gdb -n "Index Files"}.
+@end ifset
+@ifclear man
+@ref{Index Files}.
+@end ifclear
+@c man end
+
+@c man begin SEEALSO gdb-add-index
+@ifset man
+The full documentation for @value{GDBN} is maintained as a Texinfo manual.
+If the @code{info} and @code{gdb} programs and @value{GDBN}'s Texinfo
+documentation are properly installed at your site, the command
+
+@smallexample
+info gdb
+@end smallexample
+
+should give you access to the complete manual.
+
+@cite{Using GDB: A Guide to the GNU Source-Level Debugger},
+Richard M. Stallman and Roland H. Pesch, July 1991.
+@end ifset
+@c man end
+
@include gpl.texi
@node GNU Free Documentation License
projects / deliverable / binutils-gdb.git / blobdiff