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 * Native:: Adding a New Native Configuration
75 * Target:: Adding a New Target
76 * Languages:: Defining New Source Languages
77 * Releases:: Configuring GDB for Release
78 * Partial Symbol Tables:: How GDB reads symbols quickly at startup
79 * BFD support for GDB:: How BFD and GDB interface
80 * Symbol Reading:: Defining New Symbol Readers
82 * Wrapping:: Wrapping Output Lines
83 * Frames:: Keeping track of function calls
84 * Coding Style:: Strunk and White for GDB maintainers
85 * Host Conditionals:: What features exist in the host
86 * Target Conditionals:: What features exist in the target
87 * Native Conditionals:: Conditionals for when host and target are same
88 * Obsolete Conditionals:: Conditionals that don't exist any more
93 @chapter The @file{README} File
95 Check the @file{README} file, it often has useful information that does not
96 appear anywhere else in the directory.
99 @node New Architectures
100 @chapter Defining a New Host or Target Architecture
102 When building support for a new host and/or target, much of the work you
103 need to do is handled by specifying configuration files;
104 @pxref{Config,,Adding a New Configuration}. Further work can be
105 divided into ``host-dependent'' (@pxref{Host,,Adding a New Host}) and
106 ``target-dependent'' (@pxref{Target,,Adding a New Target}). The
107 following discussion is meant to explain the difference between hosts
110 @heading What is considered ``host-dependent'' versus ``target-dependent''?
112 @dfn{Host} refers to attributes of the system where GDB runs.
113 @dfn{Target} refers to the system where the program being debugged
114 executes. In most cases they are the same machine, in which case
115 a third type of @dfn{Native} attributes come into play.
117 Defines and include files needed to build on the host are host support.
118 Examples are tty support, system defined types, host byte order, host
121 Defines and information needed to handle the target format are target
122 dependent. Examples are the stack frame format, instruction set,
123 breakpoint instruction, registers, and how to set up and tear down the stack
126 Information that is only needed when the host and target are the same,
127 is native dependent. One example is Unix child process support; if the
128 host and target are not the same, doing a fork to start the target
129 process is a bad idea. The various macros needed for finding the
130 registers in the @code{upage}, running @code{ptrace}, and such are all in the
131 native-dependent files.
133 Another example of native-dependent code is support for features
134 that are really part of the target environment, but which require
135 @code{#include} files that are only available on the host system.
136 Core file handling and @code{setjmp} handling are two common cases.
138 When you want to make GDB work ``native'' on a particular
139 machine, you have to include all three kinds of information.
141 The dependent information in GDB is organized into files by naming
147 Sets Makefile parameters
149 Global #include's and #define's and definitions
151 Global variables and functions
154 Native-Dependent Files
157 Sets Makefile parameters (for @emph{both} host and native)
159 #include's and #define's and definitions. This file
160 is only included by the small number of modules that need it,
161 so beware of doing feature-test #define's from its macros.
163 global variables and functions
166 Target-Dependent Files
169 Sets Makefile parameters
171 Global #include's and #define's and definitions
173 Global variables and functions
176 At this writing, most supported hosts have had their host and native
177 dependencies sorted out properly. There are a few stragglers, which
178 can be recognized by the absence of NATDEPFILES lines in their
182 @chapter Adding a New Configuration
184 Most of the work in making GDB compile on a new machine is in specifying
185 the configuration of the machine. This is done in a dizzying variety of
186 header files and configuration scripts, which we hope to make more
187 sensible soon. Let's say your new host is called an @var{xxx} (e.g.
188 @samp{sun4}), and its full three-part configuration name is
189 @code{@var{xarch}-@var{xvend}-@var{xos}} (e.g. @samp{sparc-sun-sunos4}). In
192 In the top level directory, edit @file{config.sub} and add @var{xarch},
193 @var{xvend}, and @var{xos} to the lists of supported architectures,
194 vendors, and operating systems near the bottom of the file. Also, add
195 @var{xxx} as an alias that maps to
196 @code{@var{xarch}-@var{xvend}-@var{xos}}. You can test your changes by
200 ./config.sub @var{xxx}
205 ./config.sub @code{@var{xarch}-@var{xvend}-@var{xos}}
208 which should both respond with @code{@var{xarch}-@var{xvend}-@var{xos}}
209 and no error messages.
211 Now, go to the @file{bfd} directory and
212 create a new file @file{bfd/hosts/h-@var{xxx}.h}. Examine the
213 other @file{h-*.h} files as templates, and create one that brings in the
214 right include files for your system, and defines any host-specific
215 macros needed by BFD, the Binutils, GNU LD, or the Opcodes directories.
216 (They all share the bfd @file{hosts} directory and the @file{configure.host}
219 Then edit @file{bfd/configure.host}. Add a line to recognize your
220 @code{@var{xarch}-@var{xvend}-@var{xos}} configuration, and set
221 @code{my_host} to @var{xxx} when you recognize it. This will cause your
222 file @file{h-@var{xxx}.h} to be linked to @file{sysdep.h} at configuration
223 time. When creating the line that recognizes your configuration,
224 only match the fields that you really need to match; e.g. don't match
225 match the architecture or manufacturer if the OS is sufficient
226 to distinguish the configuration that your @file{h-@var{xxx}.h} file supports.
227 Don't match the manufacturer name unless you really need to.
228 This should make future ports easier.
230 Also, if this host requires any changes to the Makefile, create a file
231 @file{bfd/config/@var{xxx}.mh}, which includes the required lines.
233 It's possible that the @file{libiberty} and @file{readline} directories
234 won't need any changes for your configuration, but if they do, you can
235 change the @file{configure.in} file there to recognize your system and
236 map to an @file{mh-@var{xxx}} file. Then add @file{mh-@var{xxx}}
237 to the @file{config/} subdirectory, to set any makefile variables you
238 need. The only current options in there are things like @samp{-DSYSV}.
239 (This @file{mh-@var{xxx}} naming convention differs from elsewhere
240 in GDB, by historical accident. It should be cleaned up so that all
241 such files are called @file{@var{xxx}.mh}.)
243 Aha! Now to configure GDB itself! Edit
244 @file{gdb/configure.in} to recognize your system and set @code{gdb_host}
245 to @var{xxx}, and (unless your desired target is already available) also
246 set @code{gdb_target} to something appropriate (for instance,
247 @var{xxx}). To handle new hosts, modify the segment after the comment
248 @samp{# per-host}; to handle new targets, modify after @samp{#
250 @c Would it be simpler to just use different per-host and per-target
251 @c *scripts*, and call them from {configure} ?
253 Finally, you'll need to specify and define GDB's host-, native-, and
254 target-dependent @file{.h} and @file{.c} files used for your
255 configuration; the next two chapters discuss those.
259 @chapter Adding a New Host
261 Once you have specified a new configuration for your host
262 (@pxref{Config,,Adding a New Configuration}), there are three remaining
263 pieces to making GDB work on a new machine. First, you have to make it
264 host on the new machine (compile there, handle that machine's terminals
265 properly, etc). If you will be cross-debugging to some other kind of
266 system that's already supported, you are done.
268 If you want to use GDB to debug programs that run on the new machine,
269 you have to get it to understand the machine's object files, symbol
270 files, and interfaces to processes; @pxref{Target,,Adding a New Target}
271 and @pxref{Native,,Adding a New Native Configuration}
273 Several files control GDB's configuration for host systems:
276 @item gdb/config/mh-@var{xxx}
277 Specifies Makefile fragments needed when hosting on machine @var{xxx}.
278 In particular, this lists the required machine-dependent object files,
279 by defining @samp{XDEPFILES=@dots{}}. Also
280 specifies the header file which describes host @var{xxx}, by defining
281 @samp{XM_FILE= xm-@var{xxx}.h}. You can also define @samp{CC},
282 @samp{REGEX} and @samp{REGEX1}, @samp{SYSV_DEFINE}, @samp{XM_CFLAGS},
283 @samp{XM_ADD_FILES}, @samp{XM_CLIBS}, @samp{XM_CDEPS},
284 etc.; see @file{Makefile.in}.
286 @item gdb/xm-@var{xxx}.h
287 (@file{xm.h} is a link to this file, created by configure).
288 Contains C macro definitions describing the host system environment,
289 such as byte order, host C compiler and library, ptrace support,
290 and core file structure. Crib from existing @file{xm-*.h} files
293 @item gdb/@var{xxx}-xdep.c
294 Contains any miscellaneous C code required for this machine
295 as a host. On many machines it doesn't exist at all. If it does
296 exist, put @file{@var{xxx}-xdep.o} into the @code{XDEPFILES} line
297 in @file{gdb/config/mh-@var{xxx}}.
300 @subheading Generic Host Support Files
302 There are some ``generic'' versions of routines that can be used by
303 various systems. These can be customized in various ways by macros
304 defined in your @file{xm-@var{xxx}.h} file. If these routines work for
305 the @var{xxx} host, you can just include the generic file's name (with
306 @samp{.o}, not @samp{.c}) in @code{XDEPFILES}.
308 Otherwise, if your machine needs custom support routines, you will need
309 to write routines that perform the same functions as the generic file.
310 Put them into @code{@var{xxx}-xdep.c}, and put @code{@var{xxx}-xdep.o}
311 into @code{XDEPFILES}.
315 This contains serial line support for Berkeley-derived Unix systems.
318 This contains serial line support for 32-bit programs running under DOS
319 using the GO32 execution environment.
322 This contains serial line support for System V-derived Unix systems.
325 Now, you are now ready to try configuring GDB to compile using your system
326 as its host. From the top level (above @file{bfd}, @file{gdb}, etc), do:
329 ./configure @var{xxx} +target=vxworks960
332 This will configure your system to cross-compile for VxWorks on
333 the Intel 960, which is probably not what you really want, but it's
334 a test case that works at this stage. (You haven't set up to be
335 able to debug programs that run @emph{on} @var{xxx} yet.)
337 If this succeeds, you can try building it all with:
343 Repeat until the program configures, compiles, links, and runs.
344 When run, it won't be able to do much (unless you have a VxWorks/960
345 board on your network) but you will know that the host support is
348 Good luck! Comments and suggestions about this section are particularly
349 welcome; send them to @samp{bug-gdb@@prep.ai.mit.edu}.
352 @chapter Adding a New Native Configuration
354 If you are making GDB run native on the @var{xxx} machine, you have
355 plenty more work to do. Several files control GDB's configuration for
359 @item gdb/config/@var{xxx}.mh
360 Specifies Makefile fragments needed when hosting @emph{or native}
361 on machine @var{xxx}.
362 In particular, this lists the required native-dependent object files,
363 by defining @samp{NATDEPFILES=@dots{}}. Also
364 specifies the header file which describes native support on @var{xxx},
365 by defining @samp{NM_FILE= nm-@var{xxx}.h}.
366 You can also define @samp{NAT_CFLAGS},
367 @samp{NAT_ADD_FILES}, @samp{NAT_CLIBS}, @samp{NAT_CDEPS},
368 etc.; see @file{Makefile.in}.
370 @item gdb/nm-@var{xxx}.h
371 (@file{nm.h} is a link to this file, created by configure).
372 Contains C macro definitions describing the native system environment,
373 such as child process control and core file support.
374 Crib from existing @file{nm-*.h} files to create a new one.
376 @item gdb/@var{xxx}-nat.c
377 Contains any miscellaneous C code required for this native support
378 of this machine. On some machines it doesn't exist at all.
381 @subheading Generic Native Support Files
383 There are some ``generic'' versions of routines that can be used by
384 various systems. These can be customized in various ways by macros
385 defined in your @file{nm-@var{xxx}.h} file. If these routines work for
386 the @var{xxx} host, you can just include the generic file's name (with
387 @samp{.o}, not @samp{.c}) in @code{NATDEPFILES}.
389 Otherwise, if your machine needs custom support routines, you will need
390 to write routines that perform the same functions as the generic file.
391 Put them into @code{@var{xxx}-nat.c}, and put @code{@var{xxx}-nat.o}
392 into @code{NATDEPFILES}.
397 This contains the @emph{target_ops vector} that supports Unix child
398 processes on systems which use ptrace and wait to control the child.
401 This contains the @emph{target_ops vector} that supports Unix child
402 processes on systems which use /proc to control the child.
405 This does the low-level grunge that uses Unix system calls
406 to do a "fork and exec" to start up a child process.
409 This is the low level interface to inferior processes for systems
410 using the Unix @code{ptrace} call in a vanilla way.
412 @item coredep.c::fetch_core_registers()
413 Support for reading registers out of a core file. This routine calls
414 @code{register_addr()}, see below.
415 Now that BFD is used to read core files, virtually all machines should
416 use @code{coredep.c}, and should just provide @code{fetch_core_registers} in
417 @code{@var{xxx}-nat.c} (or @code{REGISTER_U_ADDR} in @code{nm-@var{xxx}.h}).
419 @item coredep.c::register_addr()
420 If your @code{nm-@var{xxx}.h} file defines the macro
421 @code{REGISTER_U_ADDR(addr, blockend, regno)}, it should be defined to
422 set @code{addr} to the offset within the @samp{user}
423 struct of GDB register number @code{regno}. @code{blockend} is the
424 offset within the ``upage'' of @code{u.u_ar0}.
425 If @code{REGISTER_U_ADDR} is defined,
426 @file{coredep.c} will define the @code{register_addr()} function and use
427 the macro in it. If you do not define @code{REGISTER_U_ADDR}, but you
428 are using the standard @code{fetch_core_registers()}, you will need to
429 define your own version of @code{register_addr()}, put it into your
430 @code{@var{xxx}-nat.c} file, and be sure @code{@var{xxx}-nat.o} is in
431 the @code{NATDEPFILES} list. If you have your own
432 @code{fetch_core_registers()}, you may not need a separate
433 @code{register_addr()}. Many custom @code{fetch_core_registers()}
434 implementations simply locate the registers themselves.@refill
437 When making GDB run native on a new operating system,
438 to make it possible to debug
439 core files, you will need to either write specific code for parsing your
440 OS's core files, or customize @file{bfd/trad-core.c}. First, use
441 whatever @code{#include} files your machine uses to define the struct of
442 registers that is accessible (possibly in the u-area) in a core file
443 (rather than @file{machine/reg.h}), and an include file that defines whatever
444 header exists on a core file (e.g. the u-area or a @samp{struct core}). Then
445 modify @code{trad_unix_core_file_p()} to use these values to set up the
446 section information for the data segment, stack segment, any other
447 segments in the core file (perhaps shared library contents or control
448 information), ``registers'' segment, and if there are two discontiguous
449 sets of registers (e.g. integer and float), the ``reg2'' segment. This
450 section information basically delimits areas in the core file in a
451 standard way, which the section-reading routines in BFD know how to seek
454 Then back in GDB, you need a matching routine called
455 @code{fetch_core_registers()}. If you can use the generic one, it's in
456 @file{coredep.c}; if not, it's in your @file{@var{xxx}-nat.c} file.
457 It will be passed a char pointer to the entire ``registers'' segment,
458 its length, and a zero; or a char pointer to the entire ``regs2''
459 segment, its length, and a 2. The routine should suck out the supplied
460 register values and install them into GDB's ``registers'' array.
461 (@xref{New Architectures,,Defining a New Host or Target Architecture},
462 for more info about this.)
464 If your system uses @file{/proc} to control processes, and uses ELF
465 format core files, then you may be able to use the same routines
466 for reading the registers out of processes and out of core files.
469 @chapter Adding a New Target
471 For a new target called @var{ttt}, first specify the configuration as
472 described in @ref{Config,,Adding a New Configuration}. If your new
473 target is the same as your new host, you've probably already done that.
475 A variety of files specify attributes of the GDB target environment:
478 @item gdb/config/@var{ttt}.mt
479 Contains a Makefile fragment specific to this target.
480 Specifies what object files are needed for target @var{ttt}, by
481 defining @samp{TDEPFILES=@dots{}}.
482 Also specifies the header file which describes @var{ttt}, by defining
483 @samp{TM_FILE= tm-@var{ttt}.h}. You can also define @samp{TM_CFLAGS},
484 @samp{TM_CLIBS}, @samp{TM_CDEPS},
485 and other Makefile variables here; see @file{Makefile.in}.
487 @item gdb/tm-@var{ttt}.h
488 (@file{tm.h} is a link to this file, created by configure).
489 Contains macro definitions about the target machine's
490 registers, stack frame format and instructions.
491 Crib from existing @file{tm-*.h} files when building a new one.
493 @item gdb/@var{ttt}-tdep.c
494 Contains any miscellaneous code required for this target machine.
495 On some machines it doesn't exist at all. Sometimes the macros
496 in @file{tm-@var{ttt}.h} become very complicated, so they are
497 implemented as functions here instead, and the macro is simply
498 defined to call the function.
501 Defines functions for accessing files that are
502 executable on the target system. These functions open and examine an
503 exec file, extract data from one, write data to one, print information
504 about one, etc. Now that executable files are handled with BFD, every
505 target should be able to use the generic exec.c rather than its
508 @item gdb/@var{arch}-pinsn.c
509 Prints (disassembles) the target machine's instructions.
510 This file is usually shared with other target machines which use the
511 same processor, which is why it is @file{@var{arch}-pinsn.c} rather
512 than @file{@var{ttt}-pinsn.c}.
514 @item gdb/@var{arch}-opcode.h
515 Contains some large initialized
516 data structures describing the target machine's instructions.
517 This is a bit strange for a @file{.h} file, but it's OK since
518 it is only included in one place. @file{@var{arch}-opcode.h} is shared
519 between the debugger and the assembler, if the GNU assembler has been
520 ported to the target machine.
522 @item gdb/tm-@var{arch}.h
523 This often exists to describe the basic layout of the target machine's
524 processor chip (registers, stack, etc).
525 If used, it is included by @file{tm-@var{xxx}.h}. It can
526 be shared among many targets that use the same processor.
528 @item gdb/@var{arch}-tdep.c
529 Similarly, there are often common subroutines that are shared by all
530 target machines that use this particular architecture.
533 When adding support for a new target machine, there are various areas
534 of support that might need change, or might be OK.
536 If you are using an existing object file format (a.out or COFF),
537 there is probably little to be done. See @file{bfd/doc/bfd.texinfo}
538 for more information on writing new a.out or COFF versions.
540 If you need to add a new object file format, you are beyond the scope
541 of this document right now. Look at the structure of the a.out
542 and COFF support, build a transfer vector (@code{xvec}) for your new format,
543 and start populating it with routines. Add it to the list in
544 @file{bfd/targets.c}.
546 If you are adding a new operating system for an existing CPU chip, add a
547 @file{tm-@var{xos}.h} file that describes the operating system
548 facilities that are unusual (extra symbol table info; the breakpoint
549 instruction needed; etc). Then write a
550 @file{tm-@var{xarch}-@var{xos}.h} that just @code{#include}s
551 @file{tm-@var{xarch}.h} and @file{tm-@var{xos}.h}. (Now that we have
552 three-part configuration names, this will probably get revised to
553 separate the @var{xos} configuration from the @var{xarch}
558 @chapter Adding a Source Language to GDB
560 To add other languages to GDB's expression parser, follow the following steps:
563 @item Create the expression parser.
565 This should reside in a file @file{@var{lang}-exp.y}. Routines for building
566 parsed expressions into a @samp{union exp_element} list are in @file{parse.c}.
568 Since we can't depend upon everyone having Bison, and YACC produces
569 parsers that define a bunch of global names, the following lines
570 @emph{must} be included at the top of the YACC parser, to prevent
571 the various parsers from defining the same global names:
574 #define yyparse @var{lang}_parse
575 #define yylex @var{lang}_lex
576 #define yyerror @var{lang}_error
577 #define yylval @var{lang}_lval
578 #define yychar @var{lang}_char
579 #define yydebug @var{lang}_debug
580 #define yypact @var{lang}_pact
581 #define yyr1 @var{lang}_r1
582 #define yyr2 @var{lang}_r2
583 #define yydef @var{lang}_def
584 #define yychk @var{lang}_chk
585 #define yypgo @var{lang}_pgo
586 #define yyact @var{lang}_act
587 #define yyexca @var{lang}_exca
588 #define yyerrflag @var{lang}_errflag
589 #define yynerrs @var{lang}_nerrs
592 At the bottom of your parser, define a @code{struct language_defn} and
593 initialize it with the right values for your language. Define an
594 @code{initialize_@var{lang}} routine and have it call
595 @samp{add_language(@var{lang}_language_defn)} to tell the rest of GDB
596 that your language exists. You'll need some other supporting variables
597 and functions, which will be used via pointers from your
598 @code{@var{lang}_language_defn}. See the declaration of @code{struct
599 language_defn} in @file{language.h}, and the other @file{*-exp.y} files,
600 for more information.
602 @item Add any evaluation routines, if necessary
604 If you need new opcodes (that represent the operations of the language),
605 add them to the enumerated type in @file{expression.h}. Add support
606 code for these operations in @code{eval.c:evaluate_subexp()}. Add cases
607 for new opcodes in two functions from @file{parse.c}:
608 @code{prefixify_subexp()} and @code{length_of_subexp()}. These compute
609 the number of @code{exp_element}s that a given operation takes up.
611 @item Update some existing code
613 Add an enumerated identifier for your language to the enumerated type
614 @code{enum language} in @file{defs.h}.
616 Update the routines in @file{language.c} so your language is included. These
617 routines include type predicates and such, which (in some cases) are
618 language dependent. If your language does not appear in the switch
619 statement, an error is reported.
621 Also included in @file{language.c} is the code that updates the variable
622 @code{current_language}, and the routines that translate the
623 @code{language_@var{lang}} enumerated identifier into a printable
626 Update the function @code{_initialize_language} to include your language. This
627 function picks the default language upon startup, so is dependent upon
628 which languages that GDB is built for.
630 Update @code{allocate_symtab} in @file{symfile.c} and/or symbol-reading
631 code so that the language of each symtab (source file) is set properly.
632 This is used to determine the language to use at each stack frame level.
633 Currently, the language is set based upon the extension of the source
634 file. If the language can be better inferred from the symbol
635 information, please set the language of the symtab in the symbol-reading
638 Add helper code to @code{expprint.c:print_subexp()} to handle any new
639 expression opcodes you have added to @file{expression.h}. Also, add the
640 printed representations of your operators to @code{op_print_tab}.
642 @item Add a place of call
644 Add a call to @code{@var{lang}_parse()} and @code{@var{lang}_error} in
645 @code{parse.c:parse_exp_1()}.
647 @item Use macros to trim code
649 The user has the option of building GDB for some or all of the
650 languages. If the user decides to build GDB for the language
651 @var{lang}, then every file dependent on @file{language.h} will have the
652 macro @code{_LANG_@var{lang}} defined in it. Use @code{#ifdef}s to
653 leave out large routines that the user won't need if he or she is not
656 Note that you do not need to do this in your YACC parser, since if GDB
657 is not build for @var{lang}, then @file{@var{lang}-exp.tab.o} (the
658 compiled form of your parser) is not linked into GDB at all.
660 See the file @file{configure.in} for how GDB is configured for different
663 @item Edit @file{Makefile.in}
665 Add dependencies in @file{Makefile.in}. Make sure you update the macro
666 variables such as @code{HFILES} and @code{OBJS}, otherwise your code may
667 not get linked in, or, worse yet, it may not get @code{tar}red into the
673 @chapter Configuring GDB for Release
675 From the top level directory (containing @file{gdb}, @file{bfd},
676 @file{libiberty}, and so on):
678 make -f Makefile.in gdb.tar.Z
681 This will properly configure, clean, rebuild any files that are
682 distributed pre-built (e.g. @file{c-exp.tab.c} or @file{refcard.ps}),
683 and will then make a tarfile. (If the top level directory has already
684 beenn configured, you can just do @code{make gdb.tar.Z} instead.)
686 This procedure requires:
689 @item @code{makeinfo} (texinfo2 level)
692 @item @code{yacc} or @code{bison}
695 @dots{} and the usual slew of utilities (@code{sed}, @code{tar}, etc.).
697 @subheading TEMPORARY RELEASE PROCEDURE FOR DOCUMENTATION
699 @file{gdb.texinfo} is currently marked up using the texinfo-2 macros,
700 which are not yet a default for anything (but we have to start using
703 For making paper, the only thing this implies is the right generation of
704 @file{texinfo.tex} needs to be included in the distribution.
706 For making info files, however, rather than duplicating the texinfo2
707 distribution, generate @file{gdb-all.texinfo} locally, and include the files
708 @file{gdb.info*} in the distribution. Note the plural; @code{makeinfo} will
709 split the document into one overall file and five or so included files.
712 @node Partial Symbol Tables
713 @chapter Partial Symbol Tables
715 GDB has three types of symbol tables.
718 @item full symbol tables (symtabs). These contain the main
719 information about symbols and addresses.
720 @item partial symbol tables (psymtabs). These contain enough
721 information to know when to read the corresponding
722 part of the full symbol table.
723 @item minimal symbol tables (msymtabs). These contain information
724 gleaned from non-debugging symbols.
727 This section describes partial symbol tables.
729 A psymtab is constructed by doing a very quick pass over an executable
730 file's debugging information. Small amounts of information are
731 extracted -- enough to identify which parts of the symbol table will
732 need to be re-read and fully digested later, when the user needs the
733 information. The speed of this pass causes GDB to start up very
734 quickly. Later, as the detailed rereading occurs, it occurs in small
735 pieces, at various times, and the delay therefrom is mostly invisible to
736 the user. (@xref{Symbol Reading}.)
738 The symbols that show up in a file's psymtab should be, roughly, those
739 visible to the debugger's user when the program is not running code from
740 that file. These include external symbols and types, static
741 symbols and types, and enum values declared at file scope.
743 The psymtab also contains the range of instruction addresses that the
744 full symbol table would represent.
746 The idea is that there are only two ways for the user (or much of
747 the code in the debugger) to reference a symbol:
752 (e.g. execution stops at some address which is inside a function
753 in this file). The address will be noticed to be in the
754 range of this psymtab, and the full symtab will be read in.
755 @code{find_pc_function}, @code{find_pc_line}, and other @code{find_pc_@dots{}}
756 functions handle this.
759 (e.g. the user asks to print a variable, or set a breakpoint on a
760 function). Global names and file-scope names will be found in the
761 psymtab, which will cause the symtab to be pulled in. Local names will
762 have to be qualified by a global name, or a file-scope name, in which
763 case we will have already read in the symtab as we evaluated the
764 qualifier. Or, a local symbol can be referenced when
765 we are "in" a local scope, in which case the first case applies.
766 @code{lookup_symbol} does most of the work here.
770 The only reason that psymtabs exist is to cause a symtab to be read in
771 at the right moment. Any symbol that can be elided from a psymtab,
772 while still causing that to happen, should not appear in it. Since
773 psymtabs don't have the idea of scope, you can't put local symbols in
774 them anyway. Psymtabs don't have the idea of the type of a symbol,
775 either, so types need not appear, unless they will be referenced by
778 It is a bug for GDB to behave one way when only a psymtab has been read,
779 and another way if the corresponding symtab has been read in. Such
780 bugs are typically caused by a psymtab that does not contain all the
781 visible symbols, or which has the wrong instruction address ranges.
783 The psymtab for a particular section of a symbol-file (objfile)
784 could be thrown away after the symtab has been read in. The symtab
785 should always be searched before the psymtab, so the psymtab will
786 never be used (in a bug-free environment). Currently,
787 psymtabs are allocated on an obstack, and all the psymbols themselves
788 are allocated in a pair of large arrays on an obstack, so there is
789 little to be gained by trying to free them unless you want to do a lot
792 @node BFD support for GDB
793 @chapter Binary File Descriptor Library Support for GDB
795 BFD provides support for GDB in several ways:
798 @item identifying executable and core files
799 BFD will identify a variety of file types, including a.out, coff, and
800 several variants thereof, as well as several kinds of core files.
802 @item access to sections of files
803 BFD parses the file headers to determine the names, virtual addresses,
804 sizes, and file locations of all the various named sections in files
805 (such as the text section or the data section). GDB simply calls
806 BFD to read or write section X at byte offset Y for length Z.
808 @item specialized core file support
809 BFD provides routines to determine the failing command name stored
810 in a core file, the signal with which the program failed, and whether
811 a core file matches (i.e. could be a core dump of) a particular executable
814 @item locating the symbol information
815 GDB uses an internal interface of BFD to determine where to find the
816 symbol information in an executable file or symbol-file. GDB itself
817 handles the reading of symbols, since BFD does not ``understand'' debug
818 symbols, but GDB uses BFD's cached information to find the symbols,
822 @c The interface for symbol reading is described in @ref{Symbol
823 @c Reading,,Symbol Reading}.
827 @chapter Symbol Reading
829 GDB reads symbols from "symbol files". The usual symbol file is the
830 file containing the program which gdb is debugging. GDB can be directed
831 to use a different file for symbols (with the ``symbol-file''
832 command), and it can also read more symbols via the ``add-file'' and ``load''
833 commands, or while reading symbols from shared libraries.
835 Symbol files are initially opened by @file{symfile.c} using the BFD
836 library. BFD identifies the type of the file by examining its header.
837 @code{symfile_init} then uses this identification to locate a
838 set of symbol-reading functions.
840 Symbol reading modules identify themselves to GDB by calling
841 @code{add_symtab_fns} during their module initialization. The argument
842 to @code{add_symtab_fns} is a @code{struct sym_fns} which contains
843 the name (or name prefix) of the symbol format, the length of the prefix,
844 and pointers to four functions. These functions are called at various
845 times to process symbol-files whose identification matches the specified
848 The functions supplied by each module are:
851 @item @var{xxx}_symfile_init(struct sym_fns *sf)
853 Called from @code{symbol_file_add} when we are about to read a new
854 symbol file. This function should clean up any internal state
855 (possibly resulting from half-read previous files, for example)
856 and prepare to read a new symbol file. Note that the symbol file
857 which we are reading might be a new "main" symbol file, or might
858 be a secondary symbol file whose symbols are being added to the
859 existing symbol table.
861 The argument to @code{@var{xxx}_symfile_init} is a newly allocated
862 @code{struct sym_fns} whose @code{bfd} field contains the BFD
863 for the new symbol file being read. Its @code{private} field
864 has been zeroed, and can be modified as desired. Typically,
865 a struct of private information will be @code{malloc}'d, and
866 a pointer to it will be placed in the @code{private} field.
868 There is no result from @code{@var{xxx}_symfile_init}, but it can call
869 @code{error} if it detects an unavoidable problem.
871 @item @var{xxx}_new_init()
873 Called from @code{symbol_file_add} when discarding existing symbols.
874 This function need only handle
875 the symbol-reading module's internal state; the symbol table data
876 structures visible to the rest of GDB will be discarded by
877 @code{symbol_file_add}. It has no arguments and no result.
878 It may be called after @code{@var{xxx}_symfile_init}, if a new symbol
879 table is being read, or may be called alone if all symbols are
880 simply being discarded.
882 @item @var{xxx}_symfile_read(struct sym_fns *sf, CORE_ADDR addr, int mainline)
884 Called from @code{symbol_file_add} to actually read the symbols from a
885 symbol-file into a set of psymtabs or symtabs.
887 @code{sf} points to the struct sym_fns originally passed to
888 @code{@var{xxx}_sym_init} for possible initialization. @code{addr} is the
889 offset between the file's specified start address and its true address
890 in memory. @code{mainline} is 1 if this is the main symbol table being
891 read, and 0 if a secondary symbol file (e.g. shared library or
892 dynamically loaded file) is being read.@refill
895 In addition, if a symbol-reading module creates psymtabs when
896 @var{xxx}_symfile_read is called, these psymtabs will contain a pointer to
897 a function @code{@var{xxx}_psymtab_to_symtab}, which can be called from
898 any point in the GDB symbol-handling code.
901 @item @var{xxx}_psymtab_to_symtab (struct partial_symtab *pst)
903 Called from @code{psymtab_to_symtab} (or the PSYMTAB_TO_SYMTAB
904 macro) if the psymtab has not already been read in and had its
905 @code{pst->symtab} pointer set. The argument is the psymtab
906 to be fleshed-out into a symtab. Upon return, pst->readin
907 should have been set to 1, and pst->symtab should contain a
908 pointer to the new corresponding symtab, or zero if there
909 were no symbols in that part of the symbol file.
916 Cleanups are a structured way to deal with things that need to be done
917 later. When your code does something (like @code{malloc} some memory, or open
918 a file) that needs to be undone later (e.g. free the memory or close
919 the file), it can make a cleanup. The cleanup will be done at some
920 future point: when the command is finished, when an error occurs, or
921 when your code decides it's time to do cleanups.
923 You can also discard cleanups, that is, throw them away without doing
924 what they say. This is only done if you ask that it be done.
929 @item struct cleanup *@var{old_chain};
930 Declare a variable which will hold a cleanup chain handle.
932 @item @var{old_chain} = make_cleanup (@var{function}, @var{arg});
933 Make a cleanup which will cause @var{function} to be called with @var{arg}
934 (a @code{char *}) later. The result, @var{old_chain}, is a handle that can be
935 passed to @code{do_cleanups} or @code{discard_cleanups} later. Unless you are
936 going to call @code{do_cleanups} or @code{discard_cleanups} yourself,
937 you can ignore the result from @code{make_cleanup}.
940 @item do_cleanups (@var{old_chain});
941 Perform all cleanups done since @code{make_cleanup} returned @var{old_chain}.
945 old = make_cleanup (b, 0);
949 will call @code{b()} but will not call @code{a()}. The cleanup that calls @code{a()} will remain
950 in the cleanup chain, and will be done later unless otherwise discarded.@refill
952 @item discard_cleanups (@var{old_chain});
953 Same as @code{do_cleanups} except that it just removes the cleanups from the
954 chain and does not call the specified functions.
958 Some functions, e.g. @code{fputs_filtered()} or @code{error()}, specify that they
959 ``should not be called when cleanups are not in place''. This means
960 that any actions you need to reverse in the case of an error or
961 interruption must be on the cleanup chain before you call these functions,
962 since they might never return to your code (they @samp{longjmp} instead).
966 @chapter Wrapping Output Lines
968 Output that goes through @code{printf_filtered} or @code{fputs_filtered} or
969 @code{fputs_demangled} needs only to have calls to @code{wrap_here} added
970 in places that would be good breaking points. The utility routines
971 will take care of actually wrapping if the line width is exceeded.
973 The argument to @code{wrap_here} is an indentation string which is printed
974 @emph{only} if the line breaks there. This argument is saved away and used
975 later. It must remain valid until the next call to @code{wrap_here} or
976 until a newline has been printed through the @code{*_filtered} functions.
977 Don't pass in a local variable and then return!
979 It is usually best to call @code{wrap_here()} after printing a comma or space.
980 If you call it before printing a space, make sure that your indentation
981 properly accounts for the leading space that will print if the line wraps
984 Any function or set of functions that produce filtered output must finish
985 by printing a newline, to flush the wrap buffer, before switching to
986 unfiltered (``@code{printf}'') output. Symbol reading routines that print
987 warnings are a good example.
993 A frame is a construct that GDB uses to keep track of calling and called
998 in the machine description has no meaning to the machine-independent
999 part of GDB, except that it is used when setting up a new frame from
1000 scratch, as follows:
1003 create_new_frame (read_register (FP_REGNUM), read_pc ()));
1006 Other than that, all the meaning imparted to @code{FP_REGNUM} is imparted by
1007 the machine-dependent code. So, @code{FP_REGNUM} can have any value that
1008 is convenient for the code that creates new frames. (@code{create_new_frame}
1009 calls @code{INIT_EXTRA_FRAME_INFO} if it is defined; that is where you should
1010 use the @code{FP_REGNUM} value, if your frames are nonstandard.)
1013 Given a GDB frame, determine the address of the calling function's
1014 frame. This will be used to create a new GDB frame struct, and then
1015 @code{INIT_EXTRA_FRAME_INFO} and @code{INIT_FRAME_PC} will be called for
1020 @chapter Coding Style
1022 GDB is generally written using the GNU coding standards, as described in
1023 @file{standards.texi}, which you can get from the Free Software
1024 Foundation. There are some additional considerations for GDB maintainers
1025 that reflect the unique environment and style of GDB maintenance.
1026 If you follow these guidelines, GDB will be more consistent and easier
1029 GDB's policy on the use of prototypes is that prototypes are used
1030 to @emph{declare} functions but never to @emph{define} them. Simple
1031 macros are used in the declarations, so that a non-ANSI compiler can
1032 compile GDB without trouble. The simple macro calls are used like
1037 memory_remove_breakpoint PARAMS ((CORE_ADDR, char *));
1040 Note the double parentheses around the parameter types. This allows
1041 an arbitrary number of parameters to be described, without freaking
1042 out the C preprocessor. When the function has no parameters, it
1043 should be described like:
1047 noprocess PARAMS ((void));
1050 The @code{PARAMS} macro expands to its argument in ANSI C, or to a simple
1051 @code{()} in traditional C.
1053 All external functions should have a @code{PARAMS} declaration in a
1054 header file that callers include. All static functions should have such
1055 a declaration near the top of their source file.
1057 We don't have a gcc option that will properly check that these rules
1058 have been followed, but it's GDB policy, and we periodically check it
1059 using the tools available (plus manual labor), and clean up any remnants.
1061 @node Host Conditionals
1062 @chapter Host Conditionals
1064 When GDB is configured and compiled, various macros are defined or left
1065 undefined, to control compilation based on the attributes of the host
1066 system. These macros and their meanings are:
1068 @emph{NOTE: For now, both host and target conditionals are here.
1069 Eliminate target conditionals from this list as they are identified.}
1074 @item BLOCK_ADDRESS_FUNCTION_RELATIVE
1076 @item GDBINIT_FILENAME
1080 @item MEM_FNS_DECLARED
1084 @item PYRAMID_CONTROL_FRAME_DEBUGGING
1086 @item SIGWINCH_HANDLER_BODY
1104 @item ADDITIONAL_OPTIONS
1106 @item ADDITIONAL_OPTION_CASES
1108 @item ADDITIONAL_OPTION_HANDLER
1110 @item ADDITIONAL_OPTION_HELP
1112 @item ADDR_BITS_REMOVE
1114 @item AIX_BUGGY_PTRACE_CONTINUE
1116 @item ALIGN_STACK_ON_STARTUP
1128 @item BEFORE_MAIN_LOOP_HOOK
1130 @item BELIEVE_PCC_PROMOTION
1132 @item BELIEVE_PCC_PROMOTION_TYPE
1136 @item BITS_BIG_ENDIAN
1140 @item BLOCK_ADDRESS_ABSOLUTE
1146 @item BREAKPOINT_DEBUG
1148 @item BROKEN_LARGE_ALLOCA
1149 Avoid large @code{alloca}'s. For example, on sun's, Large alloca's fail
1150 because the attempt to increase the stack limit in main() fails because
1151 shared libraries are allocated just below the initial stack limit. The
1152 SunOS kernel will not allow the stack to grow into the area occupied by
1153 the shared libraries.
1158 @item CALL_DUMMY_LOCATION
1160 @item CALL_DUMMY_STACK_ADJUST
1162 @item CANNOT_FETCH_REGISTER
1164 @item CANNOT_STORE_REGISTER
1166 @item CFRONT_PRODUCER
1168 @item CHILD_PREPARE_TO_STORE
1170 @item CLEAR_DEFERRED_STORES
1174 @item COFF_ENCAPSULATE
1178 @item COFF_NO_LONG_FILE_NAMES
1180 @item CORE_NEEDS_RELOCATION
1184 @item CREATE_INFERIOR_HOOK
1194 @item DBX_PARM_SYMBOL_CLASS
1202 @item DECR_PC_AFTER_BREAK
1204 @item DEFAULT_PROMPT
1212 @item DISABLE_UNSETTABLE_BREAK
1214 @item DONT_USE_REMOTE
1216 @item DO_DEFERRED_STORES
1218 @item DO_REGISTERS_INFO
1220 @item END_OF_TEXT_DEFAULT
1224 @item EXTRACT_RETURN_VALUE
1226 @item EXTRACT_STRUCT_VALUE_ADDRESS
1228 @item EXTRA_FRAME_INFO
1230 @item EXTRA_SYMTAB_INFO
1232 @item FILES_INFO_HOOK
1246 @item FRAMELESS_FUNCTION_INVOCATION
1248 @item FRAME_ARGS_ADDRESS_CORRECT
1250 @item FRAME_CHAIN_COMBINE
1252 @item FRAME_CHAIN_VALID
1254 @item FRAME_CHAIN_VALID_ALTERNATE
1256 @item FRAME_FIND_SAVED_REGS
1258 @item FRAME_GET_BASEREG_VALUE
1260 @item FRAME_NUM_ARGS
1262 @item FRAME_SPECIFICATION_DYADIC
1264 @item FUNCTION_EPILOGUE_SIZE
1268 @item GCC2_COMPILED_FLAG_SYMBOL
1270 @item GCC_COMPILED_FLAG_SYMBOL
1272 @item GCC_MANGLE_BUG
1276 @item GET_SAVED_REGISTER
1278 @item GPLUS_PRODUCER
1289 In some cases, use the system call @code{mmap} for reading symbol
1290 tables. For some machines this allows for sharing and quick updates.
1291 @item HAVE_REGISTER_WINDOWS
1293 @item HAVE_SIGSETMASK
1297 @item HEADER_SEEK_FD
1301 @item HOST_BYTE_ORDER
1305 @item HPUX_VERSION_5
1313 @item IBM6000_TARGET
1321 @item INIT_EXTRA_FRAME_INFO
1323 @item INIT_EXTRA_SYMTAB_INFO
1337 @item IN_SOLIB_TRAMPOLINE
1341 @item IS_TRAPPED_INTERNALVAR
1345 @item KERNEL_DEBUGGING
1348 Define this to the address of the @code{u} structure (the ``user struct'',
1349 also known as the ``u-page'') in kernel virtual memory. GDB needs to know
1350 this so that it can subtract this address from absolute addresses in
1351 the upage, that are obtained via ptrace or from core files. On systems
1352 that don't need this value, set it to zero.
1353 @item KERNEL_U_ADDR_BSD
1354 Define this to cause GDB to determine the address of @code{u} at runtime,
1355 by using Berkeley-style @code{nlist} on the kernel's image in the root
1357 @item KERNEL_U_ADDR_HPUX
1358 Define this to cause GDB to determine the address of @code{u} at runtime,
1359 by using HP-style @code{nlist} on the kernel's image in the root
1375 @item LSEEK_NOT_LINEAR
1380 This macro is used as the argument to lseek (or, most commonly, bfd_seek).
1381 FIXME, it should be replaced by SEEK_SET instead, which is the POSIX equivalent.
1382 @item MACHKERNELDEBUG
1388 @item MAINTENANCE_CMDS
1390 @item MAINTENANCE_CMDS
1392 @item MALLOC_INCOMPATIBLE
1393 Define this if the system's prototype for @code{malloc} differs from the
1394 @sc{ANSI} definition.
1397 @item MMAP_BASE_ADDRESS
1398 When using HAVE_MMAP, the first mapping should go at this address.
1399 @item MMAP_INCREMENT
1400 when using HAVE_MMAP, this is the increment between mappings.
1405 @item NAMES_HAVE_UNDERSCORE
1409 @item NEED_POSIX_SETPGID
1411 @item NEED_TEXT_START_END
1425 @item NOTICE_SIGNAL_HANDLING_CHANGE
1427 @item NO_DEFINE_SYMBOL
1429 @item NO_HIF_SUPPORT
1431 @item NO_JOB_CONTROL
1433 @item NO_MALLOC_CHECK
1441 @item NO_SIGINTERRUPT
1443 @item NO_SINGLE_STEP
1451 @item NS32K_SVC_IMMED_OPERANDS
1453 @item NUMERIC_REG_NAMES
1461 @item ONE_PROCESS_WRITETEXT
1469 @item PCC_SOL_BROKEN
1471 @item PC_IN_CALL_DUMMY
1473 @item PC_LOAD_SEGMENT
1477 @item PRINT_RANDOM_SIGNAL
1479 @item PRINT_REGISTER_HOOK
1481 @item PRINT_TYPELESS_INTEGER
1483 @item PROCESS_LINENUMBER_HOOK
1485 @item PROLOGUE_FIRSTLINE_OVERLAP
1487 @item PSIGNAL_IN_SIGNAL_H
1491 @item PTRACE_ARG3_TYPE
1501 @item PUSH_ARGUMENTS
1503 @item PYRAMID_CONTROL_FRAME_DEBUGGING
1507 @item PYRAMID_PTRACE
1509 @item REGISTER_BYTES
1511 @item REGISTER_NAMES
1513 @item REG_STACK_SEGMENT
1515 @item REG_STRUCT_HAS_ADDR
1523 @item SDB_REG_TO_REGNUM
1531 @item SET_STACK_LIMIT_HUGE
1532 When defined, stack limits will be raised to their maximum. Use this
1533 if your host supports @code{setrlimit} and you have trouble with
1534 @code{stringtab} in @file{dbxread.c}.
1536 Also used in @file{fork-child.c} to return stack limits before child
1537 processes are forked.
1538 @item SHELL_COMMAND_CONCAT
1542 @item SHIFT_INST_REGS
1544 @item SIGN_EXTEND_CHAR
1546 @item SIGTRAP_STOP_AFTER_LOAD
1550 @item SKIP_PROLOGUE_FRAMELESS_P
1552 @item SKIP_TRAMPOLINE_CODE
1556 @item SOLIB_CREATE_INFERIOR_HOOK
1558 @item SOME_NAMES_HAVE_DOT
1562 @item STAB_REG_TO_REGNUM
1566 @item STACK_DIRECTION
1568 @item START_INFERIOR_TRAPS_EXPECTED
1572 @item STORE_RETURN_VALUE
1574 @item SUN4_COMPILER_FEATURE
1576 @item SUN_FIXED_LBRAC_BUG
1578 @item SVR4_SHARED_LIBS
1580 @item SWITCH_ENUM_BUG
1584 @item SYMBOL_RELOADING_DEFAULT
1604 @item TM_FILE_OVERRIDE
1620 @item USE_STRUCT_CONVENTION
1623 Means that System V (prior to SVR4) include files are in use.
1624 (FIXME: This symbol is abused in @file{infrun.c}, @file{regex.c},
1625 @file{remote-nindy.c}, and @file{utils.c} for other things, at the moment.)
1630 @item VARIABLES_INSIDE_BLOCK
1642 @item __HAVE_68881__
1646 @item __INT_VARARGS_H
1648 @item __not_on_pyr_yet
1664 @item longest_to_int
1694 @node Target Conditionals
1695 @chapter Target Conditionals
1697 When GDB is configured and compiled, various macros are defined or left
1698 undefined, to control compilation based on the attributes of the target
1699 system. These macros and their meanings are:
1701 @emph{NOTE: For now, both host and target conditionals are here.
1702 Eliminate host conditionals from this list as they are identified.}
1705 @item PUSH_DUMMY_FRAME
1706 Used in @samp{call_function_by_hand} to create an artificial stack frame.
1708 Used in @samp{call_function_by_hand} to remove an artificial stack frame.
1711 @item BLOCK_ADDRESS_FUNCTION_RELATIVE
1713 @item GDBINIT_FILENAME
1717 @item MEM_FNS_DECLARED
1721 @item PYRAMID_CONTROL_FRAME_DEBUGGING
1723 @item SIGWINCH_HANDLER_BODY
1725 @item ADDITIONAL_OPTIONS
1727 @item ADDITIONAL_OPTION_CASES
1729 @item ADDITIONAL_OPTION_HANDLER
1731 @item ADDITIONAL_OPTION_HELP
1733 @item ADDR_BITS_REMOVE
1735 @item ALIGN_STACK_ON_STARTUP
1747 @item BEFORE_MAIN_LOOP_HOOK
1749 @item BELIEVE_PCC_PROMOTION
1751 @item BELIEVE_PCC_PROMOTION_TYPE
1755 @item BITS_BIG_ENDIAN
1759 @item BLOCK_ADDRESS_ABSOLUTE
1765 @item BREAKPOINT_DEBUG
1771 @item CALL_DUMMY_LOCATION
1773 @item CALL_DUMMY_STACK_ADJUST
1775 @item CANNOT_FETCH_REGISTER
1777 @item CANNOT_STORE_REGISTER
1779 @item CFRONT_PRODUCER
1781 @item CHILD_PREPARE_TO_STORE
1783 @item CLEAR_DEFERRED_STORES
1787 @item COFF_ENCAPSULATE
1791 @item COFF_NO_LONG_FILE_NAMES
1793 @item CORE_NEEDS_RELOCATION
1797 @item CREATE_INFERIOR_HOOK
1807 @item DBX_PARM_SYMBOL_CLASS
1815 @item DECR_PC_AFTER_BREAK
1817 @item DEFAULT_PROMPT
1825 @item DISABLE_UNSETTABLE_BREAK
1827 @item DONT_USE_REMOTE
1829 @item DO_DEFERRED_STORES
1831 @item DO_REGISTERS_INFO
1833 @item END_OF_TEXT_DEFAULT
1837 @item EXTRACT_RETURN_VALUE
1839 @item EXTRACT_STRUCT_VALUE_ADDRESS
1841 @item EXTRA_FRAME_INFO
1843 @item EXTRA_SYMTAB_INFO
1845 @item FILES_INFO_HOOK
1860 Unused? 6-oct-92 rich@@cygnus.com. FIXME.
1861 @item FRAMELESS_FUNCTION_INVOCATION
1863 @item FRAME_ARGS_ADDRESS_CORRECT
1865 @item FRAME_CHAIN_COMBINE
1867 @item FRAME_CHAIN_VALID
1869 @item FRAME_CHAIN_VALID_ALTERNATE
1871 @item FRAME_FIND_SAVED_REGS
1873 @item FRAME_GET_BASEREG_VALUE
1875 @item FRAME_NUM_ARGS
1877 @item FRAME_SPECIFICATION_DYADIC
1879 @item FUNCTION_EPILOGUE_SIZE
1883 @item GCC2_COMPILED_FLAG_SYMBOL
1885 @item GCC_COMPILED_FLAG_SYMBOL
1887 @item GCC_MANGLE_BUG
1891 @item GDB_TARGET_IS_HPPA
1892 This determines whether horrible kludge code in dbxread.c and partial-stab.h
1893 is used to mangle multiple-symbol-table files from HPPA's. This should all
1894 be ripped out, and a scheme like elfread.c used.
1895 @item GDB_TARGET_IS_MACH386
1897 @item GDB_TARGET_IS_SUN3
1899 @item GDB_TARGET_IS_SUN386
1901 @item GET_LONGJMP_TARGET
1902 For most machines, this is a target-dependent parameter. On the DECstation
1903 and the Iris, this is a native-dependent parameter, since <setjmp.h> is
1904 needed to define it.
1906 This macro determines the target PC address that longjmp() will jump
1907 to, assuming that we have just stopped at a longjmp breakpoint. It
1908 takes a CORE_ADDR * as argument, and stores the target PC value through
1909 this pointer. It examines the current state of the machine as needed.
1910 @item GET_SAVED_REGISTER
1912 @item GPLUS_PRODUCER
1922 @item HAVE_REGISTER_WINDOWS
1924 @item HAVE_SIGSETMASK
1928 @item HEADER_SEEK_FD
1932 @item HOST_BYTE_ORDER
1936 @item HPUX_VERSION_5
1944 @item IBM6000_TARGET
1952 @item INIT_EXTRA_FRAME_INFO
1954 @item INIT_EXTRA_SYMTAB_INFO
1968 @item IN_SOLIB_TRAMPOLINE
1972 @item IS_TRAPPED_INTERNALVAR
1976 @item KERNEL_DEBUGGING
1994 @item MACHKERNELDEBUG
2000 @item MAINTENANCE_CMDS
2002 @item MAINTENANCE_CMDS
2008 @item NAMES_HAVE_UNDERSCORE
2012 @item NEED_POSIX_SETPGID
2014 @item NEED_TEXT_START_END
2028 @item NOTICE_SIGNAL_HANDLING_CHANGE
2030 @item NO_DEFINE_SYMBOL
2032 @item NO_HIF_SUPPORT
2034 @item NO_JOB_CONTROL
2036 @item NO_MALLOC_CHECK
2044 @item NO_SIGINTERRUPT
2046 @item NO_SINGLE_STEP
2054 @item NS32K_SVC_IMMED_OPERANDS
2056 @item NUMERIC_REG_NAMES
2064 @item ONE_PROCESS_WRITETEXT
2068 @item PCC_SOL_BROKEN
2070 @item PC_IN_CALL_DUMMY
2072 @item PC_LOAD_SEGMENT
2076 @item PRINT_RANDOM_SIGNAL
2078 @item PRINT_REGISTER_HOOK
2080 @item PRINT_TYPELESS_INTEGER
2082 @item PROCESS_LINENUMBER_HOOK
2084 @item PROLOGUE_FIRSTLINE_OVERLAP
2086 @item PSIGNAL_IN_SIGNAL_H
2090 @item PTRACE_ARG3_TYPE
2094 @item PUSH_ARGUMENTS
2096 @item REGISTER_BYTES
2098 @item REGISTER_NAMES
2100 @item REG_STACK_SEGMENT
2102 @item REG_STRUCT_HAS_ADDR
2110 @item SDB_REG_TO_REGNUM
2118 @item SET_STACK_LIMIT_HUGE
2120 @item SHELL_COMMAND_CONCAT
2124 @item SHIFT_INST_REGS
2126 @item SIGN_EXTEND_CHAR
2128 @item SIGTRAP_STOP_AFTER_LOAD
2132 @item SKIP_PROLOGUE_FRAMELESS_P
2134 @item SKIP_TRAMPOLINE_CODE
2138 @item SOLIB_CREATE_INFERIOR_HOOK
2140 @item SOME_NAMES_HAVE_DOT
2144 @item STAB_REG_TO_REGNUM
2148 @item STACK_DIRECTION
2150 @item START_INFERIOR_TRAPS_EXPECTED
2154 @item STORE_RETURN_VALUE
2156 @item SUN4_COMPILER_FEATURE
2158 @item SUN_FIXED_LBRAC_BUG
2160 @item SVR4_SHARED_LIBS
2162 @item SWITCH_ENUM_BUG
2166 @item SYMBOL_RELOADING_DEFAULT
2172 @item TARGET_BYTE_ORDER
2174 @item TARGET_CHAR_BIT
2176 @item TARGET_COMPLEX_BIT
2178 @item TARGET_DOUBLE_BIT
2180 @item TARGET_DOUBLE_COMPLEX_BIT
2182 @item TARGET_FLOAT_BIT
2184 @item TARGET_INT_BIT
2186 @item TARGET_LONG_BIT
2188 @item TARGET_LONG_DOUBLE_BIT
2190 @item TARGET_LONG_LONG_BIT
2192 @item TARGET_PTR_BIT
2194 @item TARGET_SHORT_BIT
2198 @item TM_FILE_OVERRIDE
2210 @item USE_STRUCT_CONVENTION
2216 @item VARIABLES_INSIDE_BLOCK
2226 @item __HAVE_68881__
2230 @item __INT_VARARGS_H
2232 @item __not_on_pyr_yet
2242 @item longest_to_int
2266 @node Native Conditionals
2267 @chapter Native Conditionals
2269 When GDB is configured and compiled, various macros are defined or left
2270 undefined, to control compilation when the host and target systems
2271 are the same. These macros should be defined (or left undefined)
2272 in @file{nm-@var{system}.h}.
2276 If defined, then gdb will include support for the @code{attach} and
2277 @code{detach} commands.
2278 @item FETCH_INFERIOR_REGISTERS
2279 Define this if the native-dependent code will provide its
2281 @code{fetch_inferior_registers} and @code{store_inferior_registers} in
2282 @file{@var{HOST}-nat.c}.
2283 If this symbol is @emph{not} defined, and @file{infptrace.c}
2284 is included in this configuration, the default routines in
2285 @file{infptrace.c} are used for these functions.
2286 @item GET_LONGJMP_TARGET
2287 For most machines, this is a target-dependent parameter. On the DECstation
2288 and the Iris, this is a native-dependent parameter, since <setjmp.h> is
2289 needed to define it.
2291 This macro determines the target PC address that longjmp() will jump
2292 to, assuming that we have just stopped at a longjmp breakpoint. It
2293 takes a CORE_ADDR * as argument, and stores the target PC value through
2294 this pointer. It examines the current state of the machine as needed.
2296 Defines the format for the name of a @file{/proc} device. Should be
2297 defined in @file{nm.h} @emph{only} in order to override the default
2298 definition in @file{procfs.c}.
2299 @item REGISTER_U_ADDR
2300 Defines the offset of the registers in the ``u area''; @pxref{Host}.
2302 This determines whether small routines in @file{*-tdep.c}, which
2303 translate register values
2304 between GDB's internal representation and the /proc representation,
2307 This is the offset of the registers in the upage. It need only be
2308 defined if the generic ptrace register access routines in
2309 @file{infptrace.c} are being used (that is,
2310 @file{infptrace.c} is configured in, and
2311 @code{FETCH_INFERIOR_REGISTERS} is not defined). If the default value
2312 from @file{infptrace.c} is good enough, leave it undefined.
2314 The default value means that u.u_ar0 @emph{points to} the location of the
2315 registers. I'm guessing that @code{#define U_REGS_OFFSET 0} means that
2316 u.u_ar0 @emph{is} the location of the registers.
2319 @node Obsolete Conditionals
2320 @chapter Obsolete Conditionals
2322 Fragments of old code in GDB sometimes reference or set the following
2323 configuration macros. They should not be used by new code, and
2324 old uses should be removed as those parts of the debugger are
2328 @item STACK_END_ADDR
2329 This macro used to define where the end of the stack appeared, for use
2330 in interpreting core file formats that don't record this address in the
2331 core file itself. This information is now configured in BFD, and GDB
2332 gets the info portably from there. The values in GDB's configuration
2333 files should be moved into BFD configuration files (if needed there),
2334 and deleted from all of GDB's config files.
2336 Any @file{@var{foo}-xdep.c} file that references STACK_END_ADDR
2337 is so old that it has never been converted to use BFD. Now that's old!