575 lines
38 KiB
HTML
575 lines
38 KiB
HTML
<html lang="en">
|
|
<head>
|
|
<title>Files - Debugging with GDB</title>
|
|
<meta http-equiv="Content-Type" content="text/html">
|
|
<meta name="description" content="Debugging with GDB">
|
|
<meta name="generator" content="makeinfo 4.13">
|
|
<link title="Top" rel="start" href="index.html#Top">
|
|
<link rel="up" href="GDB-Files.html#GDB-Files" title="GDB Files">
|
|
<link rel="next" href="File-Caching.html#File-Caching" title="File Caching">
|
|
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
|
|
<!--
|
|
Copyright (C) 1988-2019 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.''
|
|
-->
|
|
<meta http-equiv="Content-Style-Type" content="text/css">
|
|
<style type="text/css"><!--
|
|
pre.display { font-family:inherit }
|
|
pre.format { font-family:inherit }
|
|
pre.smalldisplay { font-family:inherit; font-size:smaller }
|
|
pre.smallformat { font-family:inherit; font-size:smaller }
|
|
pre.smallexample { font-size:smaller }
|
|
pre.smalllisp { font-size:smaller }
|
|
span.sc { font-variant:small-caps }
|
|
span.roman { font-family:serif; font-weight:normal; }
|
|
span.sansserif { font-family:sans-serif; font-weight:normal; }
|
|
--></style>
|
|
</head>
|
|
<body>
|
|
<div class="node">
|
|
<a name="Files"></a>
|
|
<p>
|
|
Next: <a rel="next" accesskey="n" href="File-Caching.html#File-Caching">File Caching</a>,
|
|
Up: <a rel="up" accesskey="u" href="GDB-Files.html#GDB-Files">GDB Files</a>
|
|
<hr>
|
|
</div>
|
|
|
|
<h3 class="section">18.1 Commands to Specify Files</h3>
|
|
|
|
<p><a name="index-symbol-table-1202"></a><a name="index-core-dump-file-1203"></a>
|
|
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
|
|
<span class="sc">gdb</span>'s start-up commands (see <a href="Invocation.html#Invocation">Getting In and Out of <span class="sc">gdb</span></a>).
|
|
|
|
<p>Occasionally it is necessary to change to a different file during a
|
|
<span class="sc">gdb</span> session. Or you may run <span class="sc">gdb</span> 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">file</a>). In these situations the <span class="sc">gdb</span> commands to specify
|
|
new files are useful.
|
|
|
|
|
|
<a name="index-executable-file-1204"></a>
|
|
<a name="index-file-1205"></a>
|
|
<dl><dt><code>file </code><var>filename</var><dd>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 <span class="sc">gdb</span> working directory,
|
|
<span class="sc">gdb</span> 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 <span class="sc">gdb</span>
|
|
and your program, using the <code>path</code> command.
|
|
|
|
<p><a name="index-unlinked-object-files-1206"></a><a name="index-patching-object-files-1207"></a>You can load unlinked object <samp><span class="file">.o</span></samp> files into <span class="sc">gdb</span> 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 <span class="sc">gdb</span> 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.
|
|
|
|
<br><dt><code>file</code><dd><code>file</code> with no argument makes <span class="sc">gdb</span> discard any information it
|
|
has on both executable file and the symbol table.
|
|
|
|
<p><a name="index-exec_002dfile-1208"></a><br><dt><code>exec-file </code><span class="roman">[</span> <var>filename</var> <span class="roman">]</span><dd>Specify that the program to be run (but not the symbol table) is found
|
|
in <var>filename</var>. <span class="sc">gdb</span> 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-1209"></a><br><dt><code>symbol-file </code><span class="roman">[</span> <var>filename</var> <span class="roman">[</span><code> -o </code><var>offset</var> <span class="roman">]]</span><dd>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>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><code>symbol-file</code> with no argument clears out <span class="sc">gdb</span> information on your
|
|
program's symbol table.
|
|
|
|
<p>The <code>symbol-file</code> command causes <span class="sc">gdb</span> 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
|
|
<span class="sc">gdb</span>.
|
|
|
|
<p><code>symbol-file</code> does not repeat if you press <RET> again after
|
|
executing it once.
|
|
|
|
<p>When <span class="sc">gdb</span> 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 <span class="sc">gnu</span> compiler, or
|
|
other compilers that adhere to the local conventions.
|
|
Best results are usually obtained from <span class="sc">gnu</span> compilers; for example,
|
|
using <span class="sc">gcc</span> you can generate debugging information for
|
|
optimized code.
|
|
|
|
<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>The purpose of this two-stage reading strategy is to make <span class="sc">gdb</span>
|
|
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>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-1210"></a><a name="index-reading-symbols-immediately-1211"></a><a name="index-symbols_002c-reading-immediately-1212"></a><br><dt><code>symbol-file </code><span class="roman">[</span><code> -readnow </code><span class="roman">]</span> <var>filename</var><dt><code>file </code><span class="roman">[</span><code> -readnow </code><span class="roman">]</span> <var>filename</var><dd>You can override the <span class="sc">gdb</span> two-stage strategy for reading symbol
|
|
tables by using the ‘<samp><span class="samp">-readnow</span></samp>’ option with any of the commands that
|
|
load symbol table information, if you want to be sure <span class="sc">gdb</span> has the
|
|
entire symbol table available.
|
|
|
|
<p><a name="index-g_t_0040code_007b_002dreadnever_007d_002c-option-for-symbol_002dfile-command-1213"></a><a name="index-never-read-symbols-1214"></a><a name="index-symbols_002c-never-read-1215"></a><br><dt><code>symbol-file </code><span class="roman">[</span><code> -readnever </code><span class="roman">]</span> <var>filename</var><dt><code>file </code><span class="roman">[</span><code> -readnever </code><span class="roman">]</span> <var>filename</var><dd>You can instruct <span class="sc">gdb</span> to never read the symbolic information
|
|
contained in <var>filename</var> by using the ‘<samp><span class="samp">-readnever</span></samp>’ option.
|
|
See <a href="_002d_002dreadnever.html#g_t_002d_002dreadnever">–readnever</a>.
|
|
|
|
<!-- FIXME: for now no mention of directories, since this seems to be in -->
|
|
<!-- flux. 13mar1992 status is that in theory GDB would look either in -->
|
|
<!-- current dir or in same dir as myprog; but issues like competing -->
|
|
<!-- GDB's, or clutter in system dirs, mean that in practice right now -->
|
|
<!-- only current dir is used. FFish says maybe a special GDB hierarchy -->
|
|
<!-- (eg rooted in val of env var GDBSYMS) could exist for mappable symbol -->
|
|
<!-- files. -->
|
|
<p><a name="index-core_002dfile-1216"></a><br><dt><code>core-file </code><span class="roman">[</span><var>filename</var><span class="roman">]</span><dt><code>core</code><dd>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; <span class="sc">gdb</span> can access the
|
|
executable file itself for other parts.
|
|
|
|
<p><code>core-file</code> with no argument specifies that no core file is
|
|
to be used.
|
|
|
|
<p>Note that the core file is ignored when your program is actually running
|
|
under <span class="sc">gdb</span>. 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-1217"></a><a name="index-dynamic-linking-1218"></a><br><dt><code>add-symbol-file </code><var>filename</var> <span class="roman">[</span><code> -readnow </code><span class="roman">|</span><code> -readnever </code><span class="roman">]</span> <span class="roman">[</span><code> -o </code><var>offset</var> <span class="roman">]</span> <span class="roman">[</span> <var>textaddress</var> <span class="roman">]</span> <span class="roman">[</span><code> -s </code><var>section</var> <var>address</var><code> ... </code><span class="roman">]</span><dd>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><span class="samp">-s </span><var>section</var> <var>address</var></samp>’ pairs.
|
|
If a section is omitted, <span class="sc">gdb</span> 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>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>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>Changes can be reverted using the command <code>remove-symbol-file</code>.
|
|
|
|
<p><a name="index-relocatable-object-files_002c-reading-symbols-from-1219"></a><a name="index-object-files_002c-relocatable_002c-reading-symbols-from-1220"></a><a name="index-reading-symbols-from-relocatable-object-files-1221"></a><a name="index-symbols_002c-reading-from-relocatable-object-files-1222"></a><a name="index-g_t_0040file_007b_002eo_007d-files_002c-reading-symbols-from-1223"></a>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><span class="file">.o</span></samp> files, as long as:
|
|
|
|
<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>every section the file's symbolic information refers to has actually
|
|
been loaded into the inferior, as it appears in the file, and
|
|
<li>you can determine the address at which every section was loaded, and
|
|
provide these to the <code>add-symbol-file</code> command.
|
|
</ul>
|
|
|
|
<p class="noindent">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><code>add-symbol-file</code> does not repeat if you press <RET> after using it.
|
|
|
|
<p><a name="index-remove_002dsymbol_002dfile-1224"></a><br><dt><code>remove-symbol-file </code><var>filename</var><br><dt><code>remove-symbol-file -a </code><var>address</var><dd>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:
|
|
|
|
<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...done.
|
|
(gdb) remove-symbol-file -a 0x7ffff7ff9480
|
|
Remove symbol table from file "/home/user/gdb/mylib.so"? (y or n) y
|
|
(gdb)
|
|
</pre>
|
|
<p><code>remove-symbol-file</code> does not repeat if you press <RET> after using it.
|
|
|
|
<p><a name="index-add_002dsymbol_002dfile_002dfrom_002dmemory-1225"></a><a name="index-g_t_0040code_007bsyscall-DSO_007d-1226"></a><a name="index-load-symbols-from-memory-1227"></a><br><dt><code>add-symbol-file-from-memory </code><var>address</var><dd>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-1228"></a><br><dt><code>section </code><var>section</var> <var>addr</var><dd>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-1229"></a><a name="index-info-target-1230"></a><br><dt><code>info files</code><dt><code>info target</code><dd><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 <span class="sc">gdb</span>, 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-1231"></a><br><dt><code>maint info sections</code><dd>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. In addition,
|
|
<code>maint info sections</code> provides the following command options (which
|
|
may be arbitrarily combined):
|
|
|
|
<dl>
|
|
<dt><code>ALLOBJ</code><dd>Display sections for all loaded object files, including shared libraries.
|
|
<br><dt><var>sections</var><dd>Display info only for named <var>sections</var>.
|
|
<br><dt><var>section-flags</var><dd>Display info only for sections for which <var>section-flags</var> are true.
|
|
The section flags that <span class="sc">gdb</span> currently knows about are:
|
|
<dl>
|
|
<dt><code>ALLOC</code><dd>Section will have space allocated in the process when loaded.
|
|
Set for all sections except those containing debug information.
|
|
<br><dt><code>LOAD</code><dd>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.
|
|
<br><dt><code>RELOC</code><dd>Section needs to be relocated before loading.
|
|
<br><dt><code>READONLY</code><dd>Section cannot be modified by the child process.
|
|
<br><dt><code>CODE</code><dd>Section contains executable code only.
|
|
<br><dt><code>DATA</code><dd>Section contains data only (no executable code).
|
|
<br><dt><code>ROM</code><dd>Section will reside in ROM.
|
|
<br><dt><code>CONSTRUCTOR</code><dd>Section contains data for constructor/destructor lists.
|
|
<br><dt><code>HAS_CONTENTS</code><dd>Section is not empty.
|
|
<br><dt><code>NEVER_LOAD</code><dd>An instruction to the linker to not output the section.
|
|
<br><dt><code>COFF_SHARED_LIBRARY</code><dd>A notification to the linker that the section contains
|
|
COFF shared library information.
|
|
<br><dt><code>IS_COMMON</code><dd>Section contains common symbols.
|
|
</dl>
|
|
</dl>
|
|
<a name="index-set-trust_002dreadonly_002dsections-1232"></a><a name="index-read_002donly-sections-1233"></a><br><dt><code>set trust-readonly-sections on</code><dd>Tell <span class="sc">gdb</span> that readonly sections in your object file
|
|
really are read-only (i.e. that their contents will not change).
|
|
In that case, <span class="sc">gdb</span> 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>The default is off.
|
|
|
|
<br><dt><code>set trust-readonly-sections off</code><dd>Tell <span class="sc">gdb</span> 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.
|
|
|
|
<br><dt><code>show trust-readonly-sections</code><dd>Show the current setting of trusting readonly sections.
|
|
</dl>
|
|
|
|
<p>All file-specifying commands allow both absolute and relative file names
|
|
as arguments. <span class="sc">gdb</span> always converts the file name to an absolute file
|
|
name and remembers it that way.
|
|
|
|
<p><a name="index-shared-libraries-1234"></a><a name="Shared-Libraries"></a><span class="sc">gdb</span> supports <span class="sc">gnu</span>/Linux, MS-Windows, SunOS,
|
|
Darwin/Mach-O, SVr4, IBM RS/6000 AIX, QNX Neutrino, FDPIC (FR-V), and
|
|
DSBT (TIC6X) shared libraries.
|
|
|
|
<p>On MS-Windows <span class="sc">gdb</span> must be linked with the Expat library to support
|
|
shared libraries. See <a href="Expat.html#Expat">Expat</a>.
|
|
|
|
<p><span class="sc">gdb</span> 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, <span class="sc">gdb</span> does not understand
|
|
references to a function in a shared library, however—unless you are
|
|
debugging a core file).
|
|
|
|
<!-- FIXME: some @value{GDBN} release may permit some refs to undef -->
|
|
<!-- FIXME...symbols-eg in a break cmd-assuming they are from a shared -->
|
|
<!-- FIXME...lib; check this from time to time when updating manual -->
|
|
<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>To control the automatic loading of shared library symbols, use the
|
|
commands:
|
|
|
|
|
|
<a name="index-set-auto_002dsolib_002dadd-1235"></a>
|
|
<dl><dt><code>set auto-solib-add </code><var>mode</var><dd>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 <span class="sc">gdb</span> 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-1236"></a>If your program uses lots of shared libraries with debug info that
|
|
takes large amounts of memory, you can decrease the <span class="sc">gdb</span>
|
|
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
|
|
</kbd><var>regexp</var>, 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-1237"></a><br><dt><code>show auto-solib-add</code><dd>Display the current autoloading mode.
|
|
</dl>
|
|
|
|
<p><a name="index-load-shared-library-1238"></a>To explicitly load shared library symbols, use the <code>sharedlibrary</code>
|
|
command:
|
|
|
|
|
|
<a name="index-info-sharedlibrary-1239"></a>
|
|
<a name="index-info-share-1240"></a>
|
|
<dl><dt><code>info share </code><var>regex</var><dt><code>info sharedlibrary </code><var>regex</var><dd>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-1241"></a><br><dt><code>info dll </code><var>regex</var><dd>This is an alias of <code>info sharedlibrary</code>.
|
|
|
|
<p><a name="index-sharedlibrary-1242"></a><a name="index-share-1243"></a><br><dt><code>sharedlibrary </code><var>regex</var><dt><code>share </code><var>regex</var><dd>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.
|
|
|
|
<br><dt><code>nosharedlibrary</code><dd><a name="index-nosharedlibrary-1244"></a><a name="index-unload-symbols-from-shared-libraries-1245"></a>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.
|
|
</dl>
|
|
|
|
<p>Sometimes you may wish that <span class="sc">gdb</span> 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><span class="sc">gdb</span> also supports the 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.
|
|
|
|
<dl>
|
|
<dt><code>set stop-on-solib-events</code><dd><a name="index-set-stop_002don_002dsolib_002devents-1246"></a>This command controls whether <span class="sc">gdb</span> 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.
|
|
|
|
<br><dt><code>show stop-on-solib-events</code><dd><a name="index-show-stop_002don_002dsolib_002devents-1247"></a>Show whether <span class="sc">gdb</span> stops and gives you control when shared
|
|
library events happen.
|
|
</dl>
|
|
|
|
<p>Shared libraries are also supported in many cross or remote debugging
|
|
configurations. <span class="sc">gdb</span> 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 <span class="sc">gdb</span> 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-1248"></a>For remote debugging, you need to tell <span class="sc">gdb</span> where the target
|
|
libraries are, so that it can load the correct copies—otherwise, it
|
|
may try to load the host's libraries. <span class="sc">gdb</span> has two variables
|
|
to specify the search directories for target libraries.
|
|
|
|
|
|
<a name="index-prefix-for-executable-and-shared-library-file-names-1249"></a>
|
|
<a name="index-system-root_002c-alternate-1250"></a>
|
|
<a name="index-set-solib_002dabsolute_002dprefix-1251"></a>
|
|
<a name="index-set-sysroot-1252"></a>
|
|
<dl><dt><code>set sysroot </code><var>path</var><dd>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
|
|
<span class="sc">gdb</span> 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><span class="file">/bin</span></samp>, <samp><span class="file">/lib</span></samp> and <samp><span class="file">/usr/lib</span></samp> hierarchy under
|
|
<var>path</var>.
|
|
|
|
<p>If <var>path</var> starts with the sequence <samp><span class="file">target:</span></samp> and the target
|
|
system is remote then <span class="sc">gdb</span> 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><span class="file">target:</span></samp> (if present) is used as system
|
|
root prefix on the remote file system. If <var>path</var> starts with the
|
|
sequence <samp><span class="file">remote:</span></samp> this is converted to the sequence
|
|
<samp><span class="file">target:</span></samp> by <code>set sysroot</code><a rel="footnote" href="#fn-1" name="fnd-1"><sup>1</sup></a>. If you want
|
|
to specify a local system root using a directory that happens to be
|
|
named <samp><span class="file">target:</span></samp> or <samp><span class="file">remote:</span></samp>, you need to use some
|
|
equivalent variant of the name like <samp><span class="file">./target:</span></samp>.
|
|
|
|
<p>For targets with an MS-DOS based filesystem, such as MS-Windows and
|
|
SymbianOS, <span class="sc">gdb</span> tries prefixing a few variants of the target
|
|
absolute file name with <var>path</var>. But first, on Unix hosts,
|
|
<span class="sc">gdb</span> converts all backslash directory separators into forward
|
|
slashes, because the backslash is not a directory separator on Unix:
|
|
|
|
<pre class="smallexample"> c:\foo\bar.dll ⇒ c:/foo/bar.dll
|
|
</pre>
|
|
<p>Then, <span class="sc">gdb</span> attempts prefixing the target file name with
|
|
<var>path</var>, and looks for the resulting file name in the host file
|
|
system:
|
|
|
|
<pre class="smallexample"> c:/foo/bar.dll ⇒ /path/to/sysroot/c:/foo/bar.dll
|
|
</pre>
|
|
<p>If that does not find the binary, <span class="sc">gdb</span> tries removing
|
|
the ‘<samp><span class="samp">:</span></samp>’ character from the drive spec, both for convenience, and,
|
|
for the case of the host file system not supporting file names with
|
|
colons:
|
|
|
|
<pre class="smallexample"> c:/foo/bar.dll ⇒ /path/to/sysroot/c/foo/bar.dll
|
|
</pre>
|
|
<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><span class="samp">c</span></samp>’ vs
|
|
‘<samp><span class="samp">z</span></samp>’):
|
|
|
|
<pre class="smallexample"> <samp><span class="file">/path/to/sysroot/c/sys/bin/foo.dll</span></samp>
|
|
<samp><span class="file">/path/to/sysroot/c/sys/bin/bar.dll</span></samp>
|
|
<samp><span class="file">/path/to/sysroot/z/sys/bin/bar.dll</span></samp>
|
|
</pre>
|
|
<p class="noindent">and point the system root at <samp><span class="file">/path/to/sysroot</span></samp>, so that
|
|
<span class="sc">gdb</span> can find the correct copies of both
|
|
<samp><span class="file">c:\sys\bin\foo.dll</span></samp>, and <samp><span class="file">z:\sys\bin\bar.dll</span></samp>.
|
|
|
|
<p>If that still does not find the binary, <span class="sc">gdb</span> tries
|
|
removing the whole drive spec from the target file name:
|
|
|
|
<pre class="smallexample"> c:/foo/bar.dll ⇒ /path/to/sysroot/foo/bar.dll
|
|
</pre>
|
|
<p>This last lookup makes it possible to not care about the drive name,
|
|
if you don't want or need to.
|
|
|
|
<p>The <code>set solib-absolute-prefix</code> command is an alias for <code>set
|
|
sysroot</code>.
|
|
|
|
<p><a name="index-default-system-root-1253"></a><a name="index-g_t_0040samp_007b_002d_002dwith_002dsysroot_007d-1254"></a>You can set the default system root by using the configure-time
|
|
‘<samp><span class="samp">--with-sysroot</span></samp>’ option. If the system root is inside
|
|
<span class="sc">gdb</span>'s configured binary prefix (set with ‘<samp><span class="samp">--prefix</span></samp>’ or
|
|
‘<samp><span class="samp">--exec-prefix</span></samp>’), then the default system root will be updated
|
|
automatically if the installed <span class="sc">gdb</span> is moved to a new
|
|
location.
|
|
|
|
<p><a name="index-show-sysroot-1255"></a><br><dt><code>show sysroot</code><dd>Display the current executable and shared library prefix.
|
|
|
|
<p><a name="index-set-solib_002dsearch_002dpath-1256"></a><br><dt><code>set solib-search-path </code><var>path</var><dd>If this variable is set, <var>path</var> is a colon-separated list of
|
|
directories to search for shared libraries. ‘<samp><span class="samp">solib-search-path</span></samp>’
|
|
is used after ‘<samp><span class="samp">sysroot</span></samp>’ fails to locate the library, or if the
|
|
path to the library is relative instead of absolute. If you want to
|
|
use ‘<samp><span class="samp">solib-search-path</span></samp>’ instead of ‘<samp><span class="samp">sysroot</span></samp>’, be sure to set
|
|
‘<samp><span class="samp">sysroot</span></samp>’ to a nonexistent directory to prevent <span class="sc">gdb</span> from
|
|
finding your host's libraries. ‘<samp><span class="samp">sysroot</span></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-1257"></a><br><dt><code>show solib-search-path</code><dd>Display the current shared library search path.
|
|
|
|
<p><a name="index-DOS-file_002dname-semantics-of-file-names_002e-1258"></a><a name="index-set-target_002dfile_002dsystem_002dkind-_0028unix_007cdos_002dbased_007cauto_0029-1259"></a><a name="index-show-target_002dfile_002dsystem_002dkind-1260"></a><br><dt><code>set target-file-system-kind </code><var>kind</var><dd>Set assumed file system kind for target reported file names.
|
|
|
|
<p>Shared library file names as reported by the target system may not
|
|
make sense as is on the system <span class="sc">gdb</span> 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
|
|
<span class="sc">gdb</span> a list of loaded shared libraries with file names such as
|
|
<samp><span class="file">c:\Windows\kernel32.dll</span></samp>. On Unix hosts, there's no concept of
|
|
drive letters, so the ‘<samp><span class="samp">c:\</span></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 <span class="sc">gdb</span> 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 <span class="sc">gdb</span>
|
|
to interpret such file names similarly to how the target would, and to
|
|
map them to file names valid on <span class="sc">gdb</span>'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, <span class="sc">gdb</span>
|
|
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:
|
|
|
|
<dl>
|
|
<dt><code>unix</code><dd>Instruct <span class="sc">gdb</span> to assume the target file system is of Unix
|
|
kind. Only file names starting the forward slash (‘<samp><span class="samp">/</span></samp>’) character
|
|
are considered absolute, and the directory separator character is also
|
|
the forward slash.
|
|
|
|
<br><dt><code>dos-based</code><dd>Instruct <span class="sc">gdb</span> 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><span class="samp">c:</span></samp>’), are considered absolute, and
|
|
both the slash (‘<samp><span class="samp">/</span></samp>’) and the backslash (‘<samp><span class="samp">\\</span></samp>’) characters are
|
|
considered directory separators.
|
|
|
|
<br><dt><code>auto</code><dd>Instruct <span class="sc">gdb</span> 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.
|
|
</dl>
|
|
</dl>
|
|
|
|
<p><a name="index-file-name-canonicalization-1261"></a><a name="index-base-name-differences-1262"></a>When processing file names provided by the user, <span class="sc">gdb</span>
|
|
frequently needs to compare them to the file names recorded in the
|
|
program's debug info. Normally, <span class="sc">gdb</span> compares just the
|
|
<dfn>base names</dfn> 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 <span class="sc">gdb</span>
|
|
using symlinks etc., you can set <code>basenames-may-differ</code> to
|
|
<code>true</code> to instruct <span class="sc">gdb</span> 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.
|
|
|
|
<dl>
|
|
<dt><code>set basenames-may-differ</code><dd><a name="index-set-basenames_002dmay_002ddiffer-1263"></a>Set whether a source file may have multiple base names.
|
|
|
|
<br><dt><code>show basenames-may-differ</code><dd><a name="index-show-basenames_002dmay_002ddiffer-1264"></a>Show whether a source file may have multiple base names.
|
|
</dl>
|
|
|
|
<div class="footnote">
|
|
<hr>
|
|
<h4>Footnotes</h4><p class="footnote"><small>[<a name="fn-1" href="#fnd-1">1</a>]</small> Historically the
|
|
functionality to retrieve binaries from the remote system was
|
|
provided by prefixing <var>path</var> with <samp><span class="file">remote:</span></samp></p>
|
|
|
|
<hr></div>
|
|
|
|
</body></html>
|
|
|