2 @setfilename gdbint.info
8 * Gdb-Internals: (gdbint). The GNU debugger's internals.
14 This file documents the internals of the GNU debugger GDB.
16 Copyright 1990, 1991, 1992 Free Software Foundation, Inc.
17 Contributed by Cygnus Support. Written by John Gilmore.
19 Permission is granted to make and distribute verbatim copies of
20 this manual provided the copyright notice and this permission notice
21 are preserved on all copies.
24 Permission is granted to process this file through Tex and print the
25 results, provided the printed document carries copying permission
26 notice identical to this one except for the removal of this paragraph
27 (this paragraph not being relevant to the printed manual).
30 Permission is granted to copy or distribute modified versions of this
31 manual under the terms of the GPL (for which purpose this text may be
32 regarded as a program in the language TeX).
35 @setchapternewpage off
36 @settitle GDB Internals
38 @title{Working in GDB}
39 @subtitle{A guide to the internals of the GNU debugger}
41 @author Cygnus Support
44 \def\$#1${{#1}} % Kluge: collect RCS revision info without $...$
45 \xdef\manvers{\$Revision$} % For use in headers, footers too
47 \hfill Cygnus Support\par
49 \hfill \TeX{}info \texinfoversion\par
53 @vskip 0pt plus 1filll
54 Copyright @copyright{} 1990, 1991, 1992 Free Software Foundation, Inc.
56 Permission is granted to make and distribute verbatim copies of
57 this manual provided the copyright notice and this permission notice
58 are preserved on all copies.
64 This documents the internals of the GNU debugger, GDB. It is a
65 collection of miscellaneous information with little form at this point.
66 Mostly, it is a repository into which you can put information about
67 GDB as you discover it (or as you design changes to GDB).
70 * README:: The README File
71 * New Architectures:: Defining a New Host or Target Architecture
72 * Config:: Adding a New Configuration
73 * Host:: Adding a New Host
74 * Target:: Adding a New Target
75 * Languages:: Defining New Source Languages
76 * Releases:: Configuring GDB for Release
77 * Partial Symbol Tables:: How GDB reads symbols quickly at startup
78 * BFD support for GDB:: How BFD and GDB interface
79 * Symbol Reading:: Defining New Symbol Readers
81 * Wrapping:: Wrapping Output Lines
82 * Frames:: Keeping track of function calls
83 * Coding Style:: Strunk and White for GDB maintainers
84 * Host Conditionals:: What features exist in the host
85 * Target Conditionals:: What features exist in the target
86 * Native Conditionals:: Conditionals for when host and target are same
87 * Obsolete Conditionals:: Conditionals that don't exist any more
92 @chapter The @file{README} File
94 Check the @file{README} file, it often has useful information that does not
95 appear anywhere else in the directory.
98 @node New Architectures
99 @chapter Defining a New Host or Target Architecture
101 When building support for a new host and/or target, much of the work you
102 need to do is handled by specifying configuration files;
103 @pxref{Config,,Adding a New Configuration}. Further work can be
104 divided into ``host-dependent'' (@pxref{Host,,Adding a New Host}) and
105 ``target-dependent'' (@pxref{Target,,Adding a New Target}). The
106 following discussion is meant to explain the difference between hosts
109 @heading What is considered ``host-dependent'' versus ``target-dependent''?
111 @dfn{Host} refers to attributes of the system where GDB runs.
112 @dfn{Target} refers to the system where the program being debugged
113 executes. In most cases they are the same machine; unfortunately, that
114 means you must add @emph{both} host and target support for new machines
117 The @file{config/mh-*}, @file{xm-*.h} and @file{*-xdep.c} files are for
118 host support. Similarly, the @file{config/mt-*}, @file{tm-*.h} and
119 @file{*-tdep.c} files are for target support. The question is, what
120 features or aspects of a debugging or cross-debugging environment are
121 considered to be ``host'' support?
123 Defines and include files needed to build on the host are host support.
124 Examples are tty support, system defined types, host byte order, host
127 Unix child process support is considered an aspect of the host. Since
128 when you fork on the host you are still on the host, the various macros
129 needed for finding the registers in the upage, running @code{ptrace}, and such
130 are all in the host-dependent files.
132 @c FIXME so what kinds of things are target support?
134 This is still somewhat of a grey area; I (John Gilmore) didn't do the
135 @file{xm-*} and @file{tm-*} split for gdb (it was done by Jim Kingdon)
136 so I have had to figure out the grounds on which it was split, and make
137 my own choices as I evolve it. I have moved many things out of the xdep
138 files actually, partly as a result of BFD and partly by removing
143 @chapter Adding a New Configuration
145 Most of the work in making GDB compile on a new machine is in specifying
146 the configuration of the machine. This is done in a dizzying variety of
147 header files and configuration scripts, which we hope to make more
148 sensible soon. Let's say your new host is called an @var{xxx} (e.g.
149 @samp{sun4}), and its full three-part configuration name is
150 @code{@var{xarch}-@var{xvend}-@var{xos}} (e.g. @samp{sparc-sun-sunos4}). In
153 In the top level directory, edit @file{config.sub} and add @var{xarch},
154 @var{xvend}, and @var{xos} to the lists of supported architectures,
155 vendors, and operating systems near the bottom of the file. Also, add
156 @var{xxx} as an alias that maps to
157 @code{@var{xarch}-@var{xvend}-@var{xos}}. You can test your changes by
161 ./config.sub @var{xxx}
166 ./config.sub @code{@var{xarch}-@var{xvend}-@var{xos}}
169 which should both respond with @code{@var{xarch}-@var{xvend}-@var{xos}}
170 and no error messages.
172 Now, go to the @file{bfd} directory and
173 create a new file @file{bfd/hosts/h-@var{xxx}.h}. Examine the
174 other @file{h-*.h} files as templates, and create one that brings in the
175 right include files for your system, and defines any host-specific
176 macros needed by GDB.
178 Then edit @file{bfd/configure.in}. Add shell script code to recognize your
179 @code{@var{xarch}-@var{xvend}-@var{xos}} configuration, and set
180 @code{my_host} to @var{xxx} when you recognize it. This will cause your
181 file @file{h-@var{xxx}.h} to be linked to @file{sysdep.h} at configuration
184 Also, if this host requires any changes to the Makefile, create a file
185 @file{bfd/config/mh-@var{xxx}}, which includes the required lines.
187 (If you have the binary utilities and/or GNU ld in the same tree,
188 you'll also have to edit @file{binutils/configure.in} or
189 @file{ld/configure.in} to match what you've done in the @file{bfd}
192 It's possible that the @file{libiberty} and @file{readline} directories
193 won't need any changes for your configuration, but if they do, you can
194 change the @file{configure.in} file there to recognize your system and
195 map to an @file{mh-@var{xxx}} file. Then add @file{mh-@var{xxx}}
196 to the @file{config/} subdirectory, to set any makefile variables you
197 need. The only current options in there are things like @samp{-DSYSV}.
199 Aha! Now to configure GDB itself! Edit
200 @file{gdb/configure.in} to recognize your system and set @code{gdb_host}
201 to @var{xxx}, and (unless your desired target is already available) also
202 set @code{gdb_target} to something appropriate (for instance,
203 @var{xxx}). To handle new hosts, modify the segment after the comment
204 @samp{# per-host}; to handle new targets, modify after @samp{#
206 @c Would it be simpler to just use different per-host and per-target
207 @c *scripts*, and call them from {configure} ?
209 Finally, you'll need to specify and define GDB's host- and
210 target-dependent @file{.h} and @file{.c} files used for your
211 configuration; the next two chapters discuss those.
215 @chapter Adding a New Host
217 Once you have specified a new configuration for your host
218 (@pxref{Config,,Adding a New Configuration}), there are two remaining
219 pieces to making GDB work on a new machine. First, you have to make it
220 host on the new machine (compile there, handle that machine's terminals
221 properly, etc). If you will be cross-debugging to some other kind of
222 system that's already supported, you are done.
224 If you want to use GDB to debug programs that run on the new machine,
225 you have to get it to understand the machine's object files, symbol
226 files, and interfaces to processes. @pxref{Target,,Adding a New Target}
228 Several files control GDB's configuration for host systems:
231 @item gdb/config/mh-@var{xxx}
232 Specifies Makefile fragments needed when hosting on machine @var{xxx}.
233 In particular, this lists the required machine-dependent object files,
234 by defining @samp{XDEPFILES=@dots{}}. Also
235 specifies the header file which describes host @var{xxx}, by defining
236 @samp{XM_FILE= xm-@var{xxx}.h}. You can also define @samp{CC},
237 @samp{REGEX} and @samp{REGEX1}, @samp{SYSV_DEFINE}, @samp{XM_CFLAGS},
238 @samp{XM_ADD_FILES}, @samp{XM_CLIBS}, @samp{XM_CDEPS},
239 etc.; see @file{Makefile.in}.
241 @item gdb/xm-@var{xxx}.h
242 (@file{xm.h} is a link to this file, created by configure).
243 Contains C macro definitions describing the host system environment,
244 such as byte order, host C compiler and library, ptrace support,
245 and core file structure. Crib from existing @file{xm-*.h} files
248 @item gdb/@var{xxx}-xdep.c
249 Contains any miscellaneous C code required for this machine
250 as a host. On some machines it doesn't exist at all.
253 There are some ``generic'' versions of routines that can be used by
254 various host systems. These can be customized in various ways by macros
255 defined in your @file{xm-@var{xxx}.h} file. If these routines work for
256 the @var{xxx} host, you can just include the generic file's name (with
257 @samp{.o}, not @samp{.c}) in @code{XDEPFILES}.
259 Otherwise, if your machine needs custom support routines, you will need
260 to write routines that perform the same functions as the generic file.
261 Put them into @code{@var{xxx}-xdep.c}, and put @code{@var{xxx}-xdep.o}
262 into @code{XDEPFILES}.
264 @subheading Generic Host Support Files
269 This is the low level interface to inferior processes for systems
270 using the Unix @code{ptrace} call in a vanilla way.
272 @item coredep.c::fetch_core_registers()
273 Support for reading registers out of a core file. This routine calls
274 @code{register_addr()}, see below.
275 Now that BFD is used to read core files, virtually all machines should
276 use @code{coredep.c}, and should just provide @code{fetch_core_registers} in
277 @code{@var{xxx}-xdep.c} (or @code{REGISTER_U_ADDR} in @code{xm-@var{xxx}.h}).
279 @item coredep.c::register_addr()
280 If your @code{xm-@var{xxx}.h} file defines the macro
281 @code{REGISTER_U_ADDR(addr, blockend, regno)}, it should be defined to
282 set @code{addr} to the offset within the @samp{user}
283 struct of GDB register number @code{regno}. @code{blockend} is the
284 offset within the ``upage'' of @code{u.u_ar0}.
285 If @code{REGISTER_U_ADDR} is defined,
286 @file{coredep.c} will define the @code{register_addr()} function and use
287 the macro in it. If you do not define @code{REGISTER_U_ADDR}, but you
288 are using the standard @code{fetch_core_registers()}, you will need to
289 define your own version of @code{register_addr()}, put it into your
290 @code{@var{xxx}-xdep.c} file, and be sure @code{@var{xxx}-xdep.o} is in
291 the @code{XDEPFILES} list. If you have your own
292 @code{fetch_core_registers()}, you may not need a separate
293 @code{register_addr()}. Many custom @code{fetch_core_registers()}
294 implementations simply locate the registers themselves.@refill
297 Object files needed when the target system is an @var{xxx} are listed
298 in the file @file{config/mt-@var{xxx}}, in the makefile macro
299 @samp{TDEPFILES = }@dots{}. The header file that defines the target
300 system should be called @file{tm-@var{xxx}.h}, and should be specified
301 as the value of @samp{TM_FILE} in @file{config/mt-@var{xxx}}. You can
302 also define @samp{TM_CFLAGS}, @samp{TM_CLIBS}, and @samp{TM_CDEPS} in
303 there; see @file{Makefile.in}.
305 Now, you are now ready to try configuring GDB to compile for your system.
306 From the top level (above @file{bfd}, @file{gdb}, etc), do:
309 ./configure @var{xxx} +target=vxworks960
312 This will configure your system to cross-compile for VxWorks on
313 the Intel 960, which is probably not what you really want, but it's
314 a test case that works at this stage. (You haven't set up to be
315 able to debug programs that run @emph{on} @var{xxx} yet.)
317 If this succeeds, you can try building it all with:
323 Good luck! Comments and suggestions about this section are particularly
324 welcome; send them to @samp{bug-gdb@@prep.ai.mit.edu}.
326 When hosting GDB on a new operating system, to make it possible to debug
327 core files, you will need to either write specific code for parsing your
328 OS's core files, or customize @file{bfd/trad-core.c}. First, use
329 whatever @code{#include} files your machine uses to define the struct of
330 registers that is accessible (possibly in the u-area) in a core file
331 (rather than @file{machine/reg.h}), and an include file that defines whatever
332 header exists on a core file (e.g. the u-area or a @samp{struct core}). Then
333 modify @code{trad_unix_core_file_p()} to use these values to set up the
334 section information for the data segment, stack segment, any other
335 segments in the core file (perhaps shared library contents or control
336 information), ``registers'' segment, and if there are two discontiguous
337 sets of registers (e.g. integer and float), the ``reg2'' segment. This
338 section information basically delimits areas in the core file in a
339 standard way, which the section-reading routines in BFD know how to seek
342 Then back in GDB, you need a matching routine called
343 @code{fetch_core_registers()}. If you can use the generic one, it's in
344 @file{core-dep.c}; if not, it's in your @file{@var{xxx}-xdep.c} file.
345 It will be passed a char pointer to the entire ``registers'' segment,
346 its length, and a zero; or a char pointer to the entire ``regs2''
347 segment, its length, and a 2. The routine should suck out the supplied
348 register values and install them into GDB's ``registers'' array.
349 (@xref{New Architectures,,Defining a New Host or Target Architecture},
350 for more info about this.)
354 @chapter Adding a New Target
356 For a new target called @var{ttt}, first specify the configuration as
357 described in @ref{Config,,Adding a New Configuration}. If your new
358 target is the same as your new host, you've probably already done that.
360 A variety of files specify attributes of the GDB target environment:
363 @item gdb/config/mt-@var{ttt}
364 Contains a Makefile fragment specific to this target.
365 Specifies what object files are needed for target @var{ttt}, by
366 defining @samp{TDEPFILES=@dots{}}.
367 Also specifies the header file which describes @var{ttt}, by defining
368 @samp{TM_FILE= tm-@var{ttt}.h}. You can also define @samp{TM_CFLAGS},
369 and other Makefile variables here; see @file{Makefile.in}.
371 @item gdb/tm-@var{ttt}.h
372 (@file{tm.h} is a link to this file, created by configure).
373 Contains macro definitions about the target machine's
374 registers, stack frame format and instructions.
375 Crib from existing @file{tm-*.h} files when building a new one.
377 @item gdb/@var{ttt}-tdep.c
378 Contains any miscellaneous code required for this target machine.
379 On some machines it doesn't exist at all. Sometimes the macros
380 in @file{tm-@var{ttt}.h} become very complicated, so they are
381 implemented as functions here instead, and the macro is simply
382 defined to call the function.
385 Defines functions for accessing files that are
386 executable on the target system. These functions open and examine an
387 exec file, extract data from one, write data to one, print information
388 about one, etc. Now that executable files are handled with BFD, every
389 target should be able to use the generic exec.c rather than its
392 @item gdb/@var{arch}-pinsn.c
393 Prints (disassembles) the target machine's instructions.
394 This file is usually shared with other target machines which use the
395 same processor, which is why it is @file{@var{arch}-pinsn.c} rather
396 than @file{@var{ttt}-pinsn.c}.
398 @item gdb/@var{arch}-opcode.h
399 Contains some large initialized
400 data structures describing the target machine's instructions.
401 This is a bit strange for a @file{.h} file, but it's OK since
402 it is only included in one place. @file{@var{arch}-opcode.h} is shared
403 between the debugger and the assembler, if the GNU assembler has been
404 ported to the target machine.
406 @item gdb/tm-@var{arch}.h
407 This often exists to describe the basic layout of the target machine's
408 processor chip (registers, stack, etc).
409 If used, it is included by @file{tm-@var{xxx}.h}. It can
410 be shared among many targets that use the same processor.
412 @item gdb/@var{arch}-tdep.c
413 Similarly, there are often common subroutines that are shared by all
414 target machines that use this particular architecture.
417 When adding support for a new target machine, there are various areas
418 of support that might need change, or might be OK.
420 If you are using an existing object file format (a.out or COFF),
421 there is probably little to be done. See @file{bfd/doc/bfd.texinfo}
422 for more information on writing new a.out or COFF versions.
424 If you need to add a new object file format, you are beyond the scope
425 of this document right now. Look at the structure of the a.out
426 and COFF support, build a transfer vector (@code{xvec}) for your new format,
427 and start populating it with routines. Add it to the list in
428 @file{bfd/targets.c}.
430 If you are adding a new operating system for an existing CPU chip, add a
431 @file{tm-@var{xos}.h} file that describes the operating system
432 facilities that are unusual (extra symbol table info; the breakpoint
433 instruction needed; etc). Then write a
434 @file{tm-@var{xarch}-@var{xos}.h} that just @code{#include}s
435 @file{tm-@var{xarch}.h} and @file{tm-@var{xos}.h}. (Now that we have
436 three-part configuration names, this will probably get revised to
437 separate the @var{xos} configuration from the @var{xarch}
442 @chapter Adding a Source Language to GDB
444 To add other languages to GDB's expression parser, follow the following steps:
447 @item Create the expression parser.
449 This should reside in a file @file{@var{lang}-exp.y}. Routines for building
450 parsed expressions into a @samp{union exp_element} list are in @file{parse.c}.
452 Since we can't depend upon everyone having Bison, and YACC produces
453 parsers that define a bunch of global names, the following lines
454 @emph{must} be included at the top of the YACC parser, to prevent
455 the various parsers from defining the same global names:
458 #define yyparse @var{lang}_parse
459 #define yylex @var{lang}_lex
460 #define yyerror @var{lang}_error
461 #define yylval @var{lang}_lval
462 #define yychar @var{lang}_char
463 #define yydebug @var{lang}_debug
464 #define yypact @var{lang}_pact
465 #define yyr1 @var{lang}_r1
466 #define yyr2 @var{lang}_r2
467 #define yydef @var{lang}_def
468 #define yychk @var{lang}_chk
469 #define yypgo @var{lang}_pgo
470 #define yyact @var{lang}_act
471 #define yyexca @var{lang}_exca
472 #define yyerrflag @var{lang}_errflag
473 #define yynerrs @var{lang}_nerrs
476 At the bottom of your parser, define a @code{struct language_defn} and
477 initialize it with the right values for your language. Define an
478 @code{initialize_@var{lang}} routine and have it call
479 @samp{add_language(@var{lang}_language_defn)} to tell the rest of GDB
480 that your language exists. You'll need some other supporting variables
481 and functions, which will be used via pointers from your
482 @code{@var{lang}_language_defn}. See the declaration of @code{struct
483 language_defn} in @file{language.h}, and the other @file{*-exp.y} files,
484 for more information.
486 @item Add any evaluation routines, if necessary
488 If you need new opcodes (that represent the operations of the language),
489 add them to the enumerated type in @file{expression.h}. Add support
490 code for these operations in @code{eval.c:evaluate_subexp()}. Add cases
491 for new opcodes in two functions from @file{parse.c}:
492 @code{prefixify_subexp()} and @code{length_of_subexp()}. These compute
493 the number of @code{exp_element}s that a given operation takes up.
495 @item Update some existing code
497 Add an enumerated identifier for your language to the enumerated type
498 @code{enum language} in @file{defs.h}.
500 Update the routines in @file{language.c} so your language is included. These
501 routines include type predicates and such, which (in some cases) are
502 language dependent. If your language does not appear in the switch
503 statement, an error is reported.
505 Also included in @file{language.c} is the code that updates the variable
506 @code{current_language}, and the routines that translate the
507 @code{language_@var{lang}} enumerated identifier into a printable
510 Update the function @code{_initialize_language} to include your language. This
511 function picks the default language upon startup, so is dependent upon
512 which languages that GDB is built for.
514 Update @code{allocate_symtab} in @file{symfile.c} and/or symbol-reading
515 code so that the language of each symtab (source file) is set properly.
516 This is used to determine the language to use at each stack frame level.
517 Currently, the language is set based upon the extension of the source
518 file. If the language can be better inferred from the symbol
519 information, please set the language of the symtab in the symbol-reading
522 Add helper code to @code{expprint.c:print_subexp()} to handle any new
523 expression opcodes you have added to @file{expression.h}. Also, add the
524 printed representations of your operators to @code{op_print_tab}.
526 @item Add a place of call
528 Add a call to @code{@var{lang}_parse()} and @code{@var{lang}_error} in
529 @code{parse.c:parse_exp_1()}.
531 @item Use macros to trim code
533 The user has the option of building GDB for some or all of the
534 languages. If the user decides to build GDB for the language
535 @var{lang}, then every file dependent on @file{language.h} will have the
536 macro @code{_LANG_@var{lang}} defined in it. Use @code{#ifdef}s to
537 leave out large routines that the user won't need if he or she is not
540 Note that you do not need to do this in your YACC parser, since if GDB
541 is not build for @var{lang}, then @file{@var{lang}-exp.tab.o} (the
542 compiled form of your parser) is not linked into GDB at all.
544 See the file @file{configure.in} for how GDB is configured for different
547 @item Edit @file{Makefile.in}
549 Add dependencies in @file{Makefile.in}. Make sure you update the macro
550 variables such as @code{HFILES} and @code{OBJS}, otherwise your code may
551 not get linked in, or, worse yet, it may not get @code{tar}red into the
557 @chapter Configuring GDB for Release
559 From the top level directory (containing @file{gdb}, @file{bfd},
560 @file{libiberty}, and so on):
562 make -f Makefile.in gdb.tar.Z
565 This will properly configure, clean, rebuild any files that are
566 distributed pre-built (e.g. @file{c-exp.tab.c} or @file{refcard.ps}),
567 and will then make a tarfile. (If the top level directory has already
568 beenn configured, you can just do @code{make gdb.tar.Z} instead.)
570 This procedure requires:
573 @item @code{makeinfo} (texinfo2 level)
576 @item @code{yacc} or @code{bison}
579 @dots{} and the usual slew of utilities (@code{sed}, @code{tar}, etc.).
581 @subheading TEMPORARY RELEASE PROCEDURE FOR DOCUMENTATION
583 @file{gdb.texinfo} is currently marked up using the texinfo-2 macros,
584 which are not yet a default for anything (but we have to start using
587 For making paper, the only thing this implies is the right generation of
588 @file{texinfo.tex} needs to be included in the distribution.
590 For making info files, however, rather than duplicating the texinfo2
591 distribution, generate @file{gdb-all.texinfo} locally, and include the files
592 @file{gdb.info*} in the distribution. Note the plural; @code{makeinfo} will
593 split the document into one overall file and five or so included files.
596 @node Partial Symbol Tables
597 @chapter Partial Symbol Tables
599 GDB has three types of symbol tables.
602 @item full symbol tables (symtabs). These contain the main
603 information about symbols and addresses.
604 @item partial symbol tables (psymtabs). These contain enough
605 information to know when to read the corresponding
606 part of the full symbol table.
607 @item minimal symbol tables (msymtabs). These contain information
608 gleaned from non-debugging symbols.
611 This section describes partial symbol tables.
613 A psymtab is constructed by doing a very quick pass over an executable
614 file's debugging information. Small amounts of information are
615 extracted -- enough to identify which parts of the symbol table will
616 need to be re-read and fully digested later, when the user needs the
617 information. The speed of this pass causes GDB to start up very
618 quickly. Later, as the detailed rereading occurs, it occurs in small
619 pieces, at various times, and the delay therefrom is mostly invisible to
620 the user. (@xref{Symbol Reading}.)
622 The symbols that show up in a file's psymtab should be, roughly, those
623 visible to the debugger's user when the program is not running code from
624 that file. These include external symbols and types, static
625 symbols and types, and enum values declared at file scope.
627 The psymtab also contains the range of instruction addresses that the
628 full symbol table would represent.
630 The idea is that there are only two ways for the user (or much of
631 the code in the debugger) to reference a symbol:
636 (e.g. execution stops at some address which is inside a function
637 in this file). The address will be noticed to be in the
638 range of this psymtab, and the full symtab will be read in.
639 @code{find_pc_function}, @code{find_pc_line}, and other @code{find_pc_@dots{}}
640 functions handle this.
643 (e.g. the user asks to print a variable, or set a breakpoint on a
644 function). Global names and file-scope names will be found in the
645 psymtab, which will cause the symtab to be pulled in. Local names will
646 have to be qualified by a global name, or a file-scope name, in which
647 case we will have already read in the symtab as we evaluated the
648 qualifier. Or, a local symbol can be referenced when
649 we are "in" a local scope, in which case the first case applies.
650 @code{lookup_symbol} does most of the work here.
654 The only reason that psymtabs exist is to cause a symtab to be read in
655 at the right moment. Any symbol that can be elided from a psymtab,
656 while still causing that to happen, should not appear in it. Since
657 psymtabs don't have the idea of scope, you can't put local symbols in
658 them anyway. Psymtabs don't have the idea of the type of a symbol,
659 either, so types need not appear, unless they will be referenced by
662 It is a bug for GDB to behave one way when only a psymtab has been read,
663 and another way if the corresponding symtab has been read in. Such
664 bugs are typically caused by a psymtab that does not contain all the
665 visible symbols, or which has the wrong instruction address ranges.
667 The psymtab for a particular section of a symbol-file (objfile)
668 could be thrown away after the symtab has been read in. The symtab
669 should always be searched before the psymtab, so the psymtab will
670 never be used (in a bug-free environment). Currently,
671 psymtabs are allocated on an obstack, and all the psymbols themselves
672 are allocated in a pair of large arrays on an obstack, so there is
673 little to be gained by trying to free them unless you want to do a lot
676 @node BFD support for GDB
677 @chapter Binary File Descriptor Library Support for GDB
679 BFD provides support for GDB in several ways:
682 @item identifying executable and core files
683 BFD will identify a variety of file types, including a.out, coff, and
684 several variants thereof, as well as several kinds of core files.
686 @item access to sections of files
687 BFD parses the file headers to determine the names, virtual addresses,
688 sizes, and file locations of all the various named sections in files
689 (such as the text section or the data section). GDB simply calls
690 BFD to read or write section X at byte offset Y for length Z.
692 @item specialized core file support
693 BFD provides routines to determine the failing command name stored
694 in a core file, the signal with which the program failed, and whether
695 a core file matches (i.e. could be a core dump of) a particular executable
698 @item locating the symbol information
699 GDB uses an internal interface of BFD to determine where to find the
700 symbol information in an executable file or symbol-file. GDB itself
701 handles the reading of symbols, since BFD does not ``understand'' debug
702 symbols, but GDB uses BFD's cached information to find the symbols,
706 @c The interface for symbol reading is described in @ref{Symbol
707 @c Reading,,Symbol Reading}.
711 @chapter Symbol Reading
713 GDB reads symbols from "symbol files". The usual symbol file is the
714 file containing the program which gdb is debugging. GDB can be directed
715 to use a different file for symbols (with the ``symbol-file''
716 command), and it can also read more symbols via the ``add-file'' and ``load''
717 commands, or while reading symbols from shared libraries.
719 Symbol files are initially opened by @file{symfile.c} using the BFD
720 library. BFD identifies the type of the file by examining its header.
721 @code{symfile_init} then uses this identification to locate a
722 set of symbol-reading functions.
724 Symbol reading modules identify themselves to GDB by calling
725 @code{add_symtab_fns} during their module initialization. The argument
726 to @code{add_symtab_fns} is a @code{struct sym_fns} which contains
727 the name (or name prefix) of the symbol format, the length of the prefix,
728 and pointers to four functions. These functions are called at various
729 times to process symbol-files whose identification matches the specified
732 The functions supplied by each module are:
735 @item @var{xxx}_symfile_init(struct sym_fns *sf)
737 Called from @code{symbol_file_add} when we are about to read a new
738 symbol file. This function should clean up any internal state
739 (possibly resulting from half-read previous files, for example)
740 and prepare to read a new symbol file. Note that the symbol file
741 which we are reading might be a new "main" symbol file, or might
742 be a secondary symbol file whose symbols are being added to the
743 existing symbol table.
745 The argument to @code{@var{xxx}_symfile_init} is a newly allocated
746 @code{struct sym_fns} whose @code{bfd} field contains the BFD
747 for the new symbol file being read. Its @code{private} field
748 has been zeroed, and can be modified as desired. Typically,
749 a struct of private information will be @code{malloc}'d, and
750 a pointer to it will be placed in the @code{private} field.
752 There is no result from @code{@var{xxx}_symfile_init}, but it can call
753 @code{error} if it detects an unavoidable problem.
755 @item @var{xxx}_new_init()
757 Called from @code{symbol_file_add} when discarding existing symbols.
758 This function need only handle
759 the symbol-reading module's internal state; the symbol table data
760 structures visible to the rest of GDB will be discarded by
761 @code{symbol_file_add}. It has no arguments and no result.
762 It may be called after @code{@var{xxx}_symfile_init}, if a new symbol
763 table is being read, or may be called alone if all symbols are
764 simply being discarded.
766 @item @var{xxx}_symfile_read(struct sym_fns *sf, CORE_ADDR addr, int mainline)
768 Called from @code{symbol_file_add} to actually read the symbols from a
769 symbol-file into a set of psymtabs or symtabs.
771 @code{sf} points to the struct sym_fns originally passed to
772 @code{@var{xxx}_sym_init} for possible initialization. @code{addr} is the
773 offset between the file's specified start address and its true address
774 in memory. @code{mainline} is 1 if this is the main symbol table being
775 read, and 0 if a secondary symbol file (e.g. shared library or
776 dynamically loaded file) is being read.@refill
779 In addition, if a symbol-reading module creates psymtabs when
780 @var{xxx}_symfile_read is called, these psymtabs will contain a pointer to
781 a function @code{@var{xxx}_psymtab_to_symtab}, which can be called from
782 any point in the GDB symbol-handling code.
785 @item @var{xxx}_psymtab_to_symtab (struct partial_symtab *pst)
787 Called from @code{psymtab_to_symtab} (or the PSYMTAB_TO_SYMTAB
788 macro) if the psymtab has not already been read in and had its
789 @code{pst->symtab} pointer set. The argument is the psymtab
790 to be fleshed-out into a symtab. Upon return, pst->readin
791 should have been set to 1, and pst->symtab should contain a
792 pointer to the new corresponding symtab, or zero if there
793 were no symbols in that part of the symbol file.
800 Cleanups are a structured way to deal with things that need to be done
801 later. When your code does something (like @code{malloc} some memory, or open
802 a file) that needs to be undone later (e.g. free the memory or close
803 the file), it can make a cleanup. The cleanup will be done at some
804 future point: when the command is finished, when an error occurs, or
805 when your code decides it's time to do cleanups.
807 You can also discard cleanups, that is, throw them away without doing
808 what they say. This is only done if you ask that it be done.
813 @item @var{old_chain} = make_cleanup (@var{function}, @var{arg});
814 Make a cleanup which will cause @var{function} to be called with @var{arg}
815 (a @code{char *}) later. The result, @var{old_chain}, is a handle that can be
816 passed to @code{do_cleanups} or @code{discard_cleanups} later. Unless you are
817 going to call @code{do_cleanups} or @code{discard_cleanups} yourself,
818 you can ignore the result from @code{make_cleanup}.
821 @item do_cleanups (@var{old_chain});
822 Perform all cleanups done since @code{make_cleanup} returned @var{old_chain}.
826 old = make_cleanup (b, 0);
830 will call @code{b()} but will not call @code{a()}. The cleanup that calls @code{a()} will remain
831 in the cleanup chain, and will be done later unless otherwise discarded.@refill
833 @item discard_cleanups (@var{old_chain});
834 Same as @code{do_cleanups} except that it just removes the cleanups from the
835 chain and does not call the specified functions.
839 Some functions, e.g. @code{fputs_filtered()} or @code{error()}, specify that they
840 ``should not be called when cleanups are not in place''. This means
841 that any actions you need to reverse in the case of an error or
842 interruption must be on the cleanup chain before you call these functions,
843 since they might never return to your code (they @samp{longjmp} instead).
847 @chapter Wrapping Output Lines
849 Output that goes through @code{printf_filtered} or @code{fputs_filtered} or
850 @code{fputs_demangled} needs only to have calls to @code{wrap_here} added
851 in places that would be good breaking points. The utility routines
852 will take care of actually wrapping if the line width is exceeded.
854 The argument to @code{wrap_here} is an indentation string which is printed
855 @emph{only} if the line breaks there. This argument is saved away and used
856 later. It must remain valid until the next call to @code{wrap_here} or
857 until a newline has been printed through the @code{*_filtered} functions.
858 Don't pass in a local variable and then return!
860 It is usually best to call @code{wrap_here()} after printing a comma or space.
861 If you call it before printing a space, make sure that your indentation
862 properly accounts for the leading space that will print if the line wraps
865 Any function or set of functions that produce filtered output must finish
866 by printing a newline, to flush the wrap buffer, before switching to
867 unfiltered (``@code{printf}'') output. Symbol reading routines that print
868 warnings are a good example.
874 A frame is a construct that GDB uses to keep track of calling and called
879 in the machine description has no meaning to the machine-independent
880 part of GDB, except that it is used when setting up a new frame from
884 create_new_frame (read_register (FP_REGNUM), read_pc ()));
887 Other than that, all the meaning imparted to @code{FP_REGNUM} is imparted by
888 the machine-dependent code. So, @code{FP_REGNUM} can have any value that
889 is convenient for the code that creates new frames. (@code{create_new_frame}
890 calls @code{INIT_EXTRA_FRAME_INFO} if it is defined; that is where you should
891 use the @code{FP_REGNUM} value, if your frames are nonstandard.)
894 Given a GDB frame, determine the address of the calling function's
895 frame. This will be used to create a new GDB frame struct, and then
896 @code{INIT_EXTRA_FRAME_INFO} and @code{INIT_FRAME_PC} will be called for
901 @chapter Coding Style
903 GDB is generally written using the GNU coding standards, as described in
904 @file{standards.texi}, which you can get from the Free Software
905 Foundation. There are some additional considerations for GDB maintainers
906 that reflect the unique environment and style of GDB maintenance.
907 If you follow these guidelines, GDB will be more consistent and easier
910 GDB's policy on the use of prototypes is that prototypes are used
911 to @emph{declare} functions but never to @emph{define} them. Simple
912 macros are used in the declarations, so that a non-ANSI compiler can
913 compile GDB without trouble. The simple macro calls are used like
918 memory_remove_breakpoint PARAMS ((CORE_ADDR, char *));
921 Note the double parentheses around the parameter types. This allows
922 an arbitrary number of parameters to be described, without freaking
923 out the C preprocessor. When the function has no parameters, it
924 should be described like:
928 noprocess PARAMS ((void));
931 The @code{PARAMS} macro expands to its argument in ANSI C, or to a simple
932 @code{()} in traditional C.
934 All external functions should have a @code{PARAMS} declaration in a
935 header file that callers include. All static functions should have such
936 a declaration near the top of their source file.
938 We don't have a gcc option that will properly check that these rules
939 have been followed, but it's GDB policy, and we periodically check it
940 using the tools available (plus manual labor), and clean up any remnants.
942 @node Host Conditionals
943 @chapter Host Conditionals
945 When GDB is configured and compiled, various macros are defined or left
946 undefined, to control compilation based on the attributes of the host
947 system. These macros and their meanings are:
949 @emph{NOTE: For now, both host and target conditionals are here.
950 Eliminate target conditionals from this list as they are identified.}
955 @item BLOCK_ADDRESS_FUNCTION_RELATIVE
957 @item GDBINIT_FILENAME
961 @item MEM_FNS_DECLARED
965 @item PYRAMID_CONTROL_FRAME_DEBUGGING
967 @item SIGWINCH_HANDLER_BODY
985 @item ADDITIONAL_OPTIONS
987 @item ADDITIONAL_OPTION_CASES
989 @item ADDITIONAL_OPTION_HANDLER
991 @item ADDITIONAL_OPTION_HELP
993 @item ADDR_BITS_REMOVE
995 @item AIX_BUGGY_PTRACE_CONTINUE
997 @item ALIGN_STACK_ON_STARTUP
1009 @item BEFORE_MAIN_LOOP_HOOK
1011 @item BELIEVE_PCC_PROMOTION
1013 @item BELIEVE_PCC_PROMOTION_TYPE
1017 @item BITS_BIG_ENDIAN
1021 @item BLOCK_ADDRESS_ABSOLUTE
1027 @item BREAKPOINT_DEBUG
1029 @item BROKEN_LARGE_ALLOCA
1030 Avoid large @code{alloca}'s. For example, on sun's, Large alloca's fail
1031 because the attempt to increase the stack limit in main() fails because
1032 shared libraries are allocated just below the initial stack limit. The
1033 SunOS kernel will not allow the stack to grow into the area occupied by
1034 the shared libraries.
1039 @item CALL_DUMMY_LOCATION
1041 @item CALL_DUMMY_STACK_ADJUST
1043 @item CANNOT_FETCH_REGISTER
1045 @item CANNOT_STORE_REGISTER
1047 @item CFRONT_PRODUCER
1049 @item CHILD_PREPARE_TO_STORE
1051 @item CLEAR_DEFERRED_STORES
1055 @item COFF_ENCAPSULATE
1059 @item COFF_NO_LONG_FILE_NAMES
1061 @item CORE_NEEDS_RELOCATION
1065 @item CREATE_INFERIOR_HOOK
1075 @item DBX_PARM_SYMBOL_CLASS
1083 @item DECR_PC_AFTER_BREAK
1085 @item DEFAULT_PROMPT
1093 @item DISABLE_UNSETTABLE_BREAK
1095 @item DONT_USE_REMOTE
1097 @item DO_DEFERRED_STORES
1099 @item DO_REGISTERS_INFO
1101 @item END_OF_TEXT_DEFAULT
1105 @item EXTRACT_RETURN_VALUE
1107 @item EXTRACT_STRUCT_VALUE_ADDRESS
1109 @item EXTRA_FRAME_INFO
1111 @item EXTRA_SYMTAB_INFO
1113 @item FILES_INFO_HOOK
1127 @item FRAMELESS_FUNCTION_INVOCATION
1129 @item FRAME_ARGS_ADDRESS_CORRECT
1131 @item FRAME_CHAIN_COMBINE
1133 @item FRAME_CHAIN_VALID
1135 @item FRAME_CHAIN_VALID_ALTERNATE
1137 @item FRAME_FIND_SAVED_REGS
1139 @item FRAME_GET_BASEREG_VALUE
1141 @item FRAME_NUM_ARGS
1143 @item FRAME_SPECIFICATION_DYADIC
1145 @item FUNCTION_EPILOGUE_SIZE
1149 @item GCC2_COMPILED_FLAG_SYMBOL
1151 @item GCC_COMPILED_FLAG_SYMBOL
1153 @item GCC_MANGLE_BUG
1157 @item GET_SAVED_REGISTER
1159 @item GPLUS_PRODUCER
1170 In some cases, use the system call @code{mmap} for reading symbol
1171 tables. For some machines this allows for sharing and quick updates.
1172 @item HAVE_REGISTER_WINDOWS
1174 @item HAVE_SIGSETMASK
1178 @item HEADER_SEEK_FD
1182 @item HOST_BYTE_ORDER
1186 @item HPUX_VERSION_5
1194 @item IBM6000_TARGET
1202 @item INIT_EXTRA_FRAME_INFO
1204 @item INIT_EXTRA_SYMTAB_INFO
1218 @item IN_SOLIB_TRAMPOLINE
1222 @item IS_TRAPPED_INTERNALVAR
1226 @item KERNEL_DEBUGGING
1229 Define this to the address of the @code{u} structure (the ``user struct'',
1230 also known as the ``u-page'') in kernel virtual memory. GDB needs to know
1231 this so that it can subtract this address from absolute addresses in
1232 the upage, that are obtained via ptrace or from core files. On systems
1233 that don't need this value, set it to zero.
1234 @item KERNEL_U_ADDR_BSD
1235 Define this to cause GDB to determine the address of @code{u} at runtime,
1236 by using Berkeley-style @code{nlist} on the kernel's image in the root
1238 @item KERNEL_U_ADDR_HPUX
1239 Define this to cause GDB to determine the address of @code{u} at runtime,
1240 by using HP-style @code{nlist} on the kernel's image in the root
1256 @item LSEEK_NOT_LINEAR
1261 This macro is used as the argument to lseek (or, most commonly, bfd_seek).
1262 FIXME, it should be replaced by SEEK_SET instead, which is the POSIX equivalent.
1263 @item MACHKERNELDEBUG
1269 @item MAINTENANCE_CMDS
1271 @item MAINTENANCE_CMDS
1273 @item MALLOC_INCOMPATIBLE
1274 Define this if the system's prototype for @code{malloc} differs from the
1275 @sc{ANSI} definition.
1278 @item MMAP_BASE_ADDRESS
1279 When using HAVE_MMAP, the first mapping should go at this address.
1280 @item MMAP_INCREMENT
1281 when using HAVE_MMAP, this is the increment between mappings.
1286 @item NAMES_HAVE_UNDERSCORE
1290 @item NEED_POSIX_SETPGID
1292 @item NEED_TEXT_START_END
1306 @item NOTICE_SIGNAL_HANDLING_CHANGE
1308 @item NO_DEFINE_SYMBOL
1310 @item NO_HIF_SUPPORT
1312 @item NO_JOB_CONTROL
1314 @item NO_MALLOC_CHECK
1322 @item NO_SIGINTERRUPT
1324 @item NO_SINGLE_STEP
1332 @item NS32K_SVC_IMMED_OPERANDS
1334 @item NUMERIC_REG_NAMES
1342 @item ONE_PROCESS_WRITETEXT
1350 @item PCC_SOL_BROKEN
1352 @item PC_IN_CALL_DUMMY
1354 @item PC_LOAD_SEGMENT
1358 @item PRINT_RANDOM_SIGNAL
1360 @item PRINT_REGISTER_HOOK
1362 @item PRINT_TYPELESS_INTEGER
1364 @item PROCESS_LINENUMBER_HOOK
1366 @item PROLOGUE_FIRSTLINE_OVERLAP
1368 @item PSIGNAL_IN_SIGNAL_H
1372 @item PTRACE_ARG3_TYPE
1382 @item PUSH_ARGUMENTS
1384 @item PYRAMID_CONTROL_FRAME_DEBUGGING
1388 @item PYRAMID_PTRACE
1390 @item REGISTER_BYTES
1392 @item REGISTER_NAMES
1394 @item REG_STACK_SEGMENT
1396 @item REG_STRUCT_HAS_ADDR
1404 @item SDB_REG_TO_REGNUM
1412 @item SET_STACK_LIMIT_HUGE
1413 When defined, stack limits will be raised to their maximum. Use this
1414 if your host supports @code{setrlimit} and you have trouble with
1415 @code{stringtab} in @file{dbxread.c}.
1417 Also used in @file{fork-child.c} to return stack limits before child
1418 processes are forked.
1419 @item SHELL_COMMAND_CONCAT
1423 @item SHIFT_INST_REGS
1425 @item SIGN_EXTEND_CHAR
1427 @item SIGTRAP_STOP_AFTER_LOAD
1431 @item SKIP_PROLOGUE_FRAMELESS_P
1433 @item SKIP_TRAMPOLINE_CODE
1437 @item SOLIB_CREATE_INFERIOR_HOOK
1439 @item SOME_NAMES_HAVE_DOT
1443 @item STAB_REG_TO_REGNUM
1447 @item STACK_DIRECTION
1449 @item START_INFERIOR_TRAPS_EXPECTED
1453 @item STORE_RETURN_VALUE
1455 @item SUN4_COMPILER_FEATURE
1457 @item SUN_FIXED_LBRAC_BUG
1459 @item SVR4_SHARED_LIBS
1461 @item SWITCH_ENUM_BUG
1465 @item SYMBOL_RELOADING_DEFAULT
1485 @item TM_FILE_OVERRIDE
1501 @item USE_STRUCT_CONVENTION
1504 Means that System V (prior to SVR4) include files are in use.
1505 (FIXME: This symbol is abused in @file{infrun.c}, @file{regex.c},
1506 @file{remote-nindy.c}, and @file{utils.c} for other things, at the moment.)
1511 @item VARIABLES_INSIDE_BLOCK
1523 @item __HAVE_68881__
1527 @item __INT_VARARGS_H
1529 @item __not_on_pyr_yet
1545 @item longest_to_int
1575 @node Target Conditionals
1576 @chapter Target Conditionals
1578 When GDB is configured and compiled, various macros are defined or left
1579 undefined, to control compilation based on the attributes of the target
1580 system. These macros and their meanings are:
1582 @emph{NOTE: For now, both host and target conditionals are here.
1583 Eliminate host conditionals from this list as they are identified.}
1586 @item PUSH_DUMMY_FRAME
1587 Used in @samp{call_function_by_hand} to create an artificial stack frame.
1589 Used in @samp{call_function_by_hand} to remove an artificial stack frame.
1592 @item BLOCK_ADDRESS_FUNCTION_RELATIVE
1594 @item GDBINIT_FILENAME
1598 @item MEM_FNS_DECLARED
1602 @item PYRAMID_CONTROL_FRAME_DEBUGGING
1604 @item SIGWINCH_HANDLER_BODY
1606 @item ADDITIONAL_OPTIONS
1608 @item ADDITIONAL_OPTION_CASES
1610 @item ADDITIONAL_OPTION_HANDLER
1612 @item ADDITIONAL_OPTION_HELP
1614 @item ADDR_BITS_REMOVE
1616 @item ALIGN_STACK_ON_STARTUP
1628 @item BEFORE_MAIN_LOOP_HOOK
1630 @item BELIEVE_PCC_PROMOTION
1632 @item BELIEVE_PCC_PROMOTION_TYPE
1636 @item BITS_BIG_ENDIAN
1640 @item BLOCK_ADDRESS_ABSOLUTE
1646 @item BREAKPOINT_DEBUG
1652 @item CALL_DUMMY_LOCATION
1654 @item CALL_DUMMY_STACK_ADJUST
1656 @item CANNOT_FETCH_REGISTER
1658 @item CANNOT_STORE_REGISTER
1660 @item CFRONT_PRODUCER
1662 @item CHILD_PREPARE_TO_STORE
1664 @item CLEAR_DEFERRED_STORES
1668 @item COFF_ENCAPSULATE
1672 @item COFF_NO_LONG_FILE_NAMES
1674 @item CORE_NEEDS_RELOCATION
1678 @item CREATE_INFERIOR_HOOK
1688 @item DBX_PARM_SYMBOL_CLASS
1696 @item DECR_PC_AFTER_BREAK
1698 @item DEFAULT_PROMPT
1706 @item DISABLE_UNSETTABLE_BREAK
1708 @item DONT_USE_REMOTE
1710 @item DO_DEFERRED_STORES
1712 @item DO_REGISTERS_INFO
1714 @item END_OF_TEXT_DEFAULT
1718 @item EXTRACT_RETURN_VALUE
1720 @item EXTRACT_STRUCT_VALUE_ADDRESS
1722 @item EXTRA_FRAME_INFO
1724 @item EXTRA_SYMTAB_INFO
1726 @item FILES_INFO_HOOK
1741 Unused? 6-oct-92 rich@@cygnus.com. FIXME.
1742 @item FRAMELESS_FUNCTION_INVOCATION
1744 @item FRAME_ARGS_ADDRESS_CORRECT
1746 @item FRAME_CHAIN_COMBINE
1748 @item FRAME_CHAIN_VALID
1750 @item FRAME_CHAIN_VALID_ALTERNATE
1752 @item FRAME_FIND_SAVED_REGS
1754 @item FRAME_GET_BASEREG_VALUE
1756 @item FRAME_NUM_ARGS
1758 @item FRAME_SPECIFICATION_DYADIC
1760 @item FUNCTION_EPILOGUE_SIZE
1764 @item GCC2_COMPILED_FLAG_SYMBOL
1766 @item GCC_COMPILED_FLAG_SYMBOL
1768 @item GCC_MANGLE_BUG
1772 @item GDB_TARGET_IS_HPPA
1773 This determines whether horrible kludge code in dbxread.c and partial-stab.h
1774 is used to mangle multiple-symbol-table files from HPPA's. This should all
1775 be ripped out, and a scheme like elfread.c used.
1776 @item GDB_TARGET_IS_MACH386
1778 @item GDB_TARGET_IS_SUN3
1780 @item GDB_TARGET_IS_SUN386
1782 @item GET_LONGJMP_TARGET
1783 For most machines, this is a target-dependent parameter. On the DECstation
1784 and the Iris, this is a native-dependent parameter, since <setjmp.h> is
1785 needed to define it.
1787 This macro determines the target PC address that longjmp() will jump
1788 to, assuming that we have just stopped at a longjmp breakpoint. It
1789 takes a CORE_ADDR * as argument, and stores the target PC value through
1790 this pointer. It examines the current state of the machine as needed.
1791 @item GET_SAVED_REGISTER
1793 @item GPLUS_PRODUCER
1803 @item HAVE_REGISTER_WINDOWS
1805 @item HAVE_SIGSETMASK
1809 @item HEADER_SEEK_FD
1813 @item HOST_BYTE_ORDER
1817 @item HPUX_VERSION_5
1825 @item IBM6000_TARGET
1833 @item INIT_EXTRA_FRAME_INFO
1835 @item INIT_EXTRA_SYMTAB_INFO
1849 @item IN_SOLIB_TRAMPOLINE
1853 @item IS_TRAPPED_INTERNALVAR
1857 @item KERNEL_DEBUGGING
1875 @item MACHKERNELDEBUG
1881 @item MAINTENANCE_CMDS
1883 @item MAINTENANCE_CMDS
1889 @item NAMES_HAVE_UNDERSCORE
1893 @item NEED_POSIX_SETPGID
1895 @item NEED_TEXT_START_END
1909 @item NOTICE_SIGNAL_HANDLING_CHANGE
1911 @item NO_DEFINE_SYMBOL
1913 @item NO_HIF_SUPPORT
1915 @item NO_JOB_CONTROL
1917 @item NO_MALLOC_CHECK
1925 @item NO_SIGINTERRUPT
1927 @item NO_SINGLE_STEP
1935 @item NS32K_SVC_IMMED_OPERANDS
1937 @item NUMERIC_REG_NAMES
1945 @item ONE_PROCESS_WRITETEXT
1949 @item PCC_SOL_BROKEN
1951 @item PC_IN_CALL_DUMMY
1953 @item PC_LOAD_SEGMENT
1957 @item PRINT_RANDOM_SIGNAL
1959 @item PRINT_REGISTER_HOOK
1961 @item PRINT_TYPELESS_INTEGER
1963 @item PROCESS_LINENUMBER_HOOK
1965 @item PROLOGUE_FIRSTLINE_OVERLAP
1967 @item PSIGNAL_IN_SIGNAL_H
1971 @item PTRACE_ARG3_TYPE
1975 @item PUSH_ARGUMENTS
1977 @item REGISTER_BYTES
1979 @item REGISTER_NAMES
1981 @item REG_STACK_SEGMENT
1983 @item REG_STRUCT_HAS_ADDR
1991 @item SDB_REG_TO_REGNUM
1999 @item SET_STACK_LIMIT_HUGE
2001 @item SHELL_COMMAND_CONCAT
2005 @item SHIFT_INST_REGS
2007 @item SIGN_EXTEND_CHAR
2009 @item SIGTRAP_STOP_AFTER_LOAD
2013 @item SKIP_PROLOGUE_FRAMELESS_P
2015 @item SKIP_TRAMPOLINE_CODE
2019 @item SOLIB_CREATE_INFERIOR_HOOK
2021 @item SOME_NAMES_HAVE_DOT
2025 @item STAB_REG_TO_REGNUM
2029 @item STACK_DIRECTION
2031 @item START_INFERIOR_TRAPS_EXPECTED
2035 @item STORE_RETURN_VALUE
2037 @item SUN4_COMPILER_FEATURE
2039 @item SUN_FIXED_LBRAC_BUG
2041 @item SVR4_SHARED_LIBS
2043 @item SWITCH_ENUM_BUG
2047 @item SYMBOL_RELOADING_DEFAULT
2053 @item TARGET_BYTE_ORDER
2055 @item TARGET_CHAR_BIT
2057 @item TARGET_COMPLEX_BIT
2059 @item TARGET_DOUBLE_BIT
2061 @item TARGET_DOUBLE_COMPLEX_BIT
2063 @item TARGET_FLOAT_BIT
2065 @item TARGET_INT_BIT
2067 @item TARGET_LONG_BIT
2069 @item TARGET_LONG_DOUBLE_BIT
2071 @item TARGET_LONG_LONG_BIT
2073 @item TARGET_PTR_BIT
2075 @item TARGET_SHORT_BIT
2079 @item TM_FILE_OVERRIDE
2091 @item USE_STRUCT_CONVENTION
2097 @item VARIABLES_INSIDE_BLOCK
2107 @item __HAVE_68881__
2111 @item __INT_VARARGS_H
2113 @item __not_on_pyr_yet
2123 @item longest_to_int
2147 @node Native Conditionals
2148 @chapter Native Conditionals
2150 When GDB is configured and compiled, various macros are defined or left
2151 undefined, to control compilation when the host and target systems
2152 are the same. These macros should be defined (or left undefined)
2153 in @file{nm-@var{system}.h}.
2157 If defined, then gdb will include support for the @code{attach} and
2158 @code{detach} commands.
2159 @item FETCH_INFERIOR_REGISTERS
2160 Define this if the native-dependent code will provide its
2162 @code{fetch_inferior_registers} and @code{store_inferior_registers} in
2163 @file{@var{HOST}-nat.c}.
2164 If this symbol is @emph{not} defined, the default routines in
2165 @file{infptrace.c} are used for these functions.
2166 @item GET_LONGJMP_TARGET
2167 For most machines, this is a target-dependent parameter. On the DECstation
2168 and the Iris, this is a native-dependent parameter, since <setjmp.h> is
2169 needed to define it.
2171 This macro determines the target PC address that longjmp() will jump
2172 to, assuming that we have just stopped at a longjmp breakpoint. It
2173 takes a CORE_ADDR * as argument, and stores the target PC value through
2174 this pointer. It examines the current state of the machine as needed.
2176 Defines the format for the name of a @file{/proc} device. Should be
2177 defined in @file{nm.h} @emph{only} in order to override the default
2178 definition in @file{procfs.c}.
2179 @item REGISTER_U_ADDR
2180 Defines the offset of the registers in the ``u area''; @pxref{Host}.
2182 This determines whether small routines that translate register values
2183 to GDB's internal representation (from the /proc representation), and vice
2184 verse, are compiled.
2186 This is the offset of the registers in the upage. It need only be
2187 defined if the generic ptrace register access routines in
2188 @file{infptrace.c} are being used (that is,
2189 @code{FETCH_INFERIOR_REGISTERS} is not defined). If the default value
2190 from @file{infptrace.c} is good enough, leave it undefined.
2192 The default value means that u.u_ar0 @emph{points to} the location of the
2193 registers. I'm guessing that @code{#define U_REGS_OFFSET 0} means that
2194 u.u_ar0 @emph{is} the location of the registers.
2197 @node Obsolete Conditionals
2198 @chapter Obsolete Conditionals
2200 Fragments of old code in GDB sometimes reference or set the following
2201 configuration macros. They should not be used by new code, and
2202 old uses should be removed as those parts of the debugger are
2206 @item STACK_END_ADDR
2207 This macro used to define where the end of the stack appeared, for use
2208 in interpreting core file formats that don't record this address in the
2209 core file itself. This information is now configured in BFD, and GDB
2210 gets the info portably from there. The values in GDB's configuration
2211 files should be moved into BFD configuration files (if needed there),
2212 and deleted from all of GDB's config files.
2214 Any @file{@var{foo}-xdep.c} file that references STACK_END_ADDR
2215 is so old that it has never been converted to use BFD. Now that's old!