* gdb.base/help.exp (help source): Update expected output.
[deliverable/binutils-gdb.git] / gdb / symfile.h
1 /* Definitions for reading symbol files into GDB.
2
3 Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
4 2000, 2001, 2002, 2003, 2004, 2007, 2008, 2009, 2010
5 Free Software Foundation, Inc.
6
7 This file is part of GDB.
8
9 This program is free software; you can redistribute it and/or modify
10 it under the terms of the GNU General Public License as published by
11 the Free Software Foundation; either version 3 of the License, or
12 (at your option) any later version.
13
14 This program is distributed in the hope that it will be useful,
15 but WITHOUT ANY WARRANTY; without even the implied warranty of
16 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 GNU General Public License for more details.
18
19 You should have received a copy of the GNU General Public License
20 along with this program. If not, see <http://www.gnu.org/licenses/>. */
21
22 #if !defined (SYMFILE_H)
23 #define SYMFILE_H
24
25 /* This file requires that you first include "bfd.h". */
26 #include "symtab.h"
27
28 /* Opaque declarations. */
29 struct target_section;
30 struct objfile;
31 struct obj_section;
32 struct obstack;
33 struct block;
34
35 /* Partial symbols are stored in the psymbol_cache and pointers to
36 them are kept in a dynamically grown array that is obtained from
37 malloc and grown as necessary via realloc. Each objfile typically
38 has two of these, one for global symbols and one for static
39 symbols. Although this adds a level of indirection for storing or
40 accessing the partial symbols, it allows us to throw away duplicate
41 psymbols and set all pointers to the single saved instance. */
42
43 struct psymbol_allocation_list
44 {
45
46 /* Pointer to beginning of dynamically allocated array of pointers
47 to partial symbols. The array is dynamically expanded as
48 necessary to accommodate more pointers. */
49
50 struct partial_symbol **list;
51
52 /* Pointer to next available slot in which to store a pointer to a
53 partial symbol. */
54
55 struct partial_symbol **next;
56
57 /* Number of allocated pointer slots in current dynamic array (not
58 the number of bytes of storage). The "next" pointer will always
59 point somewhere between list[0] and list[size], and when at
60 list[size] the array will be expanded on the next attempt to
61 store a pointer. */
62
63 int size;
64 };
65
66 /* Define an array of addresses to accommodate non-contiguous dynamic
67 loading of modules. This is for use when entering commands, so we
68 can keep track of the section names until we read the file and can
69 map them to bfd sections. This structure is also used by solib.c
70 to communicate the section addresses in shared objects to
71 symbol_file_add (). */
72
73 struct section_addr_info
74 {
75 /* The number of sections for which address information is
76 available. */
77 size_t num_sections;
78 /* Sections whose names are file format dependent. */
79 struct other_sections
80 {
81 CORE_ADDR addr;
82 char *name;
83
84 /* SECTINDEX must be valid for associated BFD if ADDR is not zero. */
85 int sectindex;
86 } other[1];
87 };
88
89
90 /* A table listing the load segments in a symfile, and which segment
91 each BFD section belongs to. */
92 struct symfile_segment_data
93 {
94 /* How many segments are present in this file. If there are
95 two, the text segment is the first one and the data segment
96 is the second one. */
97 int num_segments;
98
99 /* If NUM_SEGMENTS is greater than zero, the original base address
100 of each segment. */
101 CORE_ADDR *segment_bases;
102
103 /* If NUM_SEGMENTS is greater than zero, the memory size of each
104 segment. */
105 CORE_ADDR *segment_sizes;
106
107 /* If NUM_SEGMENTS is greater than zero, this is an array of entries
108 recording which segment contains each BFD section.
109 SEGMENT_INFO[I] is S+1 if the I'th BFD section belongs to segment
110 S, or zero if it is not in any segment. */
111 int *segment_info;
112 };
113
114 /* The "quick" symbol functions exist so that symbol readers can
115 avoiding an initial read of all the symbols. For example, symbol
116 readers might choose to use the "partial symbol table" utilities,
117 which is one implementation of the quick symbol functions.
118
119 The quick symbol functions are generally opaque: the underlying
120 representation is hidden from the caller.
121
122 In general, these functions should only look at whatever special
123 index the symbol reader creates -- looking through the symbol
124 tables themselves is handled by generic code. If a function is
125 defined as returning a "symbol table", this means that the function
126 should only return a newly-created symbol table; it should not
127 examine pre-existing ones.
128
129 The exact list of functions here was determined in an ad hoc way
130 based on gdb's history. */
131
132 struct quick_symbol_functions
133 {
134 /* Return true if this objfile has any "partial" symbols
135 available. */
136 int (*has_symbols) (struct objfile *objfile);
137
138 /* Return the symbol table for the "last" file appearing in
139 OBJFILE. */
140 struct symtab *(*find_last_source_symtab) (struct objfile *objfile);
141
142 /* Forget all cached full file names for OBJFILE. */
143 void (*forget_cached_source_info) (struct objfile *objfile);
144
145 /* Look up the symbol table, in OBJFILE, of a source file named
146 NAME. If there is no '/' in the name, a match after a '/' in the
147 symbol table's file name will also work. FULL_PATH is the
148 absolute file name, and REAL_PATH is the same, run through
149 gdb_realpath.
150
151 If no such symbol table can be found, returns 0.
152
153 Otherwise, sets *RESULT to the symbol table and returns 1. This
154 might return 1 and set *RESULT to NULL if the requested file is
155 an include file that does not have a symtab of its own. */
156 int (*lookup_symtab) (struct objfile *objfile,
157 const char *name,
158 const char *full_path,
159 const char *real_path,
160 struct symtab **result);
161
162 /* Check to see if the symbol is defined in a "partial" symbol table
163 of OBJFILE. KIND should be either GLOBAL_BLOCK or STATIC_BLOCK,
164 depending on whether we want to search global symbols or static
165 symbols. NAME is the name of the symbol to look for. DOMAIN
166 indicates what sort of symbol to search for.
167
168 Returns the newly-expanded symbol table in which the symbol is
169 defined, or NULL if no such symbol table exists. */
170 struct symtab *(*lookup_symbol) (struct objfile *objfile,
171 int kind, const char *name,
172 domain_enum domain);
173
174 /* Print statistics about any indices loaded for OBJFILE. The
175 statistics should be printed to gdb_stdout. This is used for
176 "maint print statistics". */
177 void (*print_stats) (struct objfile *objfile);
178
179 /* Dump any indices loaded for OBJFILE. The dump should go to
180 gdb_stdout. This is used for "maint print objfiles". */
181 void (*dump) (struct objfile *objfile);
182
183 /* This is called by objfile_relocate to relocate any indices loaded
184 for OBJFILE. */
185 void (*relocate) (struct objfile *objfile,
186 struct section_offsets *new_offsets,
187 struct section_offsets *delta);
188
189 /* Find all the symbols in OBJFILE named FUNC_NAME, and ensure that
190 the corresponding symbol tables are loaded. */
191 void (*expand_symtabs_for_function) (struct objfile *objfile,
192 const char *func_name);
193
194 /* Read all symbol tables associated with OBJFILE. */
195 void (*expand_all_symtabs) (struct objfile *objfile);
196
197 /* Read all symbol tables associated with OBJFILE which have the
198 file name FILENAME. */
199 void (*expand_symtabs_with_filename) (struct objfile *objfile,
200 const char *filename);
201
202 /* Return the file name of the file holding the symbol in OBJFILE
203 named NAME. If no such symbol exists in OBJFILE, return NULL. */
204 char *(*find_symbol_file) (struct objfile *objfile, const char *name);
205
206 /* This method is specific to Ada. It walks the partial symbol
207 tables of OBJFILE looking for a name match. WILD_MATCH and
208 IS_NAME_SUFFIX are predicate functions that the implementation
209 may call to check for a match.
210
211 This function is completely ad hoc and new implementations should
212 refer to the psymtab implementation to see what to do. */
213 void (*map_ada_symtabs) (struct objfile *objfile,
214 int (*wild_match) (const char *, int, const char *),
215 int (*is_name_suffix) (const char *),
216 void (*callback) (struct objfile *,
217 struct symtab *, void *),
218 const char *name, int global,
219 domain_enum namespace, int wild,
220 void *data);
221
222 /* Expand all symbol tables in OBJFILE matching some criteria.
223
224 FILE_MATCHER is called for each file in OBJFILE. The file name
225 and the DATA argument are passed to it. If it returns zero, this
226 file is skipped.
227
228 Otherwise, if the file is not skipped, then NAME_MATCHER is
229 called for each symbol defined in the file. The symbol's
230 "natural" name and DATA are passed to NAME_MATCHER.
231
232 If NAME_MATCHER returns zero, then this symbol is skipped.
233
234 Otherwise, if this symbol is not skipped, and it matches KIND,
235 then this symbol's symbol table is expanded.
236
237 DATA is user data that is passed unmodified to the callback
238 functions. */
239 void (*expand_symtabs_matching) (struct objfile *objfile,
240 int (*file_matcher) (const char *, void *),
241 int (*name_matcher) (const char *, void *),
242 domain_enum kind,
243 void *data);
244
245 /* Return the symbol table from OBJFILE that contains PC and
246 SECTION. Return NULL if there is no such symbol table. This
247 should return the symbol table that contains a symbol whose
248 address exactly matches PC, or, if there is no exact match, the
249 symbol table that contains a symbol whose address is closest to
250 PC. */
251 struct symtab *(*find_pc_sect_symtab) (struct objfile *objfile,
252 struct minimal_symbol *msymbol,
253 CORE_ADDR pc,
254 struct obj_section *section,
255 int warn_if_readin);
256
257 /* Call a callback for every symbol defined in OBJFILE. FUN is the
258 callback. It is passed the symbol's natural name, and the DATA
259 passed to this function. */
260 void (*map_symbol_names) (struct objfile *objfile,
261 void (*fun) (const char *, void *),
262 void *data);
263
264 /* Call a callback for every file defined in OBJFILE. FUN is the
265 callback. It is passed the file's name, the file's full name,
266 and the DATA passed to this function. */
267 void (*map_symbol_filenames) (struct objfile *objfile,
268 void (*fun) (const char *, const char *,
269 void *),
270 void *data);
271 };
272
273 /* Structure to keep track of symbol reading functions for various
274 object file types. */
275
276 struct sym_fns
277 {
278
279 /* BFD flavour that we handle, or (as a special kludge, see
280 xcoffread.c, (enum bfd_flavour)-1 for xcoff). */
281
282 enum bfd_flavour sym_flavour;
283
284 /* Initializes anything that is global to the entire symbol table.
285 It is called during symbol_file_add, when we begin debugging an
286 entirely new program. */
287
288 void (*sym_new_init) (struct objfile *);
289
290 /* Reads any initial information from a symbol file, and initializes
291 the struct sym_fns SF in preparation for sym_read(). It is
292 called every time we read a symbol file for any reason. */
293
294 void (*sym_init) (struct objfile *);
295
296 /* sym_read (objfile, symfile_flags) Reads a symbol file into a psymtab
297 (or possibly a symtab). OBJFILE is the objfile struct for the
298 file we are reading. SYMFILE_FLAGS are the flags passed to
299 symbol_file_add & co. */
300
301 void (*sym_read) (struct objfile *, int);
302
303 /* Called when we are finished with an objfile. Should do all
304 cleanup that is specific to the object file format for the
305 particular objfile. */
306
307 void (*sym_finish) (struct objfile *);
308
309 /* This function produces a file-dependent section_offsets
310 structure, allocated in the objfile's storage, and based on the
311 parameter. The parameter is currently a CORE_ADDR (FIXME!) for
312 backward compatibility with the higher levels of GDB. It should
313 probably be changed to a string, where NULL means the default,
314 and others are parsed in a file dependent way. */
315
316 void (*sym_offsets) (struct objfile *, struct section_addr_info *);
317
318 /* This function produces a format-independent description of
319 the segments of ABFD. Each segment is a unit of the file
320 which may be relocated independently. */
321
322 struct symfile_segment_data *(*sym_segments) (bfd *abfd);
323
324 /* This function should read the linetable from the objfile when
325 the line table cannot be read while processing the debugging
326 information. */
327
328 void (*sym_read_linetable) (void);
329
330 /* Relocate the contents of a debug section SECTP. The
331 contents are stored in BUF if it is non-NULL, or returned in a
332 malloc'd buffer otherwise. */
333
334 bfd_byte *(*sym_relocate) (struct objfile *, asection *sectp, bfd_byte *buf);
335
336 /* The "quick" (aka partial) symbol functions for this symbol
337 reader. */
338 const struct quick_symbol_functions *qf;
339
340 /* Finds the next struct sym_fns. They are allocated and
341 initialized in whatever module implements the functions pointed
342 to; an initializer calls add_symtab_fns to add them to the global
343 chain. */
344
345 struct sym_fns *next;
346
347 };
348
349 extern struct section_addr_info *
350 build_section_addr_info_from_objfile (const struct objfile *objfile);
351
352 extern void relative_addr_info_to_section_offsets
353 (struct section_offsets *section_offsets, int num_sections,
354 struct section_addr_info *addrs);
355
356 extern void addr_info_make_relative (struct section_addr_info *addrs,
357 bfd *abfd);
358
359 /* The default version of sym_fns.sym_offsets for readers that don't
360 do anything special. */
361
362 extern void default_symfile_offsets (struct objfile *objfile,
363 struct section_addr_info *);
364
365 /* The default version of sym_fns.sym_segments for readers that don't
366 do anything special. */
367
368 extern struct symfile_segment_data *default_symfile_segments (bfd *abfd);
369
370 /* The default version of sym_fns.sym_relocate for readers that don't
371 do anything special. */
372
373 extern bfd_byte *default_symfile_relocate (struct objfile *objfile,
374 asection *sectp, bfd_byte *buf);
375
376 extern void extend_psymbol_list (struct psymbol_allocation_list *,
377 struct objfile *);
378
379 /* Add any kind of symbol to a psymbol_allocation_list. */
380
381 /* #include "demangle.h" */
382
383 extern const
384 struct partial_symbol *add_psymbol_to_list (char *, int, int, domain_enum,
385 enum address_class,
386 struct psymbol_allocation_list *,
387 long, CORE_ADDR,
388 enum language, struct objfile *);
389
390 extern void init_psymbol_list (struct objfile *, int);
391
392 extern struct symtab *allocate_symtab (char *, struct objfile *);
393
394 extern void add_symtab_fns (struct sym_fns *);
395
396 /* This enum encodes bit-flags passed as ADD_FLAGS parameter to
397 syms_from_objfile, symbol_file_add, etc. */
398
399 enum symfile_add_flags
400 {
401 /* Be chatty about what you are doing. */
402 SYMFILE_VERBOSE = 1 << 1,
403
404 /* This is the main symbol file (as opposed to symbol file for dynamically
405 loaded code). */
406 SYMFILE_MAINLINE = 1 << 2,
407
408 /* Do not call breakpoint_re_set when adding this symbol file. */
409 SYMFILE_DEFER_BP_RESET = 1 << 3
410 };
411
412 extern void syms_from_objfile (struct objfile *,
413 struct section_addr_info *,
414 struct section_offsets *, int, int);
415
416 extern void new_symfile_objfile (struct objfile *, int);
417
418 extern struct objfile *symbol_file_add (char *, int,
419 struct section_addr_info *, int);
420
421 extern struct objfile *symbol_file_add_from_bfd (bfd *, int,
422 struct section_addr_info *,
423 int);
424
425 extern void symbol_file_add_separate (bfd *, int, struct objfile *);
426
427 extern char *find_separate_debug_file_by_debuglink (struct objfile *);
428
429 /* Create a new section_addr_info, with room for NUM_SECTIONS. */
430
431 extern struct section_addr_info *alloc_section_addr_info (size_t
432 num_sections);
433
434 /* Build (allocate and populate) a section_addr_info struct from an
435 existing section table. */
436
437 extern struct section_addr_info
438 *build_section_addr_info_from_section_table (const struct target_section
439 *start,
440 const struct target_section
441 *end);
442
443 /* Free all memory allocated by
444 build_section_addr_info_from_section_table. */
445
446 extern void free_section_addr_info (struct section_addr_info *);
447
448
449 extern struct partial_symtab *start_psymtab_common (struct objfile *,
450 struct section_offsets *,
451 const char *, CORE_ADDR,
452 struct partial_symbol **,
453 struct partial_symbol **);
454
455 /* Make a copy of the string at PTR with SIZE characters in the symbol
456 obstack (and add a null character at the end in the copy). Returns
457 the address of the copy. */
458
459 extern char *obsavestring (const char *, int, struct obstack *);
460
461 /* Concatenate strings S1, S2 and S3; return the new string. Space is
462 found in the OBSTACKP */
463
464 extern char *obconcat (struct obstack *obstackp, const char *, const char *,
465 const char *);
466
467 /* Variables */
468
469 /* If non-zero, shared library symbols will be added automatically
470 when the inferior is created, new libraries are loaded, or when
471 attaching to the inferior. This is almost always what users will
472 want to have happen; but for very large programs, the startup time
473 will be excessive, and so if this is a problem, the user can clear
474 this flag and then add the shared library symbols as needed. Note
475 that there is a potential for confusion, since if the shared
476 library symbols are not loaded, commands like "info fun" will *not*
477 report all the functions that are actually present. */
478
479 extern int auto_solib_add;
480
481 /* For systems that support it, a threshold size in megabytes. If
482 automatically adding a new library's symbol table to those already
483 known to the debugger would cause the total shared library symbol
484 size to exceed this threshhold, then the shlib's symbols are not
485 added. The threshold is ignored if the user explicitly asks for a
486 shlib to be added, such as when using the "sharedlibrary" command. */
487
488 extern int auto_solib_limit;
489
490 /* From symfile.c */
491
492 extern void set_initial_language (void);
493
494 extern struct partial_symtab *allocate_psymtab (const char *,
495 struct objfile *);
496
497 extern void discard_psymtab (struct partial_symtab *);
498
499 extern void find_lowest_section (bfd *, asection *, void *);
500
501 extern bfd *symfile_bfd_open (char *);
502
503 extern bfd *bfd_open_maybe_remote (const char *);
504
505 extern int get_section_index (struct objfile *, char *);
506
507 /* Utility functions for overlay sections: */
508 extern enum overlay_debugging_state
509 {
510 ovly_off,
511 ovly_on,
512 ovly_auto
513 } overlay_debugging;
514 extern int overlay_cache_invalid;
515
516 /* Return the "mapped" overlay section containing the PC. */
517 extern struct obj_section *find_pc_mapped_section (CORE_ADDR);
518
519 /* Return any overlay section containing the PC (even in its LMA
520 region). */
521 extern struct obj_section *find_pc_overlay (CORE_ADDR);
522
523 /* Return true if the section is an overlay. */
524 extern int section_is_overlay (struct obj_section *);
525
526 /* Return true if the overlay section is currently "mapped". */
527 extern int section_is_mapped (struct obj_section *);
528
529 /* Return true if pc belongs to section's VMA. */
530 extern CORE_ADDR pc_in_mapped_range (CORE_ADDR, struct obj_section *);
531
532 /* Return true if pc belongs to section's LMA. */
533 extern CORE_ADDR pc_in_unmapped_range (CORE_ADDR, struct obj_section *);
534
535 /* Map an address from a section's LMA to its VMA. */
536 extern CORE_ADDR overlay_mapped_address (CORE_ADDR, struct obj_section *);
537
538 /* Map an address from a section's VMA to its LMA. */
539 extern CORE_ADDR overlay_unmapped_address (CORE_ADDR, struct obj_section *);
540
541 /* Convert an address in an overlay section (force into VMA range). */
542 extern CORE_ADDR symbol_overlayed_address (CORE_ADDR, struct obj_section *);
543
544 /* Load symbols from a file. */
545 extern void symbol_file_add_main (char *args, int from_tty);
546
547 /* Clear GDB symbol tables. */
548 extern void symbol_file_clear (int from_tty);
549
550 /* Default overlay update function. */
551 extern void simple_overlay_update (struct obj_section *);
552
553 extern bfd_byte *symfile_relocate_debug_section (struct objfile *, asection *,
554 bfd_byte *);
555
556 extern int symfile_map_offsets_to_segments (bfd *,
557 struct symfile_segment_data *,
558 struct section_offsets *,
559 int, const CORE_ADDR *);
560 struct symfile_segment_data *get_symfile_segment_data (bfd *abfd);
561 void free_symfile_segment_data (struct symfile_segment_data *data);
562
563 extern struct cleanup *increment_reading_symtab (void);
564
565 /* From dwarf2read.c */
566
567 extern int dwarf2_has_info (struct objfile *);
568
569 extern void dwarf2_build_psymtabs (struct objfile *);
570 extern void dwarf2_build_frame_info (struct objfile *);
571
572 void dwarf2_free_objfile (struct objfile *);
573
574 /* From mdebugread.c */
575
576 /* Hack to force structures to exist before use in parameter list. */
577 struct ecoff_debug_hack
578 {
579 struct ecoff_debug_swap *a;
580 struct ecoff_debug_info *b;
581 };
582
583 extern void mdebug_build_psymtabs (struct objfile *,
584 const struct ecoff_debug_swap *,
585 struct ecoff_debug_info *);
586
587 extern void elfmdebug_build_psymtabs (struct objfile *,
588 const struct ecoff_debug_swap *,
589 asection *);
590
591 #endif /* !defined(SYMFILE_H) */
This page took 0.143214 seconds and 4 git commands to generate.