1<html lang="en"> 2<head> 3<title>Files - Debugging with GDB</title> 4<meta http-equiv="Content-Type" content="text/html"> 5<meta name="description" content="Debugging with GDB"> 6<meta name="generator" content="makeinfo 4.13"> 7<link title="Top" rel="start" href="index.html#Top"> 8<link rel="up" href="GDB-Files.html#GDB-Files" title="GDB Files"> 9<link rel="next" href="Separate-Debug-Files.html#Separate-Debug-Files" title="Separate Debug Files"> 10<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> 11<!-- 12Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 131998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 14Free Software Foundation, Inc. 15 16Permission is granted to copy, distribute and/or modify this document 17under the terms of the GNU Free Documentation License, Version 1.3 or 18any later version published by the Free Software Foundation; with the 19Invariant Sections being ``Free Software'' and ``Free Software Needs 20Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,'' 21and with the Back-Cover Texts as in (a) below. 22 23(a) The FSF's Back-Cover Text is: ``You are free to copy and modify 24this GNU Manual. Buying copies from GNU Press supports the FSF in 25developing GNU and promoting software freedom.''--> 26<meta http-equiv="Content-Style-Type" content="text/css"> 27<style type="text/css"><!-- 28 pre.display { font-family:inherit } 29 pre.format { font-family:inherit } 30 pre.smalldisplay { font-family:inherit; font-size:smaller } 31 pre.smallformat { font-family:inherit; font-size:smaller } 32 pre.smallexample { font-size:smaller } 33 pre.smalllisp { font-size:smaller } 34 span.sc { font-variant:small-caps } 35 span.roman { font-family:serif; font-weight:normal; } 36 span.sansserif { font-family:sans-serif; font-weight:normal; } 37--></style> 38<link rel="stylesheet" type="text/css" href="../cs.css"> 39</head> 40<body> 41<div class="node"> 42<a name="Files"></a> 43<p> 44Next: <a rel="next" accesskey="n" href="Separate-Debug-Files.html#Separate-Debug-Files">Separate Debug Files</a>, 45Up: <a rel="up" accesskey="u" href="GDB-Files.html#GDB-Files">GDB Files</a> 46<hr> 47</div> 48 49<h3 class="section">18.1 Commands to Specify Files</h3> 50 51<p><a name="index-symbol-table-950"></a><a name="index-core-dump-file-951"></a> 52You may want to specify executable and core dump file names. The usual 53way to do this is at start-up time, using the arguments to 54<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>). 55 56 <p>Occasionally it is necessary to change to a different file during a 57<span class="sc">gdb</span> session. Or you may run <span class="sc">gdb</span> and forget to 58specify a file you want to use. Or you are debugging a remote target 59via <code>gdbserver</code> (see <a href="Server.html#Server">file</a>). In these situations the <span class="sc">gdb</span> commands to specify 60new files are useful. 61 62 63<a name="index-executable-file-952"></a> 64<a name="index-file-953"></a> 65<dl><dt><code>file </code><var>filename</var><dd>Use <var>filename</var> as the program to be debugged. It is read for its 66symbols and for the contents of pure memory. It is also the program 67executed when you use the <code>run</code> command. If you do not specify a 68directory and the file is not found in the <span class="sc">gdb</span> working directory, 69<span class="sc">gdb</span> uses the environment variable <code>PATH</code> as a list of 70directories to search, just as the shell does when looking for a program 71to run. You can change the value of this variable, for both <span class="sc">gdb</span> 72and your program, using the <code>path</code> command. 73 74 <p><a name="index-unlinked-object-files-954"></a><a name="index-patching-object-files-955"></a>You can load unlinked object <samp><span class="file">.o</span></samp> files into <span class="sc">gdb</span> using 75the <code>file</code> command. You will not be able to “run” an object 76file, but you can disassemble functions and inspect variables. Also, 77if the underlying BFD functionality supports it, you could use 78<kbd>gdb -write</kbd> to patch object files using this technique. Note 79that <span class="sc">gdb</span> can neither interpret nor modify relocations in this 80case, so branches and some initialized variables will appear to go to 81the wrong place. But this feature is still handy from time to time. 82 83 <br><dt><code>file</code><dd><code>file</code> with no argument makes <span class="sc">gdb</span> discard any information it 84has on both executable file and the symbol table. 85 86 <p><a name="index-exec_002dfile-956"></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 87in <var>filename</var>. <span class="sc">gdb</span> searches the environment variable <code>PATH</code> 88if necessary to locate your program. Omitting <var>filename</var> means to 89discard information on the executable file. 90 91 <p><a name="index-symbol_002dfile-957"></a><br><dt><code>symbol-file </code><span class="roman">[</span> <var>filename</var> <span class="roman">]</span><dd>Read symbol table information from file <var>filename</var>. <code>PATH</code> is 92searched when necessary. Use the <code>file</code> command to get both symbol 93table and program to run from the same file. 94 95 <p><code>symbol-file</code> with no argument clears out <span class="sc">gdb</span> information on your 96program's symbol table. 97 98 <p>The <code>symbol-file</code> command causes <span class="sc">gdb</span> to forget the contents of 99some breakpoints and auto-display expressions. This is because they may 100contain pointers to the internal data recording symbols and data types, 101which are part of the old symbol table data being discarded inside 102<span class="sc">gdb</span>. 103 104 <p><code>symbol-file</code> does not repeat if you press <RET> again after 105executing it once. 106 107 <p>When <span class="sc">gdb</span> is configured for a particular environment, it 108understands debugging information in whatever format is the standard 109generated for that environment; you may use either a <span class="sc">gnu</span> compiler, or 110other compilers that adhere to the local conventions. 111Best results are usually obtained from <span class="sc">gnu</span> compilers; for example, 112using <span class="sc">gcc</span> you can generate debugging information for 113optimized code. 114 115 <p>For most kinds of object files, with the exception of old SVR3 systems 116using COFF, the <code>symbol-file</code> command does not normally read the 117symbol table in full right away. Instead, it scans the symbol table 118quickly to find which source files and which symbols are present. The 119details are read later, one source file at a time, as they are needed. 120 121 <p>The purpose of this two-stage reading strategy is to make <span class="sc">gdb</span> 122start up faster. For the most part, it is invisible except for 123occasional pauses while the symbol table details for a particular source 124file are being read. (The <code>set verbose</code> command can turn these 125pauses into messages if desired. See <a href="Messages_002fWarnings.html#Messages_002fWarnings">Optional Warnings and Messages</a>.) 126 127 <p>We have not implemented the two-stage strategy for COFF yet. When the 128symbol table is stored in COFF format, <code>symbol-file</code> reads the 129symbol table data in full right away. Note that “stabs-in-COFF” 130still does the two-stage strategy, since the debug info is actually 131in stabs format. 132 133 <p><a name="index-readnow-958"></a><a name="index-reading-symbols-immediately-959"></a><a name="index-symbols_002c-reading-immediately-960"></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 134tables by using the ‘<samp><span class="samp">-readnow</span></samp>’ option with any of the commands that 135load symbol table information, if you want to be sure <span class="sc">gdb</span> has the 136entire symbol table available. 137 138 <!-- FIXME: for now no mention of directories, since this seems to be in --> 139 <!-- flux. 13mar1992 status is that in theory GDB would look either in --> 140 <!-- current dir or in same dir as myprog; but issues like competing --> 141 <!-- GDB's, or clutter in system dirs, mean that in practice right now --> 142 <!-- only current dir is used. FFish says maybe a special GDB hierarchy --> 143 <!-- (eg rooted in val of env var GDBSYMS) could exist for mappable symbol --> 144 <!-- files. --> 145 <p><a name="index-core_002dfile-961"></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 146of memory”. Traditionally, core files contain only some parts of the 147address space of the process that generated them; <span class="sc">gdb</span> can access the 148executable file itself for other parts. 149 150 <p><code>core-file</code> with no argument specifies that no core file is 151to be used. 152 153 <p>Note that the core file is ignored when your program is actually running 154under <span class="sc">gdb</span>. So, if you have been running your program and you 155wish to debug a core file instead, you must kill the subprocess in which 156the program is running. To do this, use the <code>kill</code> command 157(see <a href="Kill-Process.html#Kill-Process">Killing the Child Process</a>). 158 159 <p><a name="index-add_002dsymbol_002dfile-962"></a><a name="index-dynamic-linking-963"></a><br><dt><code>add-symbol-file </code><var>filename</var> <var>address</var><dt><code>add-symbol-file </code><var>filename</var> <var>address</var> <span class="roman">[</span><code> -readnow </code><span class="roman">]</span><dt><code>add-symbol-file </code><var>filename</var> <span class="roman">-s</span><var>section</var> <var>address</var><code> ...</code><dd>The <code>add-symbol-file</code> command reads additional symbol table 160information from the file <var>filename</var>. You would use this command 161when <var>filename</var> has been dynamically loaded (by some other means) 162into the program that is running. <var>address</var> should be the memory 163address at which the file has been loaded; <span class="sc">gdb</span> cannot figure 164this out for itself. You can additionally specify an arbitrary number 165of ‘<samp><span class="samp">-s</span><var>section</var> <var>address</var></samp>’ pairs, to give an explicit 166section name and base address for that section. You can specify any 167<var>address</var> as an expression. 168 169 <p>The symbol table of the file <var>filename</var> is added to the symbol table 170originally read with the <code>symbol-file</code> command. You can use the 171<code>add-symbol-file</code> command any number of times; the new symbol data 172thus read keeps adding to the old. To discard all old symbol data 173instead, use the <code>symbol-file</code> command without any arguments. 174 175 <p><a name="index-relocatable-object-files_002c-reading-symbols-from-964"></a><a name="index-object-files_002c-relocatable_002c-reading-symbols-from-965"></a><a name="index-reading-symbols-from-relocatable-object-files-966"></a><a name="index-symbols_002c-reading-from-relocatable-object-files-967"></a><a name="index-g_t_0040file_007b_002eo_007d-files_002c-reading-symbols-from-968"></a>Although <var>filename</var> is typically a shared library file, an 176executable file, or some other object file which has been fully 177relocated for loading into a process, you can also load symbolic 178information from relocatable <samp><span class="file">.o</span></samp> files, as long as: 179 180 <ul> 181<li>the file's symbolic information refers only to linker symbols defined in 182that file, not to symbols defined by other object files, 183<li>every section the file's symbolic information refers to has actually 184been loaded into the inferior, as it appears in the file, and 185<li>you can determine the address at which every section was loaded, and 186provide these to the <code>add-symbol-file</code> command. 187</ul> 188 189 <p class="noindent">Some embedded operating systems, like Sun Chorus and VxWorks, can load 190relocatable files into an already running program; such systems 191typically make the requirements above easy to meet. However, it's 192important to recognize that many native systems use complex link 193procedures (<code>.linkonce</code> section factoring and C<tt>++</tt> constructor table 194assembly, for example) that make the requirements difficult to meet. In 195general, one cannot assume that using <code>add-symbol-file</code> to read a 196relocatable object file's symbolic information will have the same effect 197as linking the relocatable object file into the program in the normal 198way. 199 200 <p><code>add-symbol-file</code> does not repeat if you press <RET> after using it. 201 202 <p><a name="index-add_002dsymbol_002dfile_002dfrom_002dmemory-969"></a><a name="index-g_t_0040code_007bsyscall-DSO_007d-970"></a><a name="index-load-symbols-from-memory-971"></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 203object file whose image is mapped directly into the inferior's memory. 204For example, the Linux kernel maps a <code>syscall DSO</code> into each 205process's address space; this DSO provides kernel-specific code for 206some system calls. The argument can be any expression whose 207evaluation yields the address of the file's shared object file header. 208For this command to work, you must have used <code>symbol-file</code> or 209<code>exec-file</code> commands in advance. 210 211 <p><a name="index-add_002dshared_002dsymbol_002dfiles-972"></a><a name="index-assf-973"></a><br><dt><code>add-shared-symbol-files </code><var>library-file</var><dt><code>assf </code><var>library-file</var><dd>The <code>add-shared-symbol-files</code> command can currently be used only 212in the Cygwin build of <span class="sc">gdb</span> on MS-Windows OS, where it is an 213alias for the <code>dll-symbols</code> command (see <a href="Cygwin-Native.html#Cygwin-Native">Cygwin Native</a>). 214<span class="sc">gdb</span> automatically looks for shared libraries, however if 215<span class="sc">gdb</span> does not find yours, you can invoke 216<code>add-shared-symbol-files</code>. It takes one argument: the shared 217library's file name. <code>assf</code> is a shorthand alias for 218<code>add-shared-symbol-files</code>. 219 220 <p><a name="index-section-974"></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 221<var>section</var> of the exec file to <var>addr</var>. This can be used if the 222exec file does not contain section addresses, (such as in the 223<code>a.out</code> format), or when the addresses specified in the file 224itself are wrong. Each section must be changed separately. The 225<code>info files</code> command, described below, lists all the sections and 226their addresses. 227 228 <p><a name="index-info-files-975"></a><a name="index-info-target-976"></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 229current target (see <a href="Targets.html#Targets">Specifying a Debugging Target</a>), 230including the names of the executable and core dump files currently in 231use by <span class="sc">gdb</span>, and the files from which symbols were loaded. The 232command <code>help target</code> lists all possible targets rather than 233current ones. 234 235 <p><a name="index-maint-info-sections-977"></a><br><dt><code>maint info sections</code><dd>Another command that can give you extra information about program sections 236is <code>maint info sections</code>. In addition to the section information 237displayed by <code>info files</code>, this command displays the flags and file 238offset of each section in the executable and core dump files. In addition, 239<code>maint info sections</code> provides the following command options (which 240may be arbitrarily combined): 241 242 <dl> 243<dt><code>ALLOBJ</code><dd>Display sections for all loaded object files, including shared libraries. 244<br><dt><var>sections</var><dd>Display info only for named <var>sections</var>. 245<br><dt><var>section-flags</var><dd>Display info only for sections for which <var>section-flags</var> are true. 246The section flags that <span class="sc">gdb</span> currently knows about are: 247 <dl> 248<dt><code>ALLOC</code><dd>Section will have space allocated in the process when loaded. 249Set for all sections except those containing debug information. 250<br><dt><code>LOAD</code><dd>Section will be loaded from the file into the child process memory. 251Set for pre-initialized code and data, clear for <code>.bss</code> sections. 252<br><dt><code>RELOC</code><dd>Section needs to be relocated before loading. 253<br><dt><code>READONLY</code><dd>Section cannot be modified by the child process. 254<br><dt><code>CODE</code><dd>Section contains executable code only. 255<br><dt><code>DATA</code><dd>Section contains data only (no executable code). 256<br><dt><code>ROM</code><dd>Section will reside in ROM. 257<br><dt><code>CONSTRUCTOR</code><dd>Section contains data for constructor/destructor lists. 258<br><dt><code>HAS_CONTENTS</code><dd>Section is not empty. 259<br><dt><code>NEVER_LOAD</code><dd>An instruction to the linker to not output the section. 260<br><dt><code>COFF_SHARED_LIBRARY</code><dd>A notification to the linker that the section contains 261COFF shared library information. 262<br><dt><code>IS_COMMON</code><dd>Section contains common symbols. 263</dl> 264 </dl> 265 <a name="index-set-trust_002dreadonly_002dsections-978"></a><a name="index-read_002donly-sections-979"></a><br><dt><code>set trust-readonly-sections on</code><dd>Tell <span class="sc">gdb</span> that readonly sections in your object file 266really are read-only (i.e. that their contents will not change). 267In that case, <span class="sc">gdb</span> can fetch values from these sections 268out of the object file, rather than from the target program. 269For some targets (notably embedded ones), this can be a significant 270enhancement to debugging performance. 271 272 <p>The default is off. 273 274 <br><dt><code>set trust-readonly-sections off</code><dd>Tell <span class="sc">gdb</span> not to trust readonly sections. This means that 275the contents of the section might change while the program is running, 276and must therefore be fetched from the target when needed. 277 278 <br><dt><code>show trust-readonly-sections</code><dd>Show the current setting of trusting readonly sections. 279</dl> 280 281 <p>All file-specifying commands allow both absolute and relative file names 282as arguments. <span class="sc">gdb</span> always converts the file name to an absolute file 283name and remembers it that way. 284 285 <p><a name="index-shared-libraries-980"></a><a name="Shared-Libraries"></a><span class="sc">gdb</span> supports <span class="sc">gnu</span>/Linux, MS-Windows, HP-UX, SunOS, SVr4, Irix, 286and IBM RS/6000 AIX shared libraries. 287 288 <p>On MS-Windows <span class="sc">gdb</span> must be linked with the Expat library to support 289shared libraries. See <a href="Expat.html#Expat">Expat</a>. 290 291 <p><span class="sc">gdb</span> automatically loads symbol definitions from shared libraries 292when you use the <code>run</code> command, or when you examine a core file. 293(Before you issue the <code>run</code> command, <span class="sc">gdb</span> does not understand 294references to a function in a shared library, however—unless you are 295debugging a core file). 296 297 <p>On HP-UX, if the program loads a library explicitly, <span class="sc">gdb</span> 298automatically loads the symbols at the time of the <code>shl_load</code> call. 299 300<!-- FIXME: some @value{GDBN} release may permit some refs to undef --> 301<!-- FIXME...symbols-eg in a break cmd-assuming they are from a shared --> 302<!-- FIXME...lib; check this from time to time when updating manual --> 303 <p>There are times, however, when you may wish to not automatically load 304symbol definitions from shared libraries, such as when they are 305particularly large or there are many of them. 306 307 <p>To control the automatic loading of shared library symbols, use the 308commands: 309 310 311<a name="index-set-auto_002dsolib_002dadd-981"></a> 312<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 313will be loaded automatically when the inferior begins execution, you 314attach to an independently started inferior, or when the dynamic linker 315informs <span class="sc">gdb</span> that a new library has been loaded. If <var>mode</var> 316is <code>off</code>, symbols must be loaded manually, using the 317<code>sharedlibrary</code> command. The default value is <code>on</code>. 318 319 <p><a name="index-memory-used-for-symbol-tables-982"></a>If your program uses lots of shared libraries with debug info that 320takes large amounts of memory, you can decrease the <span class="sc">gdb</span> 321memory footprint by preventing it from automatically loading the 322symbols from shared libraries. To that end, type <kbd>set 323auto-solib-add off</kbd> before running the inferior, then load each 324library whose debug symbols you do need with <kbd>sharedlibrary 325</kbd><var>regexp</var>, where <var>regexp</var> is a regular expression that matches 326the libraries whose symbols you want to be loaded. 327 328 <p><a name="index-show-auto_002dsolib_002dadd-983"></a><br><dt><code>show auto-solib-add</code><dd>Display the current autoloading mode. 329</dl> 330 331 <p><a name="index-load-shared-library-984"></a>To explicitly load shared library symbols, use the <code>sharedlibrary</code> 332command: 333 334 335<a name="index-info-sharedlibrary-985"></a> 336<a name="index-info-share-986"></a> 337<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 338that match <var>regex</var>. If <var>regex</var> is omitted then print 339all shared libraries that are loaded. 340 341 <p><a name="index-sharedlibrary-987"></a><a name="index-share-988"></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 342Unix regular expression. 343As with files loaded automatically, it only loads shared libraries 344required by your program for a core file or after typing <code>run</code>. If 345<var>regex</var> is omitted all shared libraries required by your program are 346loaded. 347 348 <br><dt><code>nosharedlibrary</code><dd><a name="index-nosharedlibrary-989"></a><a name="index-unload-symbols-from-shared-libraries-990"></a>Unload all shared object library symbols. This discards all symbols 349that have been loaded from all shared libraries. Symbols from shared 350libraries that were loaded by explicit user requests are not 351discarded. 352</dl> 353 354 <p>Sometimes you may wish that <span class="sc">gdb</span> stops and gives you control 355when any of shared library events happen. Use the <code>set 356stop-on-solib-events</code> command for this: 357 358 <dl> 359<dt><code>set stop-on-solib-events</code><dd><a name="index-set-stop_002don_002dsolib_002devents-991"></a>This command controls whether <span class="sc">gdb</span> should give you control 360when the dynamic linker notifies it about some shared library event. 361The most common event of interest is loading or unloading of a new 362shared library. 363 364 <br><dt><code>show stop-on-solib-events</code><dd><a name="index-show-stop_002don_002dsolib_002devents-992"></a>Show whether <span class="sc">gdb</span> stops and gives you control when shared 365library events happen. 366</dl> 367 368 <p>Shared libraries are also supported in many cross or remote debugging 369configurations. <span class="sc">gdb</span> needs to have access to the target's libraries; 370this can be accomplished either by providing copies of the libraries 371on the host system, or by asking <span class="sc">gdb</span> to automatically retrieve the 372libraries from the target. If copies of the target libraries are 373provided, they need to be the same as the target libraries, although the 374copies on the target can be stripped as long as the copies on the host are 375not. 376 377 <p><a name="index-where-to-look-for-shared-libraries-993"></a>For remote debugging, you need to tell <span class="sc">gdb</span> where the target 378libraries are, so that it can load the correct copies—otherwise, it 379may try to load the host's libraries. <span class="sc">gdb</span> has two variables 380to specify the search directories for target libraries. 381 382 383<a name="index-prefix-for-shared-library-file-names-994"></a> 384<a name="index-system-root_002c-alternate-995"></a> 385<a name="index-set-solib_002dabsolute_002dprefix-996"></a> 386<a name="index-set-sysroot-997"></a> 387<dl><dt><code>set sysroot </code><var>path</var><dd>Use <var>path</var> as the system root for the program being debugged. Any 388absolute shared library paths will be prefixed with <var>path</var>; many 389runtime loaders store the absolute paths to the shared library in the 390target program's memory. If you use <code>set sysroot</code> to find shared 391libraries, they need to be laid out in the same way that they are on 392the target, with e.g. a <samp><span class="file">/lib</span></samp> and <samp><span class="file">/usr/lib</span></samp> hierarchy 393under <var>path</var>. 394 395 <p>If <var>path</var> starts with the sequence <samp><span class="file">remote:</span></samp>, <span class="sc">gdb</span> will 396retrieve the target libraries from the remote system. This is only 397supported when using a remote target that supports the <code>remote get</code> 398command (see <a href="File-Transfer.html#File-Transfer">Sending files to a remote system</a>). 399The part of <var>path</var> following the initial <samp><span class="file">remote:</span></samp> 400(if present) is used as system root prefix on the remote file system. 401<a rel="footnote" href="#fn-1" name="fnd-1"><sup>1</sup></a> 402 403 <p>For targets with an MS-DOS based filesystem, such as MS-Windows and 404SymbianOS, <span class="sc">gdb</span> tries prefixing a few variants of the target 405absolute file name with <var>path</var>. But first, on Unix hosts, 406<span class="sc">gdb</span> converts all backslash directory separators into forward 407slashes, because the backslash is not a directory separator on Unix: 408 409 <pre class="smallexample"> c:\foo\bar.dll ⇒ c:/foo/bar.dll 410</pre> 411 <p>Then, <span class="sc">gdb</span> attempts prefixing the target file name with 412<var>path</var>, and looks for the resulting file name in the host file 413system: 414 415 <pre class="smallexample"> c:/foo/bar.dll ⇒ /path/to/sysroot/c:/foo/bar.dll 416</pre> 417 <p>If that does not find the shared library, <span class="sc">gdb</span> tries removing 418the ‘<samp><span class="samp">:</span></samp>’ character from the drive spec, both for convenience, and, 419for the case of the host file system not supporting file names with 420colons: 421 422 <pre class="smallexample"> c:/foo/bar.dll ⇒ /path/to/sysroot/c/foo/bar.dll 423</pre> 424 <p>This makes it possible to have a system root that mirrors a target 425with more than one drive. E.g., you may want to setup your local 426copies of the target system shared libraries like so (note ‘<samp><span class="samp">c</span></samp>’ vs 427‘<samp><span class="samp">z</span></samp>’): 428 429 <pre class="smallexample"> <samp><span class="file">/path/to/sysroot/c/sys/bin/foo.dll</span></samp> 430 <samp><span class="file">/path/to/sysroot/c/sys/bin/bar.dll</span></samp> 431 <samp><span class="file">/path/to/sysroot/z/sys/bin/bar.dll</span></samp> 432</pre> 433 <p class="noindent">and point the system root at <samp><span class="file">/path/to/sysroot</span></samp>, so that 434<span class="sc">gdb</span> can find the correct copies of both 435<samp><span class="file">c:\sys\bin\foo.dll</span></samp>, and <samp><span class="file">z:\sys\bin\bar.dll</span></samp>. 436 437 <p>If that still does not find the shared library, <span class="sc">gdb</span> tries 438removing the whole drive spec from the target file name: 439 440 <pre class="smallexample"> c:/foo/bar.dll ⇒ /path/to/sysroot/foo/bar.dll 441</pre> 442 <p>This last lookup makes it possible to not care about the drive name, 443if you don't want or need to. 444 445 <p>The <code>set solib-absolute-prefix</code> command is an alias for <code>set 446sysroot</code>. 447 448 <p><a name="index-default-system-root-998"></a><a name="index-g_t_0040samp_007b_002d_002dwith_002dsysroot_007d-999"></a>You can set the default system root by using the configure-time 449‘<samp><span class="samp">--with-sysroot</span></samp>’ option. If the system root is inside 450<span class="sc">gdb</span>'s configured binary prefix (set with ‘<samp><span class="samp">--prefix</span></samp>’ or 451‘<samp><span class="samp">--exec-prefix</span></samp>’), then the default system root will be updated 452automatically if the installed <span class="sc">gdb</span> is moved to a new 453location. 454 455 <p><a name="index-show-sysroot-1000"></a><br><dt><code>show sysroot</code><dd>Display the current shared library prefix. 456 457 <p><a name="index-set-solib_002dsearch_002dpath-1001"></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 458directories to search for shared libraries. ‘<samp><span class="samp">solib-search-path</span></samp>’ 459is used after ‘<samp><span class="samp">sysroot</span></samp>’ fails to locate the library, or if the 460path to the library is relative instead of absolute. If you want to 461use ‘<samp><span class="samp">solib-search-path</span></samp>’ instead of ‘<samp><span class="samp">sysroot</span></samp>’, be sure to set 462‘<samp><span class="samp">sysroot</span></samp>’ to a nonexistent directory to prevent <span class="sc">gdb</span> from 463finding your host's libraries. ‘<samp><span class="samp">sysroot</span></samp>’ is preferred; setting 464it to a nonexistent directory may interfere with automatic loading 465of shared library symbols. 466 467 <p><a name="index-show-solib_002dsearch_002dpath-1002"></a><br><dt><code>show solib-search-path</code><dd>Display the current shared library search path. 468 469 <p><a name="index-DOS-file_002dname-semantics-of-file-names_002e-1003"></a><a name="index-set-target_002dfile_002dsystem_002dkind-_0028unix_007cdos_002dbased_007cauto_0029-1004"></a><a name="index-show-target_002dfile_002dsystem_002dkind-1005"></a><br><dt><code>set target-file-system-kind </code><var>kind</var><dd>Set assumed file system kind for target reported file names. 470 471 <p>Shared library file names as reported by the target system may not 472make sense as is on the system <span class="sc">gdb</span> is running on. For 473example, when remote debugging a target that has MS-DOS based file 474system semantics, from a Unix host, the target may be reporting to 475<span class="sc">gdb</span> a list of loaded shared libraries with file names such as 476<samp><span class="file">c:\Windows\kernel32.dll</span></samp>. On Unix hosts, there's no concept of 477drive letters, so the ‘<samp><span class="samp">c:\</span></samp>’ prefix is not normally understood as 478indicating an absolute file name, and neither is the backslash 479normally considered a directory separator character. In that case, 480the native file system would interpret this whole absolute file name 481as a relative file name with no directory components. This would make 482it impossible to point <span class="sc">gdb</span> at a copy of the remote target's 483shared libraries on the host using <code>set sysroot</code>, and impractical 484with <code>set solib-search-path</code>. Setting 485<code>target-file-system-kind</code> to <code>dos-based</code> tells <span class="sc">gdb</span> 486to interpret such file names similarly to how the target would, and to 487map them to file names valid on <span class="sc">gdb</span>'s native file system 488semantics. The value of <var>kind</var> can be <code>"auto"</code>, in addition 489to one of the supported file system kinds. In that case, <span class="sc">gdb</span> 490tries to determine the appropriate file system variant based on the 491current target's operating system (see <a href="ABI.html#ABI">Configuring the Current ABI</a>). The supported file system settings are: 492 493 <dl> 494<dt><code>unix</code><dd>Instruct <span class="sc">gdb</span> to assume the target file system is of Unix 495kind. Only file names starting the forward slash (‘<samp><span class="samp">/</span></samp>’) character 496are considered absolute, and the directory separator character is also 497the forward slash. 498 499 <br><dt><code>dos-based</code><dd>Instruct <span class="sc">gdb</span> to assume the target file system is DOS based. 500File names starting with either a forward slash, or a drive letter 501followed by a colon (e.g., ‘<samp><span class="samp">c:</span></samp>’), are considered absolute, and 502both the slash (‘<samp><span class="samp">/</span></samp>’) and the backslash (‘<samp><span class="samp">\\</span></samp>’) characters are 503considered directory separators. 504 505 <br><dt><code>auto</code><dd>Instruct <span class="sc">gdb</span> to use the file system kind associated with the 506target operating system (see <a href="ABI.html#ABI">Configuring the Current ABI</a>). 507This is the default. 508</dl> 509 </dl> 510 511 <div class="footnote"> 512<hr> 513<h4>Footnotes</h4><p class="footnote"><small>[<a name="fn-1" href="#fnd-1">1</a>]</small> If you want to specify a local system root using a directory 514that happens to be named <samp><span class="file">remote:</span></samp>, you need to use some equivalent 515variant of the name like <samp><span class="file">./remote:</span></samp>.</p> 516 517 <hr></div> 518 519 </body></html> 520 521