| <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> |
| <html> |
| <!-- Copyright (C) 1988-2015 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.2, 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="Separate-Debug-Files.html#Separate-Debug-Files" rel="next" title="Separate Debug Files"> |
| <link href="GDB-Files.html#GDB-Files" rel="prev" 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="Separate-Debug-Files.html#Separate-Debug-Files" accesskey="n" rel="next">Separate Debug Files</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></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><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-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> <var>address</var></code></dt> |
| <dt><code>add-symbol-file <var>filename</var> <var>address</var> <span class="roman">[</span> -readnow <span class="roman">]</span></code></dt> |
| <dt><code>add-symbol-file <var>filename</var> <var>address</var> -s <var>section</var> <var>address</var> …</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>address</var> should give the memory |
| address at which the file has been loaded; <small>GDB</small> cannot figure |
| this out for itself. You can additionally specify an arbitrary number |
| of ‘<samp>-s <var>section</var> <var>address</var></samp>’ pairs, to give an explicit |
| section name and base address for that section. You can specify any |
| <var>address</var> as an expression. |
| </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...done. |
| (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</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. In addition, |
| <code>maint info sections</code> provides the following command options (which |
| may be arbitrarily combined): |
| </p> |
| <dl compact="compact"> |
| <dt><code>ALLOBJ</code></dt> |
| <dd><p>Display sections for all loaded object files, including shared libraries. |
| </p></dd> |
| <dt><code><var>sections</var></code></dt> |
| <dd><p>Display info only for named <var>sections</var>. |
| </p></dd> |
| <dt><code><var>section-flags</var></code></dt> |
| <dd><p>Display info only for sections for which <var>section-flags</var> are true. |
| 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-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, HP-UX, SunOS, SVr4, Irix, |
| and IBM RS/6000 AIX 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>On HP-UX, if the program loads a library explicitly, <small>GDB</small> |
| automatically loads the symbols at the time of the <code>shl_load</code> call. |
| </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 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="DOCF14" href="#FOOT14"><sup>14</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 and |
| SymbianOS, <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="FOOT14" href="#DOCF14">(14)</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="Separate-Debug-Files.html#Separate-Debug-Files" accesskey="n" rel="next">Separate Debug Files</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> |
