diff options
Diffstat (limited to 'share/doc/gdb/Files.html')
| -rw-r--r-- | share/doc/gdb/Files.html | 790 |
1 files changed, 790 insertions, 0 deletions
diff --git a/share/doc/gdb/Files.html b/share/doc/gdb/Files.html new file mode 100644 index 0000000..4e5810f --- /dev/null +++ b/share/doc/gdb/Files.html @@ -0,0 +1,790 @@ +<!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: Files</title> + +<meta name="description" content="Debugging with GDB: Files"> +<meta name="keywords" content="Debugging with GDB: Files"> +<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="GDB-Files.html#GDB-Files" rel="up" title="GDB Files"> +<link href="File-Caching.html#File-Caching" rel="next" title="File Caching"> +<link href="GDB-Files.html#GDB-Files" rel="previous" title="GDB Files"> +<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="Files"></a> +<div class="header"> +<p> +Next: <a href="File-Caching.html#File-Caching" accesskey="n" rel="next">File Caching</a>, Up: <a href="GDB-Files.html#GDB-Files" accesskey="u" rel="up">GDB Files</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="Commands-to-Specify-Files"></a> +<h3 class="section">18.1 Commands to Specify Files</h3> + +<a name="index-symbol-table"></a> +<a name="index-core-dump-file"></a> + +<p>You may want to specify executable and core dump file names. The usual +way to do this is at start-up time, using the arguments to +<small>GDB</small>’s start-up commands (see <a href="Invocation.html#Invocation">Getting In and +Out of <small>GDB</small></a>). +</p> +<p>Occasionally it is necessary to change to a different file during a +<small>GDB</small> session. Or you may run <small>GDB</small> and forget to +specify a file you want to use. Or you are debugging a remote target +via <code>gdbserver</code> (see <a href="Server.html#Server">Using the <code>gdbserver</code> +Program</a>). In these situations the <small>GDB</small> commands to specify +new files are useful. +</p> +<dl compact="compact"> +<dd><a name="index-executable-file"></a> +<a name="index-file"></a> +</dd> +<dt><code>file <var>filename</var></code></dt> +<dd><p>Use <var>filename</var> as the program to be debugged. It is read for its +symbols and for the contents of pure memory. It is also the program +executed when you use the <code>run</code> command. If you do not specify a +directory and the file is not found in the <small>GDB</small> working directory, +<small>GDB</small> uses the environment variable <code>PATH</code> as a list of +directories to search, just as the shell does when looking for a program +to run. You can change the value of this variable, for both <small>GDB</small> +and your program, using the <code>path</code> command. +</p> +<a name="index-unlinked-object-files"></a> +<a name="index-patching-object-files"></a> +<p>You can load unlinked object <samp>.o</samp> files into <small>GDB</small> using +the <code>file</code> command. You will not be able to “run” an object +file, but you can disassemble functions and inspect variables. Also, +if the underlying BFD functionality supports it, you could use +<kbd>gdb -write</kbd> to patch object files using this technique. Note +that <small>GDB</small> can neither interpret nor modify relocations in this +case, so branches and some initialized variables will appear to go to +the wrong place. But this feature is still handy from time to time. +</p> +</dd> +<dt><code>file</code></dt> +<dd><p><code>file</code> with no argument makes <small>GDB</small> discard any information it +has on both executable file and the symbol table. +</p> +<a name="index-exec_002dfile"></a> +</dd> +<dt><code>exec-file <span class="roman">[</span> <var>filename</var> <span class="roman">]</span></code></dt> +<dd><p>Specify that the program to be run (but not the symbol table) is found +in <var>filename</var>. <small>GDB</small> searches the environment variable <code>PATH</code> +if necessary to locate your program. Omitting <var>filename</var> means to +discard information on the executable file. +</p> +<a name="index-symbol_002dfile"></a> +</dd> +<dt><code>symbol-file <span class="roman">[</span> <var>filename</var> <span class="roman">[</span> -o <var>offset</var> <span class="roman">]]</span></code></dt> +<dd><p>Read symbol table information from file <var>filename</var>. <code>PATH</code> is +searched when necessary. Use the <code>file</code> command to get both symbol +table and program to run from the same file. +</p> +<p>If an optional <var>offset</var> is specified, it is added to the start +address of each section in the symbol file. This is useful if the +program is relocated at runtime, such as the Linux kernel with kASLR +enabled. +</p> +<p><code>symbol-file</code> with no argument clears out <small>GDB</small> information on your +program’s symbol table. +</p> +<p>The <code>symbol-file</code> command causes <small>GDB</small> to forget the contents of +some breakpoints and auto-display expressions. This is because they may +contain pointers to the internal data recording symbols and data types, +which are part of the old symbol table data being discarded inside +<small>GDB</small>. +</p> +<p><code>symbol-file</code> does not repeat if you press <tt class="key">RET</tt> again after +executing it once. +</p> +<p>When <small>GDB</small> is configured for a particular environment, it +understands debugging information in whatever format is the standard +generated for that environment; you may use either a <small>GNU</small> compiler, or +other compilers that adhere to the local conventions. +Best results are usually obtained from <small>GNU</small> compilers; for example, +using <code><small>GCC</small></code> you can generate debugging information for +optimized code. +</p> +<p>For most kinds of object files, with the exception of old SVR3 systems +using COFF, the <code>symbol-file</code> command does not normally read the +symbol table in full right away. Instead, it scans the symbol table +quickly to find which source files and which symbols are present. The +details are read later, one source file at a time, as they are needed. +</p> +<p>The purpose of this two-stage reading strategy is to make <small>GDB</small> +start up faster. For the most part, it is invisible except for +occasional pauses while the symbol table details for a particular source +file are being read. (The <code>set verbose</code> command can turn these +pauses into messages if desired. See <a href="Messages_002fWarnings.html#Messages_002fWarnings">Optional +Warnings and Messages</a>.) +</p> +<p>We have not implemented the two-stage strategy for COFF yet. When the +symbol table is stored in COFF format, <code>symbol-file</code> reads the +symbol table data in full right away. Note that “stabs-in-COFF” +still does the two-stage strategy, since the debug info is actually +in stabs format. +</p> +<a name="index-readnow"></a> +<a name="index-reading-symbols-immediately"></a> +<a name="index-symbols_002c-reading-immediately"></a> +</dd> +<dt><code>symbol-file <span class="roman">[</span> -readnow <span class="roman">]</span> <var>filename</var></code></dt> +<dt><code>file <span class="roman">[</span> -readnow <span class="roman">]</span> <var>filename</var></code></dt> +<dd><p>You can override the <small>GDB</small> two-stage strategy for reading symbol +tables by using the ‘<samp>-readnow</samp>’ option with any of the commands that +load symbol table information, if you want to be sure <small>GDB</small> has the +entire symbol table available. +</p> +<a name="index-_002dreadnever_002c-option-for-symbol_002dfile-command"></a> +<a name="index-never-read-symbols"></a> +<a name="index-symbols_002c-never-read"></a> +</dd> +<dt><code>symbol-file <span class="roman">[</span> -readnever <span class="roman">]</span> <var>filename</var></code></dt> +<dt><code>file <span class="roman">[</span> -readnever <span class="roman">]</span> <var>filename</var></code></dt> +<dd><p>You can instruct <small>GDB</small> to never read the symbolic information +contained in <var>filename</var> by using the ‘<samp>-readnever</samp>’ option. +See <a href="File-Options.html#g_t_002d_002dreadnever">--readnever</a>. +</p> + +<a name="index-core_002dfile"></a> +</dd> +<dt><code>core-file <span class="roman">[</span><var>filename</var><span class="roman">]</span></code></dt> +<dt><code>core</code></dt> +<dd><p>Specify the whereabouts of a core dump file to be used as the “contents +of memory”. Traditionally, core files contain only some parts of the +address space of the process that generated them; <small>GDB</small> can access the +executable file itself for other parts. +</p> +<p><code>core-file</code> with no argument specifies that no core file is +to be used. +</p> +<p>Note that the core file is ignored when your program is actually running +under <small>GDB</small>. So, if you have been running your program and you +wish to debug a core file instead, you must kill the subprocess in which +the program is running. To do this, use the <code>kill</code> command +(see <a href="Kill-Process.html#Kill-Process">Killing the Child Process</a>). +</p> +<a name="index-add_002dsymbol_002dfile"></a> +<a name="index-dynamic-linking"></a> +</dd> +<dt><code>add-symbol-file <var>filename</var> <span class="roman">[</span> -readnow <span class="roman">|</span> -readnever <span class="roman">]</span> <span class="roman">[</span> -o <var>offset</var> <span class="roman">]</span> <span class="roman">[</span> <var>textaddress</var> <span class="roman">]</span> <span class="roman">[</span> -s <var>section</var> <var>address</var> … <span class="roman">]</span></code></dt> +<dd><p>The <code>add-symbol-file</code> command reads additional symbol table +information from the file <var>filename</var>. You would use this command +when <var>filename</var> has been dynamically loaded (by some other means) +into the program that is running. The <var>textaddress</var> parameter gives +the memory address at which the file’s text section has been loaded. +You can additionally specify the base address of other sections using +an arbitrary number of ‘<samp>-s <var>section</var> <var>address</var></samp>’ pairs. +If a section is omitted, <small>GDB</small> will use its default addresses +as found in <var>filename</var>. Any <var>address</var> or <var>textaddress</var> +can be given as an expression. +</p> +<p>If an optional <var>offset</var> is specified, it is added to the start +address of each section, except those for which the address was +specified explicitly. +</p> +<p>The symbol table of the file <var>filename</var> is added to the symbol table +originally read with the <code>symbol-file</code> command. You can use the +<code>add-symbol-file</code> command any number of times; the new symbol data +thus read is kept in addition to the old. +</p> +<p>Changes can be reverted using the command <code>remove-symbol-file</code>. +</p> +<a name="index-relocatable-object-files_002c-reading-symbols-from"></a> +<a name="index-object-files_002c-relocatable_002c-reading-symbols-from"></a> +<a name="index-reading-symbols-from-relocatable-object-files"></a> +<a name="index-symbols_002c-reading-from-relocatable-object-files"></a> +<a name="index-_002eo-files_002c-reading-symbols-from"></a> +<p>Although <var>filename</var> is typically a shared library file, an +executable file, or some other object file which has been fully +relocated for loading into a process, you can also load symbolic +information from relocatable <samp>.o</samp> files, as long as: +</p> +<ul> +<li> the file’s symbolic information refers only to linker symbols defined in +that file, not to symbols defined by other object files, +</li><li> every section the file’s symbolic information refers to has actually +been loaded into the inferior, as it appears in the file, and +</li><li> you can determine the address at which every section was loaded, and +provide these to the <code>add-symbol-file</code> command. +</li></ul> + +<p>Some embedded operating systems, like Sun Chorus and VxWorks, can load +relocatable files into an already running program; such systems +typically make the requirements above easy to meet. However, it’s +important to recognize that many native systems use complex link +procedures (<code>.linkonce</code> section factoring and C<tt>++</tt> constructor table +assembly, for example) that make the requirements difficult to meet. In +general, one cannot assume that using <code>add-symbol-file</code> to read a +relocatable object file’s symbolic information will have the same effect +as linking the relocatable object file into the program in the normal +way. +</p> +<p><code>add-symbol-file</code> does not repeat if you press <tt class="key">RET</tt> after using it. +</p> +<a name="index-remove_002dsymbol_002dfile"></a> +</dd> +<dt><code>remove-symbol-file <var>filename</var></code></dt> +<dt><code>remove-symbol-file -a <var>address</var></code></dt> +<dd><p>Remove a symbol file added via the <code>add-symbol-file</code> command. The +file to remove can be identified by its <var>filename</var> or by an <var>address</var> +that lies within the boundaries of this symbol file in memory. Example: +</p> +<div class="smallexample"> +<pre class="smallexample">(gdb) add-symbol-file /home/user/gdb/mylib.so 0x7ffff7ff9480 +add symbol table from file "/home/user/gdb/mylib.so" at + .text_addr = 0x7ffff7ff9480 +(y or n) y +Reading symbols from /home/user/gdb/mylib.so... +(gdb) remove-symbol-file -a 0x7ffff7ff9480 +Remove symbol table from file "/home/user/gdb/mylib.so"? (y or n) y +(gdb) +</pre></div> + + +<p><code>remove-symbol-file</code> does not repeat if you press <tt class="key">RET</tt> after using it. +</p> +<a name="index-add_002dsymbol_002dfile_002dfrom_002dmemory"></a> +<a name="index-syscall-DSO"></a> +<a name="index-load-symbols-from-memory"></a> +</dd> +<dt><code>add-symbol-file-from-memory <var>address</var></code></dt> +<dd><p>Load symbols from the given <var>address</var> in a dynamically loaded +object file whose image is mapped directly into the inferior’s memory. +For example, the Linux kernel maps a <code>syscall DSO</code> into each +process’s address space; this DSO provides kernel-specific code for +some system calls. The argument can be any expression whose +evaluation yields the address of the file’s shared object file header. +For this command to work, you must have used <code>symbol-file</code> or +<code>exec-file</code> commands in advance. +</p> +<a name="index-section"></a> +</dd> +<dt><code>section <var>section</var> <var>addr</var></code></dt> +<dd><p>The <code>section</code> command changes the base address of the named +<var>section</var> of the exec file to <var>addr</var>. This can be used if the +exec file does not contain section addresses, (such as in the +<code>a.out</code> format), or when the addresses specified in the file +itself are wrong. Each section must be changed separately. The +<code>info files</code> command, described below, lists all the sections and +their addresses. +</p> +<a name="index-info-files"></a> +<a name="index-info-target"></a> +</dd> +<dt><code>info files</code></dt> +<dt><code>info target</code></dt> +<dd><p><code>info files</code> and <code>info target</code> are synonymous; both print the +current target (see <a href="Targets.html#Targets">Specifying a Debugging Target</a>), +including the names of the executable and core dump files currently in +use by <small>GDB</small>, and the files from which symbols were loaded. The +command <code>help target</code> lists all possible targets rather than +current ones. +</p> +<a name="index-maint-info-sections"></a> +</dd> +<dt><code>maint info sections <span class="roman">[</span>-all-objects<span class="roman">]</span> <span class="roman">[</span><var>filter-list</var><span class="roman">]</span></code></dt> +<dd><p>Another command that can give you extra information about program sections +is <code>maint info sections</code>. In addition to the section information +displayed by <code>info files</code>, this command displays the flags and file +offset of each section in the executable and core dump files. +</p> +<p>When ‘<samp>-all-objects</samp>’ is passed then sections from all loaded object +files, including shared libraries, are printed. +</p> +<p>The optional <var>filter-list</var> is a space separated list of filter +keywords. Sections that match any one of the filter criteria will be +printed. There are two types of filter: +</p> +<dl compact="compact"> +<dt><code><var>section-name</var></code></dt> +<dd><p>Display information about any section named <var>section-name</var>. +</p></dd> +<dt><code><var>section-flag</var></code></dt> +<dd><p>Display information for any section with <var>section-flag</var>. The +section flags that <small>GDB</small> currently knows about are: +</p><dl compact="compact"> +<dt><code>ALLOC</code></dt> +<dd><p>Section will have space allocated in the process when loaded. +Set for all sections except those containing debug information. +</p></dd> +<dt><code>LOAD</code></dt> +<dd><p>Section will be loaded from the file into the child process memory. +Set for pre-initialized code and data, clear for <code>.bss</code> sections. +</p></dd> +<dt><code>RELOC</code></dt> +<dd><p>Section needs to be relocated before loading. +</p></dd> +<dt><code>READONLY</code></dt> +<dd><p>Section cannot be modified by the child process. +</p></dd> +<dt><code>CODE</code></dt> +<dd><p>Section contains executable code only. +</p></dd> +<dt><code>DATA</code></dt> +<dd><p>Section contains data only (no executable code). +</p></dd> +<dt><code>ROM</code></dt> +<dd><p>Section will reside in ROM. +</p></dd> +<dt><code>CONSTRUCTOR</code></dt> +<dd><p>Section contains data for constructor/destructor lists. +</p></dd> +<dt><code>HAS_CONTENTS</code></dt> +<dd><p>Section is not empty. +</p></dd> +<dt><code>NEVER_LOAD</code></dt> +<dd><p>An instruction to the linker to not output the section. +</p></dd> +<dt><code>COFF_SHARED_LIBRARY</code></dt> +<dd><p>A notification to the linker that the section contains +COFF shared library information. +</p></dd> +<dt><code>IS_COMMON</code></dt> +<dd><p>Section contains common symbols. +</p></dd> +</dl> +</dd> +</dl> + +<a name="index-maint-info-target_002dsections"></a> +</dd> +<dt><code>maint info target-sections</code></dt> +<dd><p>This command prints <small>GDB</small>’s internal section table. For each +target <small>GDB</small> maintains a table containing the allocatable +sections from all currently mapped objects, along with information +about where the section is mapped. +</p> +<a name="index-set-trust_002dreadonly_002dsections"></a> +<a name="index-read_002donly-sections"></a> +</dd> +<dt><code>set trust-readonly-sections on</code></dt> +<dd><p>Tell <small>GDB</small> that readonly sections in your object file +really are read-only (i.e. that their contents will not change). +In that case, <small>GDB</small> can fetch values from these sections +out of the object file, rather than from the target program. +For some targets (notably embedded ones), this can be a significant +enhancement to debugging performance. +</p> +<p>The default is off. +</p> +</dd> +<dt><code>set trust-readonly-sections off</code></dt> +<dd><p>Tell <small>GDB</small> not to trust readonly sections. This means that +the contents of the section might change while the program is running, +and must therefore be fetched from the target when needed. +</p> +</dd> +<dt><code>show trust-readonly-sections</code></dt> +<dd><p>Show the current setting of trusting readonly sections. +</p></dd> +</dl> + +<p>All file-specifying commands allow both absolute and relative file names +as arguments. <small>GDB</small> always converts the file name to an absolute file +name and remembers it that way. +</p> +<a name="index-shared-libraries"></a> +<a name="Shared-Libraries"></a><p><small>GDB</small> supports <small>GNU</small>/Linux, MS-Windows, SunOS, +Darwin/Mach-O, SVr4, IBM RS/6000 AIX, QNX Neutrino, FDPIC (FR-V), and +DSBT (TIC6X) shared libraries. +</p> +<p>On MS-Windows <small>GDB</small> must be linked with the Expat library to support +shared libraries. See <a href="Requirements.html#Expat">Expat</a>. +</p> +<p><small>GDB</small> automatically loads symbol definitions from shared libraries +when you use the <code>run</code> command, or when you examine a core file. +(Before you issue the <code>run</code> command, <small>GDB</small> does not understand +references to a function in a shared library, however—unless you are +debugging a core file). +</p> + +<p>There are times, however, when you may wish to not automatically load +symbol definitions from shared libraries, such as when they are +particularly large or there are many of them. +</p> +<p>To control the automatic loading of shared library symbols, use the +commands: +</p> +<dl compact="compact"> +<dd><a name="index-set-auto_002dsolib_002dadd"></a> +</dd> +<dt><code>set auto-solib-add <var>mode</var></code></dt> +<dd><p>If <var>mode</var> is <code>on</code>, symbols from all shared object libraries +will be loaded automatically when the inferior begins execution, you +attach to an independently started inferior, or when the dynamic linker +informs <small>GDB</small> that a new library has been loaded. If <var>mode</var> +is <code>off</code>, symbols must be loaded manually, using the +<code>sharedlibrary</code> command. The default value is <code>on</code>. +</p> +<a name="index-memory-used-for-symbol-tables"></a> +<p>If your program uses lots of shared libraries with debug info that +takes large amounts of memory, you can decrease the <small>GDB</small> +memory footprint by preventing it from automatically loading the +symbols from shared libraries. To that end, type <kbd>set +auto-solib-add off</kbd> before running the inferior, then load each +library whose debug symbols you do need with <kbd>sharedlibrary +<var>regexp</var></kbd>, where <var>regexp</var> is a regular expression that matches +the libraries whose symbols you want to be loaded. +</p> +<a name="index-show-auto_002dsolib_002dadd"></a> +</dd> +<dt><code>show auto-solib-add</code></dt> +<dd><p>Display the current autoloading mode. +</p></dd> +</dl> + +<a name="index-load-shared-library"></a> +<p>To explicitly load shared library symbols, use the <code>sharedlibrary</code> +command: +</p> +<dl compact="compact"> +<dd><a name="index-info-sharedlibrary"></a> +<a name="index-info-share"></a> +</dd> +<dt><code>info share <var>regex</var></code></dt> +<dt><code>info sharedlibrary <var>regex</var></code></dt> +<dd><p>Print the names of the shared libraries which are currently loaded +that match <var>regex</var>. If <var>regex</var> is omitted then print +all shared libraries that are loaded. +</p> +<a name="index-info-dll"></a> +</dd> +<dt><code>info dll <var>regex</var></code></dt> +<dd><p>This is an alias of <code>info sharedlibrary</code>. +</p> +<a name="index-sharedlibrary"></a> +<a name="index-share"></a> +</dd> +<dt><code>sharedlibrary <var>regex</var></code></dt> +<dt><code>share <var>regex</var></code></dt> +<dd><p>Load shared object library symbols for files matching a +Unix regular expression. +As with files loaded automatically, it only loads shared libraries +required by your program for a core file or after typing <code>run</code>. If +<var>regex</var> is omitted all shared libraries required by your program are +loaded. +</p> +</dd> +<dt><code>nosharedlibrary</code></dt> +<dd><a name="index-nosharedlibrary"></a> +<a name="index-unload-symbols-from-shared-libraries"></a> +<p>Unload all shared object library symbols. This discards all symbols +that have been loaded from all shared libraries. Symbols from shared +libraries that were loaded by explicit user requests are not +discarded. +</p></dd> +</dl> + +<p>Sometimes you may wish that <small>GDB</small> stops and gives you control +when any of shared library events happen. The best way to do this is +to use <code>catch load</code> and <code>catch unload</code> (see <a href="Set-Catchpoints.html#Set-Catchpoints">Set Catchpoints</a>). +</p> +<p><small>GDB</small> also supports the <code>set stop-on-solib-events</code> +command for this. This command exists for historical reasons. It is +less useful than setting a catchpoint, because it does not allow for +conditions or commands as a catchpoint does. +</p> +<dl compact="compact"> +<dt><code>set stop-on-solib-events</code></dt> +<dd><a name="index-set-stop_002don_002dsolib_002devents"></a> +<p>This command controls whether <small>GDB</small> should give you control +when the dynamic linker notifies it about some shared library event. +The most common event of interest is loading or unloading of a new +shared library. +</p> +</dd> +<dt><code>show stop-on-solib-events</code></dt> +<dd><a name="index-show-stop_002don_002dsolib_002devents"></a> +<p>Show whether <small>GDB</small> stops and gives you control when shared +library events happen. +</p></dd> +</dl> + +<p>Shared libraries are also supported in many cross or remote debugging +configurations. <small>GDB</small> needs to have access to the target’s libraries; +this can be accomplished either by providing copies of the libraries +on the host system, or by asking <small>GDB</small> to automatically retrieve the +libraries from the target. If copies of the target libraries are +provided, they need to be the same as the target libraries, although the +copies on the target can be stripped as long as the copies on the host are +not. +</p> +<a name="index-where-to-look-for-shared-libraries"></a> +<p>For remote debugging, you need to tell <small>GDB</small> where the target +libraries are, so that it can load the correct copies—otherwise, it +may try to load the host’s libraries. <small>GDB</small> has two variables +to specify the search directories for target libraries. +</p> +<dl compact="compact"> +<dd><a name="index-prefix-for-executable-and-shared-library-file-names"></a> +<a name="index-system-root_002c-alternate"></a> +<a name="index-set-solib_002dabsolute_002dprefix"></a> +<a name="index-set-sysroot"></a> +</dd> +<dt><code>set sysroot <var>path</var></code></dt> +<dd><p>Use <var>path</var> as the system root for the program being debugged. Any +absolute shared library paths will be prefixed with <var>path</var>; many +runtime loaders store the absolute paths to the shared library in the +target program’s memory. When starting processes remotely, and when +attaching to already-running processes (local or remote), their +executable filenames will be prefixed with <var>path</var> if reported to +<small>GDB</small> as absolute by the operating system. If you use +<code>set sysroot</code> to find executables and shared libraries, they need +to be laid out in the same way that they are on the target, with +e.g. a <samp>/bin</samp>, <samp>/lib</samp> and <samp>/usr/lib</samp> hierarchy under +<var>path</var>. +</p> +<p>If <var>path</var> starts with the sequence <samp>target:</samp> and the target +system is remote then <small>GDB</small> will retrieve the target binaries +from the remote system. This is only supported when using a remote +target that supports the <code>remote get</code> command (see <a href="File-Transfer.html#File-Transfer">Sending files to a remote system</a>). The part of <var>path</var> +following the initial <samp>target:</samp> (if present) is used as system +root prefix on the remote file system. If <var>path</var> starts with the +sequence <samp>remote:</samp> this is converted to the sequence +<samp>target:</samp> by <code>set sysroot</code><a name="DOCF15" href="#FOOT15"><sup>15</sup></a>. If you want +to specify a local system root using a directory that happens to be +named <samp>target:</samp> or <samp>remote:</samp>, you need to use some +equivalent variant of the name like <samp>./target:</samp>. +</p> +<p>For targets with an MS-DOS based filesystem, such as MS-Windows, +<small>GDB</small> tries prefixing a few variants of the target +absolute file name with <var>path</var>. But first, on Unix hosts, +<small>GDB</small> converts all backslash directory separators into forward +slashes, because the backslash is not a directory separator on Unix: +</p> +<div class="smallexample"> +<pre class="smallexample"> c:\foo\bar.dll ⇒ c:/foo/bar.dll +</pre></div> + +<p>Then, <small>GDB</small> attempts prefixing the target file name with +<var>path</var>, and looks for the resulting file name in the host file +system: +</p> +<div class="smallexample"> +<pre class="smallexample"> c:/foo/bar.dll ⇒ /path/to/sysroot/c:/foo/bar.dll +</pre></div> + +<p>If that does not find the binary, <small>GDB</small> tries removing +the ‘<samp>:</samp>’ character from the drive spec, both for convenience, and, +for the case of the host file system not supporting file names with +colons: +</p> +<div class="smallexample"> +<pre class="smallexample"> c:/foo/bar.dll ⇒ /path/to/sysroot/c/foo/bar.dll +</pre></div> + +<p>This makes it possible to have a system root that mirrors a target +with more than one drive. E.g., you may want to setup your local +copies of the target system shared libraries like so (note ‘<samp>c</samp>’ vs +‘<samp>z</samp>’): +</p> +<div class="smallexample"> +<pre class="smallexample"> <samp>/path/to/sysroot/c/sys/bin/foo.dll</samp> + <samp>/path/to/sysroot/c/sys/bin/bar.dll</samp> + <samp>/path/to/sysroot/z/sys/bin/bar.dll</samp> +</pre></div> + +<p>and point the system root at <samp>/path/to/sysroot</samp>, so that +<small>GDB</small> can find the correct copies of both +<samp>c:\sys\bin\foo.dll</samp>, and <samp>z:\sys\bin\bar.dll</samp>. +</p> +<p>If that still does not find the binary, <small>GDB</small> tries +removing the whole drive spec from the target file name: +</p> +<div class="smallexample"> +<pre class="smallexample"> c:/foo/bar.dll ⇒ /path/to/sysroot/foo/bar.dll +</pre></div> + +<p>This last lookup makes it possible to not care about the drive name, +if you don’t want or need to. +</p> +<p>The <code>set solib-absolute-prefix</code> command is an alias for <code>set +sysroot</code>. +</p> +<a name="index-default-system-root"></a> +<a name="index-_002d_002dwith_002dsysroot"></a> +<p>You can set the default system root by using the configure-time +‘<samp>--with-sysroot</samp>’ option. If the system root is inside +<small>GDB</small>’s configured binary prefix (set with ‘<samp>--prefix</samp>’ or +‘<samp>--exec-prefix</samp>’), then the default system root will be updated +automatically if the installed <small>GDB</small> is moved to a new +location. +</p> +<a name="index-show-sysroot"></a> +</dd> +<dt><code>show sysroot</code></dt> +<dd><p>Display the current executable and shared library prefix. +</p> +<a name="index-set-solib_002dsearch_002dpath"></a> +</dd> +<dt><code>set solib-search-path <var>path</var></code></dt> +<dd><p>If this variable is set, <var>path</var> is a colon-separated list of +directories to search for shared libraries. ‘<samp>solib-search-path</samp>’ +is used after ‘<samp>sysroot</samp>’ fails to locate the library, or if the +path to the library is relative instead of absolute. If you want to +use ‘<samp>solib-search-path</samp>’ instead of ‘<samp>sysroot</samp>’, be sure to set +‘<samp>sysroot</samp>’ to a nonexistent directory to prevent <small>GDB</small> from +finding your host’s libraries. ‘<samp>sysroot</samp>’ is preferred; setting +it to a nonexistent directory may interfere with automatic loading +of shared library symbols. +</p> +<a name="index-show-solib_002dsearch_002dpath"></a> +</dd> +<dt><code>show solib-search-path</code></dt> +<dd><p>Display the current shared library search path. +</p> +<a name="index-DOS-file_002dname-semantics-of-file-names_002e"></a> +<a name="index-set-target_002dfile_002dsystem_002dkind-_0028unix_007cdos_002dbased_007cauto_0029"></a> +<a name="index-show-target_002dfile_002dsystem_002dkind"></a> +</dd> +<dt><code>set target-file-system-kind <var>kind</var></code></dt> +<dd><p>Set assumed file system kind for target reported file names. +</p> +<p>Shared library file names as reported by the target system may not +make sense as is on the system <small>GDB</small> is running on. For +example, when remote debugging a target that has MS-DOS based file +system semantics, from a Unix host, the target may be reporting to +<small>GDB</small> a list of loaded shared libraries with file names such as +<samp>c:\Windows\kernel32.dll</samp>. On Unix hosts, there’s no concept of +drive letters, so the ‘<samp>c:\</samp>’ prefix is not normally understood as +indicating an absolute file name, and neither is the backslash +normally considered a directory separator character. In that case, +the native file system would interpret this whole absolute file name +as a relative file name with no directory components. This would make +it impossible to point <small>GDB</small> at a copy of the remote target’s +shared libraries on the host using <code>set sysroot</code>, and impractical +with <code>set solib-search-path</code>. Setting +<code>target-file-system-kind</code> to <code>dos-based</code> tells <small>GDB</small> +to interpret such file names similarly to how the target would, and to +map them to file names valid on <small>GDB</small>’s native file system +semantics. The value of <var>kind</var> can be <code>"auto"</code>, in addition +to one of the supported file system kinds. In that case, <small>GDB</small> +tries to determine the appropriate file system variant based on the +current target’s operating system (see <a href="ABI.html#ABI">Configuring the +Current ABI</a>). The supported file system settings are: +</p> +<dl compact="compact"> +<dt><code>unix</code></dt> +<dd><p>Instruct <small>GDB</small> to assume the target file system is of Unix +kind. Only file names starting the forward slash (‘<samp>/</samp>’) character +are considered absolute, and the directory separator character is also +the forward slash. +</p> +</dd> +<dt><code>dos-based</code></dt> +<dd><p>Instruct <small>GDB</small> to assume the target file system is DOS based. +File names starting with either a forward slash, or a drive letter +followed by a colon (e.g., ‘<samp>c:</samp>’), are considered absolute, and +both the slash (‘<samp>/</samp>’) and the backslash (‘<samp>\\</samp>’) characters are +considered directory separators. +</p> +</dd> +<dt><code>auto</code></dt> +<dd><p>Instruct <small>GDB</small> to use the file system kind associated with the +target operating system (see <a href="ABI.html#ABI">Configuring the Current ABI</a>). +This is the default. +</p></dd> +</dl> +</dd> +</dl> + +<a name="index-file-name-canonicalization"></a> +<a name="index-base-name-differences"></a> +<p>When processing file names provided by the user, <small>GDB</small> +frequently needs to compare them to the file names recorded in the +program’s debug info. Normally, <small>GDB</small> compares just the +<em>base names</em> of the files as strings, which is reasonably fast +even for very large programs. (The base name of a file is the last +portion of its name, after stripping all the leading directories.) +This shortcut in comparison is based upon the assumption that files +cannot have more than one base name. This is usually true, but +references to files that use symlinks or similar filesystem +facilities violate that assumption. If your program records files +using such facilities, or if you provide file names to <small>GDB</small> +using symlinks etc., you can set <code>basenames-may-differ</code> to +<code>true</code> to instruct <small>GDB</small> to completely canonicalize each +pair of file names it needs to compare. This will make file-name +comparisons accurate, but at a price of a significant slowdown. +</p> +<dl compact="compact"> +<dt><code>set basenames-may-differ</code></dt> +<dd><a name="index-set-basenames_002dmay_002ddiffer"></a> +<p>Set whether a source file may have multiple base names. +</p> +</dd> +<dt><code>show basenames-may-differ</code></dt> +<dd><a name="index-show-basenames_002dmay_002ddiffer"></a> +<p>Show whether a source file may have multiple base names. +</p></dd> +</dl> + +<div class="footnote"> +<hr> +<h4 class="footnotes-heading">Footnotes</h4> + +<h3><a name="FOOT15" href="#DOCF15">(15)</a></h3> +<p>Historically the +functionality to retrieve binaries from the remote system was +provided by prefixing <var>path</var> with <samp>remote:</samp></p> +</div> +<hr> +<div class="header"> +<p> +Next: <a href="File-Caching.html#File-Caching" accesskey="n" rel="next">File Caching</a>, Up: <a href="GDB-Files.html#GDB-Files" accesskey="u" rel="up">GDB Files</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> |