diff options
Diffstat (limited to 'share/doc/gdb/Location-Specifications.html')
| -rw-r--r-- | share/doc/gdb/Location-Specifications.html | 188 |
1 files changed, 188 insertions, 0 deletions
diff --git a/share/doc/gdb/Location-Specifications.html b/share/doc/gdb/Location-Specifications.html new file mode 100644 index 0000000..9177ca4 --- /dev/null +++ b/share/doc/gdb/Location-Specifications.html @@ -0,0 +1,188 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- Copyright (C) 1988-2023 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." --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>Debugging with GDB: Location Specifications</title> + +<meta name="description" content="Debugging with GDB: Location Specifications"> +<meta name="keywords" content="Debugging with GDB: Location Specifications"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="index.html#Top" rel="start" title="Top"> +<link href="Concept-Index.html#Concept-Index" rel="index" title="Concept Index"> +<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="Source.html#Source" rel="up" title="Source"> +<link href="Linespec-Locations.html#Linespec-Locations" rel="next" title="Linespec Locations"> +<link href="List.html#List" rel="previous" title="List"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<a name="Location-Specifications"></a> +<div class="header"> +<p> +Next: <a href="Edit.html#Edit" accesskey="n" rel="next">Edit</a>, Previous: <a href="List.html#List" accesskey="p" rel="previous">List</a>, Up: <a href="Source.html#Source" accesskey="u" rel="up">Source</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p> +</div> +<hr> +<a name="Location-Specifications-1"></a> +<h3 class="section">9.2 Location Specifications</h3> +<a name="index-specifying-location"></a> +<a name="index-locspec"></a> +<a name="index-source-location"></a> +<a name="index-code-location"></a> + +<a name="index-location-spec"></a> +<p>Several <small>GDB</small> commands accept arguments that specify a location +or locations of your program’s code. Many times locations are +specified using a source line number, but they can also be specified +by a function name, an address, a label, etc. The different +forms of specifying a location that <small>GDB</small> recognizes are +collectively known as forms of <em>location specification</em>, or +<em>location spec</em>. This section documents the forms of specifying +locations that <small>GDB</small> recognizes. +</p> +<a name="index-location-resolution"></a> +<a name="index-resolution-of-location-spec"></a> +<p>When you specify a location, <small>GDB</small> needs to find the place in +your program, known as <em>code location</em>, that corresponds to the +given location spec. We call this process of finding actual code +locations corresponding to a location spec <em>location resolution</em>. +</p> +<p>A concrete code location in your program is uniquely identifiable by a +set of several attributes: its source line number, the name of its +source file, the fully-qualified and prototyped function in which it +is defined, and an instruction address. Because each inferior has its +own address space, the inferior number is also a necessary part of +these attributes. +</p> +<p>By contrast, location specs you type will many times omit some of +these attributes. For example, it is customary to specify just the +source line number to mean a line in the current source file, or +specify just the basename of the file, omitting its directories. In +other words, a location spec is usually incomplete, a kind of +blueprint, and <small>GDB</small> needs to complete the missing attributes +by using the implied defaults, and by considering the source code and +the debug information available to it. This is what location +resolution is about. +</p> +<p>The resolution of an incomplete location spec can produce more than a +single code location, if the spec doesn’t allow distinguishing between +them. Here are some examples of situations that result in a location +spec matching multiple code locations in your program: +</p> +<ul> +<li> The location spec specifies a function name, and there are several +functions in the program which have that name. (To distinguish +between them, you can specify a fully-qualified and prototyped +function name, such as <code>A::func(int)</code> instead of just +<code>func</code>.) + +</li><li> The location spec specifies a source file name, and there are several +source files in the program that share the same name, for example +several files with the same basename in different subdirectories. (To +distinguish between them, specify enough leading directories with the +file name.) + +</li><li> For a C<tt>++</tt> constructor, the <small>GCC</small> compiler generates several +instances of the function body, used in different cases, but their +source-level names are identical. + +</li><li> For a C<tt>++</tt> template function, a given line in the function can +correspond to any number of instantiations. + +</li><li> For an inlined function, a given source line can correspond to several +actual code locations with that function’s inlined code. +</li></ul> + +<p>Resolution of a location spec can also fail to produce a complete code +location, or even fail to produce any code location. Here are some +examples of such situations: +</p> +<ul> +<li> Some parts of the program lack detailed enough debug info, so the +resolved code location lacks some attributes, like source file name +and line number, leaving just the instruction address and perhaps also +a function name. Such an incomplete code location is only usable in +contexts that work with addresses and/or function names. Some +commands can only work with complete code locations. + +</li><li> The location spec specifies a function name, and there are no +functions in the program by that name, or they only exist in a +yet-unloaded shared library. + +</li><li> The location spec specifies a source file name, and there are no +source files in the program by that name, or they only exist in a +yet-unloaded shared library. + +</li><li> The location spec specifies both a source file name and a source line +number, and even though there are source files in the program that +match the file name, none of those files has the specified line +number. +</li></ul> + +<p>Locations may be specified using three different formats: linespec +locations, explicit locations, or address locations. The following +subsections describe these formats. +</p> +<table class="menu" border="0" cellspacing="0"> +<tr><td align="left" valign="top">• <a href="Linespec-Locations.html#Linespec-Locations" accesskey="1">Linespec Locations</a>:</td><td> </td><td align="left" valign="top">Linespec locations +</td></tr> +<tr><td align="left" valign="top">• <a href="Explicit-Locations.html#Explicit-Locations" accesskey="2">Explicit Locations</a>:</td><td> </td><td align="left" valign="top">Explicit locations +</td></tr> +<tr><td align="left" valign="top">• <a href="Address-Locations.html#Address-Locations" accesskey="3">Address Locations</a>:</td><td> </td><td align="left" valign="top">Address locations +</td></tr> +</table> + +<hr> +<div class="header"> +<p> +Next: <a href="Edit.html#Edit" accesskey="n" rel="next">Edit</a>, Previous: <a href="List.html#List" accesskey="p" rel="previous">List</a>, Up: <a href="Source.html#Source" accesskey="u" rel="up">Source</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p> +</div> + + + +</body> +</html> |