Commit | Line | Data |
---|---|---|
9bcc06ef RP |
1 | _dnl__ -*- Texinfo -*- |
2 | _dnl__ Copyright (c) 1988 1989 1990 1991 Free Software Foundation, Inc. | |
3 | _dnl__ This file is part of the source for the GDB manual. | |
16e58d91 | 4 | @c M4 FRAGMENT: $Id$ |
9bcc06ef RP |
5 | @node _GDBN__ Files, Targets, Altering, Top |
6 | @chapter _GDBN__'s Files | |
7 | ||
8 | @menu | |
9 | * Files:: Commands to Specify Files | |
10 | * Symbol Errors:: Errors Reading Symbol Files | |
11 | @end menu | |
12 | ||
13 | @node Files, Symbol Errors, _GDBN__ Files, _GDBN__ Files | |
14 | @section Commands to Specify Files | |
15 | @cindex core dump file | |
16 | @cindex symbol table | |
17 | _GDBN__ needs to know the file name of the program to be debugged, both in | |
18 | order to read its symbol table and in order to start the program. To | |
19 | debug a core dump of a previous run, _GDBN__ must be told the file name of | |
20 | the core dump. | |
21 | ||
22 | The usual way to specify the executable and core dump file names is with | |
23 | the command arguments given when you start _GDBN__, as discussed in | |
24 | @pxref{Invocation}. | |
25 | ||
26 | Occasionally it is necessary to change to a different file during a | |
27 | _GDBN__ session. Or you may run _GDBN__ and forget to specify the files you | |
28 | want to use. In these situations the _GDBN__ commands to specify new files | |
29 | are useful. | |
30 | ||
31 | @table @code | |
32 | @item file @var{filename} | |
33 | @cindex executable file | |
34 | @kindex file | |
35 | Use @var{filename} as the program to be debugged. It is read for its | |
36 | symbols and for the contents of pure memory. It is also the program | |
37 | executed when you use the @code{run} command. If you do not specify a | |
38 | directory and the file is not found in _GDBN__'s working directory, | |
39 | ||
40 | _GDBN__ uses the environment variable @code{PATH} as a list of | |
41 | directories to search, just as the shell does when looking for a program | |
42 | to run. You can change the value of this variable, for both _GDBN__ and | |
43 | your program, using the @code{path} command. | |
44 | ||
45 | @code{file} with no argument makes _GDBN__ discard any information it | |
46 | has on both executable file and the symbol table. | |
47 | ||
48 | @item exec-file @var{filename} | |
49 | @kindex exec-file | |
50 | Specify that the program to be run (but not the symbol table) is found | |
51 | in @var{filename}. _GDBN__ will search the environment variable @code{PATH} | |
52 | if necessary to locate the program. | |
53 | ||
54 | @item symbol-file @var{filename} | |
55 | @kindex symbol-file | |
56 | Read symbol table information from file @var{filename}. @code{PATH} is | |
57 | searched when necessary. Use the @code{file} command to get both symbol | |
58 | table and program to run from the same file. | |
59 | ||
60 | @code{symbol-file} with no argument clears out _GDBN__'s information on your | |
61 | program's symbol table. | |
62 | ||
63 | The @code{symbol-file} command causes _GDBN__ to forget the contents of its | |
64 | convenience variables, the value history, and all breakpoints and | |
65 | auto-display expressions. This is because they may contain pointers to | |
66 | the internal data recording symbols and data types, which are part of | |
67 | the old symbol table data being discarded inside _GDBN__. | |
68 | ||
69 | @code{symbol-file} will not repeat if you press @key{RET} again after | |
70 | executing it once. | |
71 | ||
72 | On some kinds of object files, the @code{symbol-file} command does not | |
73 | actually read the symbol table in full right away. Instead, it scans | |
74 | the symbol table quickly to find which source files and which symbols | |
75 | are present. The details are read later, one source file at a time, | |
76 | when they are needed. | |
77 | ||
78 | The purpose of this two-stage reading strategy is to make _GDBN__ start up | |
79 | faster. For the most part, it is invisible except for occasional pauses | |
80 | while the symbol table details for a particular source file are being | |
81 | read. (The @code{set verbose} command can turn these pauses into | |
82 | messages if desired. @xref{Messages/Warnings}). | |
83 | ||
84 | When the symbol table is stored in COFF format, @code{symbol-file} does | |
85 | read the symbol table data in full right away. We haven't implemented | |
86 | the two-stage strategy for COFF yet. | |
87 | ||
88 | When _GDBN__ is configured for a particular environment, it will | |
89 | understand debugging information in whatever format is the standard | |
90 | generated for that environment; you may use either a GNU compiler, or | |
91 | other compilers that adhere to the local conventions. Best results are | |
92 | usually obtained from GNU compilers; for example, using @code{_GCC__} | |
93 | you can generate debugging information for optimized code. | |
94 | ||
95 | @item core-file @var{filename} | |
96 | @itemx core @var{filename} | |
97 | @kindex core | |
98 | @kindex core-file | |
99 | Specify the whereabouts of a core dump file to be used as the ``contents | |
100 | of memory''. Traditionally, core files contain only some parts of the | |
101 | address space of the process that generated them; _GDBN__ can access the | |
102 | executable file itself for other parts. | |
103 | ||
104 | @code{core-file} with no argument specifies that no core file is | |
105 | to be used. | |
106 | ||
107 | Note that the core file is ignored when your program is actually running | |
108 | under _GDBN__. So, if you have been running the program and you wish to | |
109 | debug a core file instead, you must kill the subprocess in which the | |
110 | program is running. To do this, use the @code{kill} command | |
111 | (@pxref{Kill Process}). | |
112 | ||
113 | @item load @var{filename} | |
114 | @kindex load | |
115 | _if__(_GENERIC__) | |
116 | Depending on what remote debugging facilities are configured into | |
117 | _GDBN__, the @code{load} command may be available. Where it exists, it | |
118 | is meant to make @var{filename} (an executable) available for debugging | |
119 | on the remote system---by downloading, or dynamic linking, for example. | |
120 | @code{load} also records @var{filename}'s symbol table in _GDBN__, like | |
121 | the @code{add-symbol-file} command. | |
122 | ||
123 | If @code{load} is not available on your _GDBN__, attempting to execute | |
124 | it gets the error message ``@code{You can't do that when your target is | |
125 | @dots{}}'' | |
126 | _fi__(_GENERIC__) | |
127 | ||
128 | _if__(_VXWORKS__) | |
129 | On VxWorks, @code{load} will dynamically link @var{filename} on the | |
130 | current target system as well as adding its symbols in _GDBN__. | |
131 | _fi__(_VXWORKS__) | |
132 | ||
133 | _if__(_I960__) | |
134 | @cindex download to Nindy-960 | |
135 | With the Nindy interface to an Intel 960 board, @code{load} will | |
136 | download @var{filename} to the 960 as well as adding its symbols in | |
137 | _GDBN__. | |
138 | _fi__(_I960__) | |
139 | ||
140 | @code{load} will not repeat if you press @key{RET} again after using it. | |
141 | ||
142 | @item add-symbol-file @var{filename} @var{address} | |
143 | @kindex add-symbol-file | |
144 | @cindex dynamic linking | |
145 | The @code{add-symbol-file} command reads additional symbol table information | |
146 | from the file @var{filename}. You would use this command when that file | |
147 | has been dynamically loaded (by some other means) into the program that | |
148 | is running. @var{address} should be the memory address at which the | |
149 | file has been loaded; _GDBN__ cannot figure this out for itself. | |
150 | ||
151 | The symbol table of the file @var{filename} is added to the symbol table | |
152 | originally read with the @code{symbol-file} command. You can use the | |
153 | @code{add-symbol-file} command any number of times; the new symbol data thus | |
154 | read keeps adding to the old. To discard all old symbol data instead, | |
155 | use the @code{symbol-file} command. | |
156 | ||
157 | @code{add-symbol-file} will not repeat if you press @key{RET} after using it. | |
158 | ||
159 | @item info files | |
160 | @itemx info target | |
161 | @kindex info files | |
162 | @kindex info target | |
163 | @code{info files} and @code{info target} are synonymous; both print the | |
164 | current targets (@pxref{Targets}), including the names of the executable | |
165 | and core dump files currently in use by _GDBN__, and the files from | |
166 | which symbols were loaded. The command @code{help targets} lists all | |
167 | possible targets rather than current ones. | |
168 | ||
169 | @end table | |
170 | ||
171 | All file-specifying commands allow both absolute and relative file names | |
172 | as arguments. _GDBN__ always converts the file name to an absolute path | |
173 | name and remembers it that way. | |
174 | ||
175 | @kindex sharedlibrary | |
176 | @kindex share | |
177 | @cindex shared libraries | |
178 | ||
179 | _GDBN__ supports the SunOS shared library format. Symbols from a shared | |
180 | library cannot be referenced before the shared library has been linked | |
181 | with the program. (That is to say, until after you type @code{run} and | |
182 | the function @code{main} has been entered; or when examining core | |
183 | files.) Once the shared library has been linked in, you can use the | |
184 | following commands: | |
185 | ||
186 | @table @code | |
187 | @item sharedlibrary @var{regex} | |
188 | @itemx share @var{regex} | |
189 | Load shared object library symbols for files matching a UNIX regular | |
190 | expression. | |
191 | ||
192 | @item share | |
193 | @itemx sharedlibrary | |
194 | Load symbols for all shared libraries. | |
195 | ||
196 | @item info share | |
197 | @itemx info sharedlibrary | |
198 | @kindex info sharedlibrary | |
199 | @kindex info share | |
200 | Print the names of the shared libraries which you have loaded with the | |
201 | @code{sharedlibrary} command. | |
202 | @end table | |
203 | ||
204 | @code{sharedlibrary} does not repeat automatically when you press | |
205 | @key{RET} after using it once. | |
206 | ||
207 | @node Symbol Errors, , Files, _GDBN__ Files | |
208 | @section Errors Reading Symbol Files | |
209 | While a symbol file is being read, _GDBN__ will occasionally encounter | |
210 | problems, such as symbol types it does not recognize, or known bugs in | |
211 | compiler output. By default, it prints one message about each such | |
212 | type of problem, no matter how many times the problem occurs. You can | |
213 | ask it to print more messages, to see how many times the problems occur, | |
214 | or can shut the messages off entirely, with the @code{set | |
215 | complaints} command (@xref{Messages/Warnings}). | |
216 | ||
217 | The messages currently printed, and their meanings, are: | |
218 | ||
219 | @table @code | |
220 | @item inner block not inside outer block in @var{symbol} | |
221 | ||
222 | The symbol information shows where symbol scopes begin and end | |
223 | (such as at the start of a function or a block of statements). This | |
224 | error indicates that an inner scope block is not fully contained | |
225 | in its outer scope blocks. | |
226 | ||
227 | _GDBN__ circumvents the problem by treating the inner block as if it had | |
228 | the same scope as the outer block. In the error message, @var{symbol} | |
229 | may be shown as ``@code{(don't know)}'' if the outer block is not a | |
230 | function. | |
231 | ||
232 | @item block at @var{address} out of order | |
233 | ||
234 | The symbol information for symbol scope blocks should occur in | |
235 | order of increasing addresses. This error indicates that it does not | |
236 | do so. | |
237 | ||
238 | _GDBN__ does not circumvent this problem, and will have trouble locating | |
239 | symbols in the source file whose symbols being read. (You can often | |
240 | determine what source file is affected by specifying @code{set verbose | |
241 | on}. @xref{Messages/Warnings}.) | |
242 | ||
243 | @item bad block start address patched | |
244 | ||
245 | The symbol information for a symbol scope block has a start address | |
246 | smaller than the address of the preceding source line. This is known | |
247 | to occur in the SunOS 4.1.1 (and earlier) C compiler. | |
248 | ||
249 | _GDBN__ circumvents the problem by treating the symbol scope block as | |
250 | starting on the previous source line. | |
251 | ||
252 | @c @item{encountered DBX-style class variable debugging information. | |
253 | @c You seem to have compiled your program with "g++ -g0" instead of "g++ -g". | |
254 | @c Therefore _GDBN__ will not know about your class variables} | |
255 | @c | |
256 | @c This error indicates that the symbol information produced for a C++ | |
257 | @c program includes zero-size fields, which indicated static fields in | |
258 | @c a previous release of the G++ compiler. This message is probably | |
259 | @c obsolete. | |
260 | @c | |
261 | @item bad string table offset in symbol @var{n} | |
262 | ||
263 | @cindex foo | |
264 | Symbol number @var{n} contains a pointer into the string table which is | |
265 | larger than the size of the string table. | |
266 | ||
267 | _GDBN__ circumvents the problem by considering the symbol to have the | |
268 | name @code{foo}, which may cause other problems if many symbols end up | |
269 | with this name. | |
270 | ||
271 | @item unknown symbol type @code{0x@var{nn}} | |
272 | ||
273 | The symbol information contains new data types that _GDBN__ does not yet | |
274 | know how to read. @code{0x@var{nn}} is the symbol type of the misunderstood | |
275 | information, in hexadecimal. | |
276 | ||
277 | _GDBN__ circumvents the error by ignoring this symbol information. This | |
278 | will usually allow the program to be debugged, though certain symbols | |
279 | will not be accessible. If you encounter such a problem and feel like | |
280 | debugging it, you can debug @code{_GDBP__} with itself, breakpoint on | |
281 | @code{complain}, then go up to the function @code{read_dbx_symtab} and | |
282 | examine @code{*bufp} to see the symbol. | |
283 | ||
284 | @item stub type has NULL name | |
285 | _GDBN__ could not find the full definition for a struct or class. | |
286 | ||
287 | @ignore | |
288 | @c this is #if 0'd in dbxread.c as of (at least!) 17 may 1991 | |
289 | @item const/volatile indicator missing, got '@var{X}' | |
290 | ||
291 | The symbol information for a C++ member function is missing some | |
292 | information that the compiler should have output for it. | |
293 | @end ignore | |
294 | ||
295 | @item C++ type mismatch between compiler and debugger | |
296 | ||
297 | The debugger could not parse a type specification output by the compiler | |
298 | for some C++ object. | |
299 | ||
300 | @end table |